science

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: the default model, the need for an API key to probe Anthropic, and the return format (per-model score, confidence, signals, raw_response). 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 four sentences, front-loaded with the main action and output, then efficient details on models and API key. No unnecessary words; every sentence earns its place.

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

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

Given moderate complexity (4 parameters, 1 required) and no output schema, the description covers essential usage: default model, optional models, API key condition, and return structure (per-model data + combined view). Annotations add safety context. Complete enough for correct invocation.

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

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

Schema description coverage is 100% with clear parameter descriptions. The description enriches semantics by explaining the default model, how _apiKey enables Anthropic, and the role of context for disambiguation. This goes beyond what the schema alone provides.

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

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

The description clearly states the tool's primary purpose: probing LLMs to score visibility for a business/brand/product/topic. It uses a specific verb ('probe'), identifies the resource ('LLMs'), and describes the output (score 0-100). It also distinguishes from siblings like scan_competitor_ai_presence by focusing on multi-model scoring and API key option.

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

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

The description explains when to use the tool (AI-marketing audits, pre-launch brand checks, competitive monitoring) and provides guidance on model selection: default free model vs. Anthropic with BYO key. However, it does not explicitly contrast with siblings like ask_pipeworx or scan_competitor_ai_presence, leaving some ambiguity.

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 context about routing to 3,775 sources, returning stable citation URIs, and filling arguments. Adds value beyond annotations.

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

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

Description is front-loaded with key usage guidance and includes examples. While lengthy, every sentence adds value. Could be slightly more concise but 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 single required parameter, no output schema, and rich annotations, the description fully covers what the tool does, when to use it, and expected behavior. Examples further clarify.

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 multiple aliases described. Description does not add additional parameter meaning beyond what schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool routes questions to authoritative sources and returns structured answers. It distinguishes from web search and sibling tools like 'ask_pipeworx_grounded' by emphasizing preference for factual, structured data with citations.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and lists specific query types (SEC filings, FDA data, etc.) and example queries. Provides clear when-to-use guidance and examples.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds valuable behavioral details: it produces explicit refusal reasons ('not_in_source', etc.), explains the extraction process, and specifies the output structure. No contradiction with annotations.

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

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

The description is informative but somewhat lengthy. It is front-loaded with the core purpose, followed by details and use cases. Every sentence adds value, though some could be condensed without loss. Overall, efficient for the amount of context needed.

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 (no output schema, multiple refusal types, high-stakes use), the description is complete. It explains the return format, possible refusal reasons, and external behavior (cost, routing). The agent can fully understand when and how to invoke the tool.

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

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

Schema coverage is 100% and includes multiple aliases for 'question' with clear descriptions. The description does not add much parameter-specific meaning beyond what the schema provides, though it notes the routing parallels 'ask_pipeworx' which implies the same input handling. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a 'hallucination-resistant answer mode for high-stakes reads'. It specifies that it extracts answers only from tool results, distinguishing it from its sibling 'ask_pipeworx' by noting the extra LLM call and use case. The verb 'extracts' and resource 'answer' with evidence are precise.

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 an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'). Also mentions the cost trade-off (one extra LLM call) and lists contexts where fact-invention is unacceptable (financial verdicts, legal claims, etc.).

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 extensive behavioral details beyond annotations: market resolution, classification, fan-out logic, response shapes, error conditions (low confidence, closed markets, wide spreads), cancellation risk, and safety mechanisms. Much richer than readOnlyHint alone.

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?

Long but well-structured with clear sections (CLASSIFIERS, FAN-OUT, RESPONSE SHAPES, etc.). Front-loaded with core purpose; detail is appropriate for complexity. Could be slightly more concise but not overly verbose.

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

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

Comprehensive coverage for a complex tool without output schema. Describes all response fields (market, analysis, evidence, match confidence, parent event, news fields) and edge cases (low confidence, closed markets, wide spreads, cancellation rules). No significant 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 covers all parameters with 100% description coverage. Description adds value by explaining market input formats, default depth, and when to use include_raw (response size trade-off). Adds meaningful context beyond schema.

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

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

Clearly states it researches a Polymarket bet by pulling Pipeworx data in one call. Lists specific use cases and distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage.

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

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

Explicitly states when to use: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Could further contrast with other research tools but is sufficiently clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorted results, and citation URIs. No contradictions.

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

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

The description is a single dense paragraph. It front-loads the purpose but could be more structured (e.g., bullet points for examples). Every sentence adds value, but readability could be improved.

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

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

Without an output schema, the description only vaguely mentions 'paired data + pipeworx:// citation URIs'. It does not specify the exact structure or metrics. For a tool with two simple parameters, this is somewhat sufficient but leaves room for ambiguity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds examples (e.g., 'AAPL','MSFT') and explains what data each type retrieves, providing meaning beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single call. It provides example phrases and explicitly says 'ALWAYS PREFER over sequential single-pack lookups', effectively distinguishing it from siblings like entity_profile.

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

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

The description explicitly tells when to use this tool (when comparing entities) and advises preferring it over sequential lookups. It doesn't explicitly state when not to use it or mention alternatives, but the guidance is clear and actionable.

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

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

Adds context beyond annotations: describes parallel execution, evidence with citations, gaps array for unanswered facets, typical latency (15-60s), and account/plan requirements. Annotations already cover safety (readOnlyHint) and idempotency, so description supplements with process and output details.

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

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

The description is lengthy but front-loaded with the core action and then structured with process, usage, requirements, and output details. Every sentence adds value, though could be slightly more concise for a quick skim.

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 multi-source research, the description covers purpose, mechanism, output format (findings packet with evidence and gaps), usage guidance, prerequisites, and alternatives. No output schema exists, but the description compensates adequately. Complete enough for an agent to decide and invoke correctly.

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

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

Schema has 100% coverage, but description adds value by explaining depth enum values (quick=3, standard=5, thorough=8) and that thorough requires a paid plan. Also clarifies that the question should be broad/multi-part. This goes beyond the schema descriptions.

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

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

The description clearly states the tool performs multi-source research by decomposing questions and running parallel sub-queries. It explicitly distinguishes from sibling ask_pipeworx, which is for single lookups.

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

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

Provides explicit guidance: use for broad/multi-part questions, with examples. Directly names the alternative tool (ask_pipeworx) for simpler queries. Also notes account and plan requirements for depth levels.

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 top-N relevant tools with full schemas and examples, and that results are ready to call directly. This adds valuable behavioral context beyond annotations.

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

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

The description is two sentences long, front-loaded with purpose, and each sentence serves a clear function. No extraneous 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 is a meta-tool with good annotations and full schema coverage, the description explains what it returns (top-N tools with schemas) and how to use it (call first). It compensates for the lack of output schema by describing the return format.

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

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

Schema description coverage is 100%, so baseline is 3. The description provides examples of queries but does not add substantially new meaning beyond the schema's parameter descriptions and aliases.

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 'Find tools by describing the data or task' with specific verbs (browse, search, look up, discover) and a specific resource (tools). It distinguishes itself from sibling tools by being a meta-tool that returns other 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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It provides clear context for when to use, but does not explicitly mention when not to use or alternatives.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds behavioral context: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields, mentions soft-fail for patents, and explains it runs in one parallel call. No contradiction.

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

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

The description is informative but slightly long. However, it is well-structured with examples, purpose, behavior, and parameter details. Each sentence earns its place, though could be more streamlined.

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

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

Given the complexity of aggregating multiple sources and no output schema, the description thoroughly explains what returns are expected (cik, filings, fundamentals, patents, news, LEI), including limitations (patents soft-fail, no names, only company type). It is complete for an agent to understand the tool's capabilities.

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 meaning: type is only 'company', value must be ticker or zero-padded CIK, not names. It also explains why names are not supported and suggests resolve_entity, going beyond the schema.

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

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

The description clearly states the tool provides a holistic profile of a US public company. It uses specific verbs like 'profile' and 'fans out', and distinguishes from siblings by explicitly preferring over chaining and referencing resolve_entity for names.

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

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

The description provides explicit usage guidance: use when the user asks for a holistic view, prefer over chaining other tools, and if only a name is available, use resolve_entity first. It includes examples of user queries.

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data and pairing, which enhances transparency without contradicting annotations.

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

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

Two sentences, front-loaded with action and usage conditions. 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?

Simple tool with one parameter well-documented in schema, annotations cover safety, and description provides complete usage context and sibling references.

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 already describes parameter 'key' as 'Memory key to delete' with 100% coverage. Description only mentions 'by key', adding no extra semantics.

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

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

The description states 'Delete a previously stored memory by key' which clearly identifies the action and resource. It distinguishes from siblings 'remember' and 'recall' through pairing advice.

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 context is stale, task is done, or to clear sensitive data. Also pairs with sibling tools 'remember' and 'recall'.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by detailing the process (fetches page, extracts title/description/links, emits markdown). 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 sentences: one for purpose and use cases, one for process, one for output format. No unnecessary words, front-loaded with key 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 tool with clearly described parameters and output, the description provides all needed context. No output schema but return value is well-described as a single text blob.

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 and max_links). The description repeats that the URL can be any URL but does not add new semantic detail 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 generates a production-ready llms.txt file for any URL, distinguishes it from siblings like 'scan_competitor_ai_presence' and 'ai_visibility_check' which are about analysis, not generation.

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 use cases (indexing client sites, drafting for own project, auditing competitors) but does not mention when not to use or alternative tools. Still provides clear context for appropriate 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 declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds that it returns specific metrics but discloses no additional behavioral traits like rate limits, data freshness, or restrictions. With annotations, the bar is lower, and the description adds minimal extra 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 two sentences, front-loaded with purpose and examples, and efficiently lists return values. 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 presence of an output schema and annotations, the description is fairly complete. It covers what the tool does and what it returns. Minor missing context could be data source or region limitations, 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?

Schema coverage is 100% with simple descriptions for latitude and longitude. The description does not add deeper meaning beyond the schema; it restates the location concept with examples. Baseline 3 is appropriate as the description adds little semantic value.

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

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

The description clearly states the tool checks air quality at a location and lists the specific pollutants returned (AQI, PM2.5, PM10, ozone, NO2). It distinguishes itself from sibling tools like get_apod or get_earthquakes by focusing on air quality.

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

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

The description gives a clear use case but does not provide guidance on when to use this tool versus alternatives or mention any limitations or exclusions. No explicit when-to-use or when-not-to-use information.

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 false. The description adds specific outputs (image URL, title, explanation) but does not disclose potential API key requirements, rate limits, or error behavior. Additional context would improve transparency.

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

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

Single sentence with parenthetical example, front-loaded with key information. 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 simplicity (1 optional param, output schema exists), description covers main functionality and return values. Minor gap: no mention of error handling for invalid dates or missing images.

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

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

Schema coverage is 100% and the schema clearly describes the 'date' parameter with format and default. The description adds an example but no meaningful extra semantics beyond the schema.

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

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

Description clearly states 'Get NASA's Astronomy Picture of the Day' with specific outputs (image URL, title, explanation). Verb and resource are specific and distinguishable from siblings, which are unrelated.

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 implies usage for fetching APOD but does not provide explicit guidance on when to use vs alternatives, or when not to use. Since no similar sibling tools exist, this gap is less critical but still limits clarity.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is clear. The description adds that it returns specific fields (magnitude, depth, coordinates, timestamp) and focuses on 'recent' earthquakes, which is mildly helpful but not a major behavioral disclosure beyond what annotations provide.

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

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

Two sentences, no fluff, front-loaded with the verb and resource. Every sentence provides value. Excellent conciseness.

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

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

The description mentions 'by location' but no location parameter exists, creating a gap. It does list return fields, but with an output schema present, that is partially redundant. Overall, it is adequate but not fully complete due to the missing location 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% with descriptions for both parameters (days and min_magnitude). The description does not add any additional meaning or context beyond what is already in the input schema, so it meets the baseline.

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

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

The description states 'Search recent earthquakes by location and magnitude threshold', but the input schema only includes days and min_magnitude parameters, with no location parameter. This mismatch makes the purpose somewhat vague and potentially misleading. However, it does clearly indicate that the tool searches for earthquakes and lists some return fields.

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

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

The description implies usage (when you need earthquake data by magnitude and time range) but does not explicitly state when to use this tool vs alternatives. No exclusions or alternative tools are mentioned, though sibling tools are unrelated.

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, etc. The description adds that it returns specific fields (latitude, longitude, altitude, velocity), which provides some behavioral context but does not go into detail about data freshness or rate limits.

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 sentence, front-loaded with the primary action, 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?

With zero parameters, high annotation coverage, and an output schema, the description provides all necessary context: what it does and what it 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?

No parameters exist, so the schema already covers all. Baseline 4 per rules.

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

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

The description clearly states the tool gets the current ISS position and lists the return fields (latitude, longitude, altitude, velocity). It uses a specific verb-resource pair ('Get Iss Location') and is distinct from sibling tools like get_air_quality or get_earthquakes.

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. It does not describe prerequisites, context, or exclusions.

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

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

Annotations already indicate readOnly, idempotent, not destructive. Description adds that it lists only active by default and includes an optional include_inactive parameter, plus lists return fields, providing behavioral context beyond annotations.

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

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

Two sentences, front-loaded, no unnecessary words. Every sentence provides value.

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

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

Given no output schema, description lists all return fields. Also mentions parameter behavior. Satisfies information needs for agent to understand result format.

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

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

Schema covers the single parameter fully (description present). Description doesn't add extra semantics beyond implying active vs inactive, 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?

Clearly states 'List the caller's active subscriptions' with specific verb and resource, and lists return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear guidance on when to use the tool.

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

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

Discloses rate-limiting (5 per identifier per day), that it's free and doesn't count against quota, and that the team reads digests daily. 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?

Well-structured with front-loaded purpose, but slightly verbose. Could be tightened slightly without losing clarity.

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

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

Given 3 parameters (including nested object), description covers usage, behavioral constraints, and parameter semantics. No output schema, but feedback tools typically have minimal 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?

Schema coverage is 100% and description adds meaning: explains the enum values for 'type', specifies message length (2000 chars), and clarifies that context is optional.

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's for sending feedback to the Pipeworx team about bugs, missing features, or praise. It distinguishes itself from sibling tools, none of which are feedback-related.

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

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

Provides explicit guidance on when to use each type (bug, feature, data_gap, praise) and what not to include (end-user prompt). Mentions rate limits and quota-free 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 declare readOnlyHint, openWorldHint, and idempotentHint. The description adds value by explaining the data source (CF analytics-engine), lack of PII, and caching behavior (5min-1h). No contradiction.

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

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

The description is a single, well-structured paragraph with no extraneous words. It begins with the core functionality and then provides use cases and additional context efficiently.

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 input (one optional parameter) and rich annotations, the description covers data source, privacy, and caching. No output schema exists, but the description explains return fields sufficiently.

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 detailed description for the window parameter. The main description reiterates the parameter's role. No additional parameter semantics are needed beyond what schema provides.

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

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

The description clearly states that the tool returns top tools, packs, and total call volume for a recent window. The verb 'returns' and resource 'trending data' are specific. It distinguishes from siblings like 'ask_pipeworx' and 'discover_tools' by focusing on usage frequency.

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?

Three explicit use cases are listed, providing clear context for when to use the tool. However, it does not mention when to avoid it or point to alternative tools for other purposes.

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?

Extensively describes internal logic: monotonicity checks, partition_sum, Jaccard similarity, placeholder filter, fill check with CLOB depth. Discloses that call fails with no args. No contradiction with annotations (all read/idempotent/open hints are consistent).

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 requirement and high-level purpose. While dense, every sentence contributes; some technical details (Jaccard, partition filter) could be secondary but are relevant. Slightly verbose but well-organized.

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

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

Given no output schema, the description fully describes the response structure (opportunities array, partition_check, fill_check). It also addresses edge cases (no args failure, placeholder filtering). Complete for a complex arbitrage detection 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 descriptions are already informative and cover 100% of parameters. The description adds significant context: examples of slugs, explanation of how each mode works internally, and criteria like Jaccard similarity. Enhances understanding beyond schema.

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

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

Clearly states it finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. Distinguishes two modes (event and topic), making the verb-resource-action explicit.

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

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

Provides clear guidance on when to use each mode (event for specific market, topic for cross-event scanning). Mentions that cross-event mode catches patterns single-event misses. Includes hint about using polymarket_fill_risk for custom sizing. Does not explicitly compare with other Polymarket sibling tools, but the tool's purpose is unique.

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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description extensively adds behavioral context: caching behavior (1h at KV level), diagnostic output, segment details, and filter knobs. No contradiction with annotations.

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

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

The description is long but densely packed with valuable information, front-loading purpose and systematically explaining segments. Every sentence adds value, though minor trimming could improve conciseness without losing substance.

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

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

Given the tool's complexity (9 parameters, three model families, no output schema), the description is remarkably complete. It explains output structure (by_segment, fed_candidates, diagnostics), model details, filter knobs, and includes warnings like 24h-move indicator. No output schema is needed due to thorough description.

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

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

Schema coverage is 100%, so baseline is 3. The description adds beyond schema by explaining parameter interactions (e.g., min_kelly vs min_partition_leg_kelly) and usage context for tradeable-edge filters, enhancing meaning for agent invocation.

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

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

The description explicitly states it scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a clear use case: 'what should I bet on today'. It differentiates from sibling tools like polymarket_arbitrage and polymarket_kalshi_spread by focusing on edge opportunities across three model families.

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

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

The description provides clear context for when to use the tool (discovering opportunities) but lacks explicit when-not-to-use instructions or comparisons with alternatives like polymarket_arbitrage. It implies usage for agents seeking betting edges but does not guide on excluding scenarios.

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

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

Annotations already indicate safe read operations. Description adds context about snapshot frequency, decay computation, and data gaps, which is useful 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?

Thorough but verbose; every sentence adds value, but could be more streamlined. Response structure is clearly explained.

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

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

With no output schema, description fully explains the response structure (tracked[], expired[], snapshot_dates[]) and important caveats (decay from daily closes, not intraday). 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 covers both parameters fully. Description adds defaults and clarifications (max days, snapshot family options) and explains why snapshot dates may have gaps.

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 it provides edge persistence and decay telemetry from daily snapshots. Distinguishes from sibling tools by focusing on historical data and trend analysis.

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

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

Explains when to use it (comparing fresh vs. stale edges) and provides limits (60-day TTL, snapshot gaps). 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=true, idempotentHint=true, destructiveHint=false. The description goes far beyond these by detailing the internal behavior: walks the ladder, compares top-of-book vs VWAP, returns fields like slippage, fillability, verdict, and warns about thin legs and forced directional risk. No contradiction with annotations.

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

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

The description is dense but well-organized with labeled sections (SINGLE-MARKET:, BASKET:). It front-loads the purpose and requirements. Every sentence adds necessary information for a complex tool with two modes; no 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?

Despite no output schema, the description exhaustively lists return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket). It also covers edge cases like thin books and partial fills, making the tool's behavior fully transparent.

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

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

Although schema description coverage is 100%, the tool description adds significant value: it explains the conditional relationship between market and event parameters (two modes), interprets size_usd differently for single-market (max spend/target proceeds) vs basket (settlement notional), and describes default behavior for side. This goes well 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 performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two modes (single-market and basket) and explicitly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by saying 'USE THIS before acting on any ... signal or any polymarket_edges trade above ~$500.' The verb-resource pair is specific: check edge against order book.

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: before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or polymarket_edges trades above ~$500. It explains the rationale—theoretical overround on thin books is unattainable and partial basket fills convert arb into unhedged directional positions. It also provides mode-selection guidance: 'REQUIRES one of market or event'.

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

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

The description extensively covers behavior: two modes, response format (leg-by-leg prices, spreads in percentage points), safety fields (compatibility_warning cases, temporal_alignment, skipped counters). It explains when spreads are meaningful (aligned, matched pairs) and when they are not. 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 lengthy but efficient, with each sentence adding value. It is front-loaded with purpose, then modes, response, and safety details. Minor redundancy could be trimmed, 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?

For a tool with no output schema and three parameters, the description covers all necessary context: purpose, modes, response structure, safety fields, corner cases, and warnings. No gaps remain.

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

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

All three parameters are fully described in the schema (100% coverage). The description adds significant context: mode switching, list of pre-mapped topics, override behavior, and implications of combinations.

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 the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, with two distinct modes (topic shortcuts and explicit event IDs). It clearly distinguishes its function from sibling tools like polymarket_arbitrage and bet_research.

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

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

The description explains when to use each mode and warns that pre-mapped topics often yield compatibility warnings, implying limited tradeability. It provides guidance on interpreting safety fields but could more explicitly state when not to use the tool or suggest alternatives.

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

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

Annotations already indicate readOnlyHint, destructiveHint, and idempotentHint. The description adds value by explaining scoping to 'your identifier (anonymous IP, BYO key hash, or account ID)', providing behavioral context beyond the annotations.

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

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

The description is concise (3 sentences) and front-loaded with the core function. Each sentence serves a purpose: functionality, use case, and additional context. 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 a single optional parameter, no output schema, and the tool's simplicity, the description provides complete information for an AI agent to understand and invoke the tool correctly. It covers retrieval, listing, scoping, and pairing with sibling tools.

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

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

The schema has 100% coverage with a description for the optional 'key' parameter. The description reinforces that omitting the key lists all saved keys, which matches the schema. No additional parameter details are needed, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: retrieve a saved value or list all keys. It specifies the verb 'retrieve' and the resource 'value previously saved via remember', and distinguishes it from sibling tools like 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?

The description provides clear usage context: 'look up context the agent stored earlier' with concrete examples. It mentions pairing with remember and forget but does not explicitly state when not to use it, which is a minor gap.

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 behavioral context like mark_read flagging events as read for subsequent calls, which provides value beyond annotations. No contradictions.

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

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

The description is reasonably concise at 4-5 sentences, front-loading the core purpose. Each sentence adds value, though some users might find the mention of an alternative URL slightly tangential. 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 the tool has 5 parameters and no output schema, the description adequately covers behavior, filtering, and side effects of mark_read. It is complete enough for an agent to understand usage without ambiguity.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds contextual meaning beyond the schema, e.g., specifying that type expects a subscription type like 'sec_8k' and that mark_read affects future calls. This enhances 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 it pulls fired events from the subscription feed, specifying what is returned (source, citation_uri, raw event payload). However, it does not explicitly differentiate from sibling tools like list_subscriptions or subscribe, which reduces clarity for selection.

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

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

It explains filtering by type and since, the mark_read behavior, and notes that polling is fine. It also mentions an alternative access method (URL for scripts). But it lacks explicit guidance on when not to use this tool versus alternatives like list_subscriptions.

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

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

Annotations indicate read-only and non-destructive behavior, but the description adds substantial detail: fan-out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), fallback logic, soft-fail for USPTO, and a structured return format with citation URIs.

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 densely informative, with example queries leading. Every sentence contributes value. Minor redundancy could be trimmed, 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?

Despite no output schema, the description details the return structure (changes[] grouped by source, total_changes, citation URIs). All important behaviors (sources, fallbacks, limitations) are covered, making the tool fully understandable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context: since accepts relative shorthand ('7d','30d','3m','1y'), type is limited to 'company', value can be ticker or CIK. 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 states it's a change feed for a company over a time window, and explicitly distinguishes from entity_profile. The example queries ('What's new with X') make the purpose immediately understandable.

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, including example queries and a clear directive to use entity_profile for static profiles regardless of time 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 provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. Description adds persistence details: authenticated users get persistent memory, anonymous sessions retain 24 hours. No contradictions, but could mention overwriting 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?

Five sentences, front-loaded with main purpose, no unnecessary words. Each sentence adds value.

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

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

Given tool complexity (simple key-value store), description covers usage, persistence, sibling relationships, and parameter semantics. No output schema needed; complete for 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?

Input schema has 100% coverage with descriptions for key and value. Description adds practical examples of keys (subject_property, target_ticker) and values (findings, addresses), enhancing semantic 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?

Clearly states verb 'Save' and resource 'data', specifies scope 'across this conversation or across sessions'. Distinguishes from siblings by mentioning '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?

Explicitly says 'Use when you discover something worth carrying forward' and provides concrete examples. Also instructs to pair with recall and forget for retrieval and deletion.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds value by explaining internal cascading lookups, auto-disambiguation, and citation URI generation. However, it does not discuss error handling or rate limits.

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

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

The description is front-loaded with examples and structured by type, but is slightly verbose (e.g., repeating 'returns ticker + 10-digit CIK + company_name'). Every sentence adds value, but could be tightened.

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

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

Given the tool's moderate complexity (2 params, no output schema), the description thoroughly covers return values, supported entity types, input variations, and internal efficiency gains. Nothing important is omitted.

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 significantly enriches parameter meaning. It details what each type returns (e.g., ticker + CIK for company, RxCUI for drug) and clarifies acceptable input formats (ticker, CIK, name for company; brand/generic for drug). This goes well beyond 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 resolves names to canonical/official identifiers, with specific examples like 'What's the ticker for…' and 'find the CIK for…'. It distinguishes itself from sibling tools by its unique function of providing IDs needed by other tools, and lists two explicit entity types (company, drug) with detailed return values.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It does not explicitly state when not to use or mention alternatives, but given the unique purpose, this is a minor gap.

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, idempotent, non-destructive. The description adds behavioral details: it calls ai_visibility_check per entity, ranks results, and returns a list with score, confidence, signal density. No contradictions with annotations.

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

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

Four sentences that are front-loaded with the main action, no fluff. Every sentence adds value: action, process, example, output fields. 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?

For a comparative tool with 4 parameters and no output schema, the description adequately covers input semantics, process, and output (ranked list with score, confidence, signal density). Could be slightly more precise about output format, but 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 has 100% coverage, but the description adds semantic meaning: 'entities' first entry is subject, 'models' defaults, '_apiKey' optional for Anthropic, 'context' disambiguates. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes itself from sibling tool ai_visibility_check by being a comparative version.

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

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

The description provides a clear use case (competitive AI-marketing audits) and an example. However, it does not explicitly state when not to use this tool or list alternative tools, though the context of sibling tools implies alternatives.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description adds behavioral details: fans out to two external services, 5-30s timeout on bundlephobia first measurement, partial failures with sources_failed list, and the structure of the response (summary, per-advisory, links, 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 informative but lengthy. It is well-structured with a clear lead sentence, then details, usage guidelines, limitations, and failure behavior. Every sentence adds value, though it could be slightly more concise without losing essential 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 composite nature, no output schema, and potential failures, the description is thorough. It covers the return format, timeout behavior, ecosystem limitations, and fallback paths. All needed context for an agent to use it correctly is present.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra context: scoped packages like '@types/node' are accepted for 'package', and 'version' defaults to latest. This modest addition justifies a 4.

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

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

The description clearly states it is a composite check for npm packages covering deps.dev and bundlephobia, with a specific verb-resource (scan_dependency) and distinct purpose: evaluating safety, popularity, size. It lists exact return fields, making it 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 says 'Use whenever an agent asks "is X safe / popular / small"' and notes when not to use it: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' Also explains partial failure behavior, giving clear context for decision-making.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description details the embedding model (BGE-base-en), windowing (500-char overlapping), similarity metric (cosine), and character cap (200K chars with truncation flagging). This adds significant 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?

The description is a single, well-structured paragraph of six sentences. It front-loads the purpose, then provides usage guidance, pairs with a sibling, and ends with technical details. No extraneous 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 tool without an output schema, the description explains the return format (passages with offsets and scores), limitations (character cap), and pairing with ask_pipeworx_grounded. It covers most necessary context, though it could explicitly state the default limit 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%, so the baseline is 3. The description adds qualitative use-case context for the 'text' and 'query' parameters but does not add new syntactic details 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: 'Semantic search INSIDE a fetched record.' It specifies the verb ('search inside') and resource ('fetched record'), and distinguishes itself from siblings like ask_pipeworx_grounded by explaining how it complements that tool.

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

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

The description explicitly advises when to use the tool: 'Use when the record is too big to cram into the prompt.' It also provides an alternative workflow partner, ask_pipeworx_grounded. However, it does not mention when not to use it or compare with other siblings.

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

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

Discloses that the tool creates a subscription (mutates state), requires an authenticated account, and has rate limits (SMS cap of 10/day) and side effects (webhook auto-disable). No contradiction with annotations; adds context beyond annotations.

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

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

Description is well-structured with a clear opening sentence followed by detailed sections. Slightly verbose but every sentence contributes useful 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 complexity (3 parameters, nested objects, no output schema), the description covers all necessary aspects: purpose, auth requirements, type-specific filters, delivery options with constraints, and return value. 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?

The description significantly enriches the input schema by providing concrete examples for each subscription type and clarifying delivery channel requirements (e.g., phone verification, webhook signature details). Schema coverage is 100%, but the description adds valuable context not present in 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?

Clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. Distinguishes from sibling tools like list_subscriptions or unsubscribe.

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

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

Provides explicit guidance on required account type (Pipeworx OAuth), supported types with examples, and delivery channel constraints (SMS verification, webhook auto-disable). Lacks explicit when-not-to-use instructions but effectively communicates prerequisites.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral details: returns category-bucketed example questions with exact tool+argument shapes from a live catalog. No contradictions.

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

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

The description is front-loaded with common user questions and contains all necessary information, though it is slightly verbose. Each sentence contributes value.

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

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

Despite lacking an output schema, the description explains the return format (category-bucketed examples) and mentions the live catalog. Combined with annotations, it provides sufficient context for a beginner tool.

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

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

Schema coverage is 100%, and the description adds examples of valid topic values (finance, pharma, etc.) and the effect of omitting the parameter (cross-category spread). This exceeds the baseline of 3.

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

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

The description clearly states the tool's purpose: an onboarding entry point that returns category-bucketed example questions when the agent doesn't know what Pipeworx can do. It distinguishes itself from siblings by specifying its role as a first-use tool for discovering capabilities.

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

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

Explicitly advises 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions it can teach how to call meta-tools. This provides clear context and 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?

Adds ownership enforcement, deactivation (not deletion), and historical event preservation, all beyond annotations. No contradiction with annotations.

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

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

Two concise sentences with main action first, 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?

Covers all relevant aspects (ownership, behavioral effect, relation to recent_alerts) given tool simplicity and no output schema.

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

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

Schema coverage is 100% and description reinforces parameter purpose ('id returned by subscribe'). No additional parameter info needed.

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

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

Description clearly states action ('Cancel a subscription by id') and resource, distinguishing from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Provides ownership enforcement and behavioral details, but does not explicitly state when to use vs alternatives; however, context is sufficient given the simple operation.

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 safe, idempotent, read-only behavior. The description adds detail on return values (verdict types, citation, delta) and the replacement of multiple calls, providing additional context beyond annotations.

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

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

The description is moderately long but well-structured: intent examples first, then purpose, scope, and outputs. Every sentence contributes useful information, though minor tightening is 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 the single parameter, no output schema, and clear annotations, the description fully covers what the tool does, its limitations (US public company financials), and what it returns. No gaps remain for agent decision-making.

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 good parameter description. The description reinforces by providing concrete examples of valid claims, adding semantic value without being redundant.

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

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

The description clearly identifies the tool as a claim verifier for company-financial claims via SEC EDGAR + XBRL, with explicit user intent mappings. It distinguishes itself by replacing 4–6 sequential calls, making its purpose unique among 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 states to use it 'whenever the agent needs to check factual correctness' and specifies the domain (US public company financials). It does not explicitly state when not to use, but the scope is clear enough for appropriate selection.

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