Timeapi Io

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

Annotations already declare readOnly, idempotent, and non-destructive. Description adds that the tool returns per-model {score, confidence, signals, raw_response} + combined view, and clarifies the Anthropic cost model. No contradictions. Could optionally detail score interpretation, but overall good.

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 well-structured paragraph: function statement, default behavior, parameter caveat, return format, use cases. No filler sentences, every sentence serves a purpose.

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

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

No output schema, but description lists returned fields. All 4 parameters covered in schema and description. Annotations present. For a probing tool, missing edge cases (e.g., zero results) but adequate for typical use. Could mention rate limits or output size, but not strictly required.

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

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

100% schema description coverage, so baseline is 3. Description adds value by clarifying default model, Anthropic key requirement, and context disambiguation purpose. This exceeds the schema's minimal descriptions without redundancy.

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

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

Explicitly states it probes LLMs for knowledge about an entity and scores visibility 0-100 per model. Unambiguous verb+resource combination. Distinct from siblings like ask_pipeworx (single model Q&A) or scan_competitor_ai_presence (likely different scope).

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

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

Specifies use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). Explains default model and when to provide _apiKey for Anthropic. Does not explicitly list exclusions or alternatives among siblings, but the use-case description provides sufficient context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context: it routes questions, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and is described as 'one fast call' that 'works on every tier'. This goes beyond the annotations without contradicting them.

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

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

The description is longer than average but well-structured and front-loaded with the core directive ('PREFER OVER WEB SEARCH'). It uses clear sections: value proposition, use cases, examples, and alternatives. Minor redundancy exists ('START HERE' and 'default entry point' convey the same idea), but no sentence is wasted.

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

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

Despite having no output schema, the description explains what the tool returns (structured answer with citation URIs), how it works (routes to one of 5,501 tools across 1,441 sources), and when to escalate to siblings. For a tool of this complexity, the description is exceptionally complete and leaves little ambiguity for an agent deciding whether to invoke it.

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

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

Schema coverage is 100%, and the schema already describes the 'question' parameter and its aliases. The description adds usage context by providing concrete example questions ('current US unemployment rate', 'Apple's latest 10-K') and clarifying the breadth of accepted natural-language inputs, which helps the agent formulate good queries.

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: answer factual questions by routing to 5,501 tools and returning structured answers with citation URIs. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and from web search, making its scope unambiguous.

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

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

The description provides explicit when-to-use guidance ('START HERE for most questions', 'Use whenever the user asks...') and when-to-step-up alternatives ('for a hallucination-resistant single answer use ask_pipeworx_grounded; for broad/multi-part use deep_research'). It even mentions when not to prefer it (breaking news and similar are handled by its news routing).

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavioral traits: candidate routing improvements may be enabled live, currently no candidate is active so behavior matches ask_pipeworx exactly, and it 'falls back to nothing' but is a full working router. This transparency about variability and experimental nature is highly valuable for agent decision-making.

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 long and front-loaded with the beta status and core functionality. Each sentence contributes unique context: beta version, current matching state, usage instruction, and confirmation of full functionality. It is slightly verbose but efficient and well-structured for the amount of crucial caveats it conveys.

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

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

The description covers the beta status, exact current behavior (matching ask_pipeworx), usage context (when to choose this over stable), and the experimental nature. It mentions 'same response shape' which compensates for the absent output schema. However, it does not detail what the routing response actually contains or give an example, leaving minor ambiguity for an agent unfamiliar with ask_pipeworx.

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

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

The schema already provides 100% coverage with descriptions for all six parameters, including the 'question' field and its aliases. The description adds 'same arguments' as ask_pipeworx, but this does not enhance understanding of parameter meaning or usage beyond the schema. It is a baseline 3 given the high schema coverage.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, explaining it is an identical universal router with the same tools, arguments, and response shape. This distinguishes it from its stable sibling ask_pipeworx and from ask_pipeworx_grounded by highlighting its experimental edge and live candidate routing improvements.

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

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

The description explicitly states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router, giving a clear purpose for testing and evaluation. This provides a direct alternative (ask_pipeworx) and contextual reason for selection.

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

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

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false, the description adds significant behavioral context: it discloses the exact return payload with refusal_reason, enumerates five refusal reasons, explains the extra LLM call cost, and states that data is used exclusively from tool results. This goes well beyond annotations and helps the agent anticipate outcomes.

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

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

The description is detailed yet efficiently packed. Each sentence serves a purpose: identifying the mode, explaining the pipeline, specifying return structure and refusal reasons, giving usage context, and noting tradeoffs. It is appropriately front-loaded with the core value proposition and has no filler.

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

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

There is no output schema, so the description must explain return values—and it does thoroughly, including success payload and refusal reasons. It also covers when to use, cost implications, and relationship to sibling tool. Given the complexity of the tool and the lack of an output schema, this is fully complete.

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

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

Schema description coverage is 100% (all parameters are documented as aliases for 'question'). The description does not add parameter-level details, but it does clarify that the tool itself fills arguments for the underlying tools, so the agent only needs to provide a natural-language question. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's specific function: a 'hallucination-resistant answer mode for high-stakes reads' that routes to tools, fetches data, and extracts answers using only tool results. It explicitly distinguishes from sibling 'ask_pipeworx' by emphasizing grounded evidence and refusal behavior, making the unique purpose unmistakable.

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 instructions: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also names the alternative 'ask_pipeworx' for casual lookups and mentions the cost tradeoff, offering clear decision guidance.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint). It details the resolver contract with confidence levels, parent event extraction, news fallback handling, safety mechanisms for low-confidence matches and closed markets, wide-spread liquidity notes, and resolution-rule risk. This comprehensive behavioral disclosure ensures the agent understands all important side effects and edge cases.

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 every sentence adds necessary detail. It is front-loaded with the core purpose and input formats. However, the extensive fan-out examples and response shapes could be structured as bullet points for easier scanning. Given the complexity, the verbosity is justified for completeness.

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

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

The description covers all angles: input, process (resolver, parallel fan-out), output structure (result.market, analysis, evidence), error/safety states (low-confidence, closed market, illiquid), and cancellation rules. Even without an output schema, the agent can fully understand the tool's behavior and expected results.

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

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

Schema coverage is 100%, but the description adds significant value. It explains the 'market' parameter accepts slugs, URLs, or question text. It clarifies the default behavior for 'depth' (thorough) and gives recommendation for 'include_raw' (false recommended, with reasons). Examples in both schema and description further illustrate usage.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies the input types (slug, URL, question text) and the output (evidence packet + comparison). This distinguishes it from sibling tools like ask_pipeworx or polymarket_edges which serve different purposes.

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 use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It gives examples of fan-out categories and response shapes. While it doesn't explicitly say when not to use, the context of sibling tools (e.g., polymarket_arbitrage, polymarket_edges) makes the usage boundaries clear. A slight improvement would be to mention that for multi-market comparison or arbitrage, other tools are more appropriate.

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. Description adds rich behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), specific data points (revenue, net income, debt, adverse-event counts), sorting by primary metric, and citation URIs. This goes beyond annotations to define what the tool returns.

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 trigger phrases and efficiently covers both entity types. It is detailed but every sentence adds value; no fluff. Slightly long but justified by the tool's dual-purpose nature.

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

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

No output schema exists, so the description carries the burden. It explains what data is returned for each type and mentions sorting and citations, but lacks explicit output structure (e.g., JSON format). Adequate but could be more precise about the response shape.

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

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

Schema coverage is 100%, so baseline is 3. Description reiterates parameter meaning (tickers/CIKs for company, drug names) and provides examples, but adds minimal new semantic detail beyond the schema's own 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 performs side-by-side comparisons of 2-5 companies or drugs, with trigger phrases like 'Compare X and Y' and 'which is bigger.' It distinguishes from sibling tools like entity_profile by advocating for parallel calls over sequential lookups.

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

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

Explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides natural language examples and implies not to use for single entity queries, clearly differentiating from alternatives like entity_profile.

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, idempotentHint=true, destructiveHint=false, which cover safety and side effects. The description adds no extra behavioral context such as valid time zone formats, handling of DST ambiguity (despite the dstAmbiguity param), or output structure. Annotations carry the burden adequately, so a score of 2 reflects minimal added 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 a single sentence of 5 words—maximally concise but at the expense of informativeness. It earns a middle score because conciseness is achieved but critical details are omitted.

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

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

Despite having an output schema, the description does not mention return values or behavior (e.g., does it return the time at both zones?). With 4 parameters including DST ambiguity handling, the description is too sparse to fully inform an agent about input/output expectations. Siblings increase the need for clarity, which is not met.

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 0%: no property descriptions exist in the schema. The description 'Convert datetime between zones' provides no information about parameter formats (e.g., dateTime format, time zone naming), required vs optional status, or the meaning of dstAmbiguity. This is a critical gap given the lack of 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 'Convert datetime between zones' clearly states the action (convert), the resource (datetime), and the scope (between zones). It distinguishes from siblings like 'current_time' and 'translate_to_iso' by focusing on conversion between arbitrary zones rather than obtaining current time or formatting. However, it does not explicitly contrast with related tools.

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

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

No guidance is provided on when to use this tool versus alternatives. Siblings include multiple time-related tools (current_time, current_iso_zoned_date_time, translate_to_iso, list_zones), but the description gives no context about prerequisites, typical use cases, or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the return format (ISO 8601 zoned datetime) but no additional behavioral traits like error handling or edge cases. No contradiction with annotations.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the tool's purpose and output format.

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

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

Given the tool's simplicity (one parameter, rich annotations, an output schema), the description covers the core purpose and return format. It lacks parameter details, but the schema examples and output schema compensate. Nearly complete for this use case.

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

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

Schema description coverage is 0%, so the description must compensate. It only mentions 'IANA timezone' for the parameter, which adds no extra meaning beyond the schema's 'timeZone' property name. It does not specify valid values, format, or provide examples.

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

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

The description clearly states the tool returns the current date/time for a given IANA timezone as an ISO 8601 zoned datetime string. It specifies the verb 'return', the resource 'current date/time', and provides an example format, distinguishing it from siblings like 'current_time' and 'convert_time_zone'.

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 (provide an IANA timezone) but gives no explicit guidance on when to use this tool versus siblings like 'current_time', 'current_time_ip', or 'convert_time_zone'. No alternatives or exclusions are mentioned.

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

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

Annotations already declare readOnlyHint and idempotentHint, indicating safe, repeatable behavior. The description adds the specific return fields (year, month, day, etc.) and mentions dstActive, which are not covered by annotations.

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

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

Single sentence, no wasted words. Lists all return fields clearly and 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?

For a simple tool with one parameter and an output schema (not shown), the description fully explains input and output. It covers the timezone format and lists all return fields, leaving no gaps.

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

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

Schema coverage is 0%, so description must compensate. It provides the parameter format ('IANA timezone') and an example ('America/New_York'), adding meaning beyond the bare string type.

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

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

The description clearly states the verb ('Return') and the resource ('current date and time for a given IANA timezone'), listing all returned fields. It distinguishes from siblings like current_iso_zoned_date_time by specifying component-wise return.

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 use when needing current time components for a specific timezone, but does not explicitly contrast with siblings or provide when-not scenarios. Missing guidance on alternative tools like convert_time_zone or day_of_the_week.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. The description adds no behavioral context beyond the basic purpose, such as whether the time is local or UTC, or any caveats. It does not contradict annotations.

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

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

The description is a single, efficient sentence with no unnecessary words. It is front-loaded and to the point.

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

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

Given the tool's simplicity (2 params, output schema exists), the description fails to explain what 'current time' means (UTC vs local), accuracy, or time zone implications. The output schema may clarify return format, but the description should add 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 0%; no parameter descriptions exist. The phrase 'at lat/lon' weakly implies the purpose of latitude and longitude, but provides no constraints, ranges, or formats. With zero coverage, more detail is needed.

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

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

The description 'Current time at lat/lon' clearly states the tool returns the current time for a given latitude and longitude. This verb+resource combination distinguishes it from siblings like 'current_time' (no location) and 'current_time_ip' (IP-based).

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

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

No guidance is given on when to use this tool versus alternatives. There is no mention of prerequisites, such as valid coordinates or time zone handling, nor any 'when not to use' advice.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which cover safety and behavior. The description adds no additional behavioral context beyond what annotations provide.

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

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

The description is extremely concise (4 words) and front-loaded. Every word is used, but it may be too terse; however, for a simple tool it works.

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

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

The tool has only one parameter and an output schema, so the description needs less elaboration. However, it does not mention output format, errors, or limitations, and given many siblings, more context would improve completeness.

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

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

The description implies the parameter 'ipAddress' is an IP address, but the schema only specifies type string with no description. It provides basic meaning but lacks format details (e.g., IPv4/IPv6). Schema coverage is 0%, so the description partially compensates.

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

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

The description clearly states the purpose: getting current time at a given IP. It is specific and straightforward, though it could explicitly use a verb like 'get' and differentiate from siblings like 'current_time'.

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

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

No guidance on when to use this tool versus alternatives like 'current_time' or 'convert_time_zone'. No exclusions or context provided.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds concrete details on the returned metadata (offsets, DST start/end, active status), providing transparency beyond annotations.

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

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

Single sentence, no waste. Directly lists the information returned.

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

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

The description covers the key outputs. Given the output schema exists, it doesn't need to detail return structure. However, it could mention error handling or input validation.

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?

With 0% schema description coverage, the description carries full burden but only mentions 'IANA zone name'. It does not specify the expected format (e.g., 'America/New_York') or provide examples beyond the schema examples.

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

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

The description clearly states the tool returns timezone metadata for an IANA zone name, listing specific fields such as UTC offset, DST offset, etc. This differentiates it from sibling tools like convert_time_zone or list_zones.

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 like convert_time_zone. No explicit when-to-use or when-not-to-use context is provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint as false, so the tool is a safe, idempotent read. The description adds no further behavioral details (e.g., output format, date range limits), but annotations cover the main traits.

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

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

The description is a single concise sentence with no redundancy. It efficiently conveys the core purpose without extraneous text.

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

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

Despite the tool's simplicity, the description omits crucial context like the output format or any constraints on the input date. An output schema exists but is not shown; the description should at least hint at what is returned.

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?

There is one parameter 'date' with type string, but the description does not clarify accepted formats or add meaning beyond the schema. Schema coverage is 0%, so the description should compensate but does not.

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 'Day of week for a date' clearly states the tool computes the day of the week from a date input. It is distinct from sibling time-related tools like convert_time_zone or current_time, though no explicit differentiation is given.

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

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

No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description is purely functional without usage context.

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

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

Annotations already declare readOnly/openWorld/idempotent non-destructive, but the description adds significant context beyond annotations: account/paid-plan requirements, 'NOT open-web search', gaps[] never invented, contradictions[] for standard/thorough, hop field, fetchable citation_uri only when source emits resolvable URI, semantic excerpting of large records, and expected 15-90s latency. No contradiction with annotations.

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

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

Though long, every sentence carries unique value and the structure is logical: auth first, then core capability, use cases/exclusions, depth semantics, output details, performance expectations. It is appropriately sized for a tool with this complexity and is front-loaded with the most critical constraint (account requirement).

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

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

Given no output schema, the description thoroughly explains the return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field) and behavior (parallel routing, excerpting, latency, auth) — making it nearly self-sufficient for an agent to understand inputs, outputs, and edge cases. Complexity is high but description covers all critical dimensions.

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 description adds substantial depth: explains question as broad/multi-part natural language, elaborates on depth enum values ('quick=3', 'standard=5', 'thorough=8') and their behavioral differences (gap recovery, contradiction scan) beyond the schema's brief descriptions. This enriches parameter understanding significantly.

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

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

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1441 STRUCTURED data sources... in ONE call... Decomposes your question into focused facets, routes each to the right one of 5,501 tools IN PARALLEL, and returns a findings packet.' It clearly distinguishes from siblings by explicitly naming ask_pipeworx as the alternative for single lookups and breaking news.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also covers auth prerequisites: 'If you are not signed in, use ask_pipeworx instead'. Additionally describes depth-level behavior choices.

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 beyond by stating the return format (names, descriptions, full input schemas with curated examples) and that results are 'ready to call directly, no second schema lookup needed,' adding behavioral detail without contradiction.

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

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

Four sentences, front-loaded with purpose, then usage guidance, then return details. Every sentence adds essential information with no redundancy or filler.

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

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

No output schema exists, so the description must explain the return value. It does so sufficiently: names, descriptions, and full schemas with examples. It also lists covered domains. Minor omission: pagination or error handling not mentioned, but for a discovery tool this is acceptable.

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 individual parameter descriptions are minimal (aliases). The description adds value by explaining the primary 'query' parameter takes natural language, provides examples, and lists all aliases (task, q, description, search). This compensates for the sparse schema descriptions.

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

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

The description opens with 'Find tools by describing the data or task,' clearly stating the verb and resource. It lists numerous example domains (SEC filings, FDA drugs, stocks, etc.) and distinguishes discover_tools from siblings by positioning it as a tool discovery utility, not a data retrieval tool itself.

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

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

Explicit guidance is given: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use the tool and implies that for known tools, discovery is unnecessary.

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, destructiveHint etc. The description goes beyond by detailing the sources (SEC EDGAR, XBRL, USPTO, news) and exact return fields (cik, recent_filings with URIs, fundamentals sorted, patents with sunset note, news fallback, LEI). It also discloses soft-failure for patents, adding significant transparency.

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

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

The description is somewhat long but well-structured: starts with examples, then explains behavior and return structure. Every sentence adds value, but could be slightly trimmed while retaining completeness.

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

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

Given there is no output schema, the description thoroughly explains the return format including specific data sources and fields. It covers limitations (patents sunset, name not supported) and is complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both type and value. The description provides examples (ticker "AAPL" or zero-padded CIK) and explicitly clarifies that names are not supported, adding 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 begins with multiple clear examples ("Tell me about X", "research Acme", etc.) and states it provides a full cross-source profile of a US public company in one parallel call. It explicitly contrasts with chaining multiple single-pack lookups, distinguishing it from sibling tools like compare_entities and resolve_entity.

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

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

Specifies when to use: when the user asks for a holistic view of a public company. It explicitly notes that names are not supported and advises to use resolve_entity first if only a name is available. It also describes the parallel call behavior, guiding the agent to prefer this over sequential lookups.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data and stale contexts, but doesn't detail what gets destroyed beyond deletion.

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 repetitive or unnecessary words. Efficiently communicates purpose and usage.

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

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

For a simple tool with one parameter and no output schema, description sufficiently covers purpose, usage context, and pairing with siblings. Annotations round out behavioral safety.

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?

Only one parameter (key) with schema description 'Memory key to delete', schema coverage 100%. Description does not add new information 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 'Delete a previously stored memory by key', specifies the action and resource. Mentions pairing with remember and recall, distinguishing from siblings.

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

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

Explicitly says when to use: when context is stale, task is done, or to clear sensitive data. Also notes pairing with remember and recall, implying 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 readOnlyHint=true, idempotentHint=true, and no destructiveness. The description adds context that the tool fetches the page externally and emits a standard markdown text blob, which are helpful behavioral details 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: a front-loaded sentence stating the main purpose, followed by short details on process and use cases. No superfluous words; every 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?

For a simple tool with 2 parameters and no output schema, the description covers the core functionality, output format, and common use cases. It could mention error handling (e.g., invalid URL), but the current scope is sufficient for most agents.

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

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

Schema description coverage is 100%, so the schema already documents both parameters adequately. The description reinforces the purpose but does not add significant new meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying actions (fetch, extract, emit) and the output format. It does not explicitly differentiate from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence', which weakens the score slightly.

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

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

The description lists use cases (clients, own project, competitor audit) but does not explicitly state when NOT to use this tool versus alternatives. No comparison to siblings or exclusion criteria are provided, so guidance is moderate.

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, and destructiveHint. Description adds useful context about returned fields and usage, enhancing transparency without contradiction.

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

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

Two concise sentences with no wasted words. Front-loaded with core purpose, then details and usage guidance.

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

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

With one optional parameter and no output schema, the description lists return fields and provides usage context. Could mention the optional parameter for completeness, 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%, so baseline is 3. Description does not discuss the 'include_inactive' parameter, but the schema itself documents it adequately. No additional value from description for parameters.

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' and specifies returned 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 advises using this tool to review subscriptions before adding more or to find an ID to cancel. Provides clear context but doesn't include 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, idempotentHint, and non-destructive nature. The description adds that it returns supported IANA names, which is useful context for behavior beyond annotations.

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

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

Two concise sentences with no wasted words, efficiently communicating purpose and usage.

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

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

For a zero-parameter list tool with an output schema, the description sufficiently explains what the tool returns and how to use it, completing the 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?

No parameters exist, so the baseline is 4. The description does not need to add parameter info and simply states the output.

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

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

The description clearly states it returns all IANA timezone names supported by TimeAPI.io, distinguishing it from sibling tools by specifying it's a directory for valid timeZone strings.

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 as a directory to find valid timeZone strings for other calls,' providing both when-to-use and implied when-not-to-use guidance.

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

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

Annotations are all false, providing no safety signals, so the description carries the full burden. It discloses rate limiting (5 per identifier per day), cost (free, doesn't count against quota), and the claim_token workflow for later retrieval of resolution status. There is no contradiction with annotations.

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

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

The description is a dense single paragraph of nine sentences, but every sentence earns its place—covering purpose, exclusions, workflow, rate limits, and cost. It is front-loaded with the primary action, though it could benefit from bullet points for scannability. Not unnecessarily 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?

With no output schema, the description compensates by explaining what filing returns (a claim_token) and how to use it later to read resolution status. It covers prerequisites, exclusions, rate limits, and the full workflow, making the tool self-contained for an agent.

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

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

Schema coverage is 100%, with each parameter described in the schema. The description adds practical value beyond the schema by explaining the claim_token round-trip ('pass it back later as pipeworx_feedback({claim_token:...})') and clarifying the context object's optionality. This is a modest enhancement over 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' providing a specific verb (Tell) and resource (Pipeworx team). It clearly distinguishes this from sibling ask_pipeworx tools, which are for asking questions rather than submitting feedback.

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

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

The description explicitly lists when to use the tool (bug, feature/data_gap, praise) and when not to use it (for tools from other MCP servers). It also instructs users to describe issues in terms of Pipeworx tools/packs and avoid pasting end-user prompts, giving clear contextual boundaries 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?

Beyond the annotations (readOnlyHint=true, etc.), the description adds valuable behavioral details: caching (5min-1h), data source (CF analytics-engine), and no PII. It also notes the self-aggregating nature. This provides sufficient transparency for a read-only, idempotent tool.

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

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

The description is concise and well-structured. It front-loads the core purpose, then provides use cases and technical details without fluff. Every sentence adds value, and the length is appropriate for the tool's simplicity.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It explains what is returned (top tools, packs, volume), how it works (caching, data source), and provides privacy assurances. No gaps are apparent for effective use.

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

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

The input schema covers the parameter 'window' with 100% descriptive coverage. The description adds extra guidance by explaining that shorter windows surface current hotness and longer windows show steady-state demand. This aids agent decision-making beyond the schema enumeration.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a recent window. It specifies the verb 'returns' and the resource (usage data from other AI agents). The tool is well-differentiated from siblings like 'discover_tools' (which likely discovers available tools) and 'ask_pipeworx' (for asking questions), as it focuses on trend data.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming canonical tools, and seeing alignment. This provides clear context for when to use the tool. However, it does not explicitly mention when not to use it or name alternative tools for specific cases, which would have improved the score.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about internal behavior (fill check against live CLOB depth, partition filter, semantic anchor) without contradicting annotations. No destructive actions are implied, and the tool's read-only nature is reinforced.

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

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

The description is relatively long but well-organized, with clear sectioning and front-loading of the main purpose. Every sentence adds unique value, though some technical details (e.g., Jaccard similarity threshold) could potentially be simplified. Overall, it earns its length.

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

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

Despite lacking an output schema, the description thoroughly details the response structure: opportunities array with gap_pp, suggested_trade, reasoning; partition_check with sum_yes_prices, gap_from_1, placeholders_filtered; and fill check with realizable_edge_pp. All modes and edge cases are covered, making the tool fully usable without additional documentation.

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, and the description substantially enriches both parameters. For event, it specifies accepted formats (slug or full URL) and gives examples. For topic, it explains the cross-event search mechanism and provides example queries. This adds significant 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: no args (trending scan), event (single market), and topic (cross-event). This specificity and differentiation from sibling tools like polymarket_edges and polymarket_fill_risk demonstrate high clarity.

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

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

The description provides explicit guidance on when to use each parameter: no args for trending scan, event for a specific market slug, and topic for cross-event scanning. It also includes when not to trade (realizable_edge_pp <= 0) and directs to polymarket_fill_risk for custom sizing. This comprehensive guidance leaves no 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 readOnlyHint=true and destructiveHint=false, but the description adds extensive behavioral details: caching, segments, diagnostics, edge computation, and tradeable-edge knobs. There is 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 lengthy but dense with useful information. It is front-loaded with purpose and each sentence adds value. Minor redundancy could be trimmed.

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 9 parameters, rich annotations, and no output schema, the description is very complete. It explains the output structure, caching, assumptions, and caveats (e.g., Fed bets unreliable).

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 all parameters have descriptions, but the description adds extra context (e.g., slippage_pp adjustments for thin partitions, min_partition_leg_kelly explanation) that goes beyond the schema.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs and resources, and distinguishes itself from siblings like polymarket_arbitrage by focusing on discovery.

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

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

The description explicitly says it's 'Built for what should I bet on today' and mentions that agents can 'discover opportunities without paging hundreds of markets.' However, it does not explicitly state when not to use it or name alternative tools for other 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 declare readOnlyHint, openWorldHint, idempotentHint, and nondestructive. The description adds significant behavioral context: it details the response structure with tracked[], expired[], and snapshot_dates[], and mentions limits like the 60-day snapshot TTL and that decay is based on daily closes, not intraday.

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

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

The description is front-loaded with the core purpose and structured with clear paragraphs for response sections and limits. It is slightly verbose but each sentence adds value; could be more concise by removing some response field details, but overall 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 the moderate complexity, good annotations, and no output schema, the description fully covers what the tool returns (tracked[], expired[], snapshot_dates[]) and important constraints (60-day TTL, daily close data). An agent can reliably determine the tool's capabilities and limitations.

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

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

Schema coverage is 100%, so the schema already documents both parameters thoroughly. The description adds only minor clarification (e.g., max 30 for days, allowed values for window), but the schema itself provides these details. Baseline 3 is appropriate.

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

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

Description clearly defines the tool as an edge persistence and decay telemetry tool from daily polymarket_edges snapshots. It uses specific terms like 'edge persistence', 'decay telemetry', and contrasts fresh vs old edges, distinguishing it from sibling tools like polymarket_edges which likely provides current edge data.

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

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

The description implies when to use (to answer how long an edge has existed and if it's shrinking) but does not explicitly state when not to use it or compare to alternatives. The context of sibling tools suggests differentiation, but no direct guidance is provided.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent with the description. The description adds behavioral depth: it explains live order book walking, ladder traversal, return of verdicts (clean|degraded|cannot_fill), and risks like forced_directional_risk in basket mode. 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 long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence adds value, but some repetition exists (e.g., explaining size_usd in two contexts). Slightly verbose for a definition, but highly effective and front-loaded.

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

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

No output schema, so the description fully explains return values: for single-market (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and basket (theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It covers both modes and error conditions (cannot_fill). Complete for a complex tool.

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

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

Input schema has 100% coverage with descriptions for all 4 parameters. The description adds significant meaning beyond the schema: explains mode distinction, default side logic, interpretation of size_usd for buys vs sells and basket mode (settlement notional), and the clamp range (10–1,000,000). It enriches understanding of parameter behavior.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It details two distinct modes (single-market and basket) and lists specific return values for each, distinguishing it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly instructs when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround uncapturable, partial fills create directional risk) and specifies requirements (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?

Annotations indicate read-only, idempotent, non-destructive. Description adds detailed behavioral context: two modes, response structure, compatibility warnings, temporal alignment, and leg matching logic. 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?

Description is relatively long but efficient, each sentence adds unique information. Front-loaded with purpose and modes. Some repetition in safety field explanation could be streamlined, 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?

Despite lacking an output schema, the description thoroughly explains response structure, safety fields, and edge cases. Three parameters are well-covered, no gaps in understanding tool behavior or results.

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

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

Input schema has 100% coverage with descriptions for each parameter. Description adds value by explaining the two modes, how explicit tickers override topic, and lists the pre-mapped topics. This provides context 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?

Description explicitly states the tool computes cross-venue spread between Kalshi and Polymarket for the same question, and distinguishes two modes. It is a specific verb+resource description that differentiates from sibling tools like polymarket_arbitrage.

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

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

Description gives clear when-to-use guidance via two modes and explains safety fields that indicate when spreads are not meaningful. However, it does not explicitly compare to sibling tools or state when not to use it, leaving some implicit guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about retrieving or listing keys and scoping, which is useful but does not reveal new behavioral traits beyond what annotations imply. 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 front-loads the core action and includes examples and pairing info, but it is somewhat verbose (three sentences). It could be tightened without losing clarity. The structure is logical and easy to parse.

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

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

With no output schema, the description should clarify the return format. It mentions retrieving a value or listing keys but does not specify the data type or structure of the value. Thus, while adequate for basic use, it lacks full completeness regarding output details.

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

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

Schema coverage is 100% and the parameter 'key' is already well-described in the schema ('Memory key to retrieve (omit to list all keys)'). The description echoes this ('omit the key argument') without adding new semantic details, so it does not exceed the baseline of 3.

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

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

The description explicitly states the tool retrieves a saved value or lists all keys, using clear verbs ('retrieve', 'list') and identifies the resource (memory context). It distinguishes from sibling tools like 'remember' and 'forget' and provides concrete examples (ticker, address, notes), making purpose unmistakable.

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

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

The description explains when to use the tool (to look up previously stored context without re-deriving), mentions pairing with 'remember' and 'forget', and notes scoping. It does not explicitly state when not to use it or contrast with other retrieval tools, but the guidance is clear enough for most contexts.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds the behavior of mark_read (flagging events as read) and confirms polling is fine, providing useful context 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 a single paragraph of 3-4 sentences, front-loaded with purpose. It is efficient with no wasted words, though a more structured format (e.g., bullet points) could improve readability.

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

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

Given 5 optional parameters, no output schema, and comprehensive annotations, the description covers behavior, parameters, and alternative access (GET endpoint). Minor gaps: no mention of error handling or rate limits.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds meaningful context, e.g., explaining that mark_read:true causes next calls to show only newer events, going beyond the schema's basic description.

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

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

The description clearly states it pulls fired events from a subscription feed and lists what each alert carries (source, citation_uri, raw payload). It does not explicitly differentiate from sibling tools like list_subscriptions, but the purpose is specific and unambiguous.

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

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

The description mentions polling works and the same feed is available via GET, but does not provide explicit guidance on when to use this tool vs alternatives. Usage context is implied but not directly stated.

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

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

Annotations declare idempotent, readOnly, openWorld, and non-destructive behavior. The description adds details about data sources, fallback logic (GDELT→GNews), USPTO soft-fail behavior, and return structure (grouped changes, citation URIs), all beyond what annotations provide.

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

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

The description is a single paragraph but contains rich, well-organized information. Could be slightly more concise but effectively front-loads the tool's core function and use cases.

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

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

Given the tool's complexity (multiple sources, fallback, parameter formats, return types), the description covers return values indirectly and provides sufficient context. Could mention pagination or rate limits, but generally complete for a read-only aggregation tool.

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

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

Schema coverage is 100%, and the description adds value with concrete format examples for 'since' (ISO date and relative shorthand) and recommendations ('Use 30d or 1m for typical monitoring'), plus clarifications on 'value' (ticker or CIK).

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

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

The description clearly states the tool provides a change feed for a company, aggregating SEC filings, news, and patents. It lists example queries and distinguishes from the sibling tool entity_profile, making the purpose unambiguous.

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

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

The description explicitly advises when to use this tool versus entity_profile ('Use entity_profile instead when you want the static profile'), and provides context for typical monitoring with since parameter recommendations.

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 idempotency and non-destructiveness. The description adds useful behavioral context: key-value scoping, 24-hour retention for anonymous sessions, and pairing with recall/forget. However, it does not clarify whether a repeated key overwrites or appends, which is a minor gap.

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, efficient paragraph. It front-loads the core purpose, then adds context and usage instructions. Every sentence contributes value without redundancy.

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

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

For a simple key-value store with no output schema, the description covers all needed aspects: purpose, usage, scoping, persistence, and integration with related tools. The agent has sufficient information to decide when and how to invoke this tool.

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

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

Schema coverage is 100% with clear descriptions. The description enhances this with naming conventions (e.g., 'subject_property', 'target_ticker') and confirms value is free text. This adds practical guidance beyond the schema, earning a 4.

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

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

The description clearly states the tool saves data for reuse, with specific examples (ticker, address, preference). It distinguishes from sibling tools recall and forget by explicitly naming them as retrieval and deletion counterparts.

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 ('when you discover something worth carrying forward') and mentions alternatives (recall, forget). It also differentiates persistence behavior for authenticated vs anonymous users.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond these: each call 'cascades through several lookup endpoints internally,' inputs are 'auto-disambiguated,' and the specific return payloads (ticker, CIK, company_name, citation URI, etc.) are disclosed. This tells the agent about the tool's internal operations and output structure, which annotations do not cover.

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

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

The description is dense but well-organized. It opens with relatable examples, then defines the purpose, provides explicit usage guidance, details each supported type with return information, and finishes with a performance note. Every sentence contributes practical information without repeating the schema or annotations. The structure is logical and easy to parse.

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

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

For a two-parameter tool with no output schema, the description is remarkably complete. It specifies the return values for each entity type, includes citation URIs, explains the input variants, and notes the cascading internal lookups. It covers when to use it, what it does, and what to expect, with no significant gaps. The agent can confidently invoke the tool based solely on this description.

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

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

The input schema already provides 100% coverage for both parameters, including examples and allowed formats. The description enhances this by explaining the consequences of each type choice (what data is returned) and introducing the 'auto-disambiguated' behavior for the value parameter. This connects parameter values to output semantics, adding meaning beyond the schema's baseline definitions.

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

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

The description opens with concrete user queries, then states the core function: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' This is a specific verb+resource pairing that clearly distinguishes it from siblings like entity_profile or compare_entities by emphasizing the output is the required ID for other tools. The supported types and example outputs further cement the purpose.

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

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

The description provides explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' This is a clear directive for the primary use case. However, it does not explicitly state when not to use the tool (e.g., when you already have the canonical ID) or name alternative tools, leaving the 'when-not' and 'alternatives' partly implied. The instruction is strong but could be more complete.

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, and non-destructive behavior. The description adds beyond by explaining that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This provides behavioral detail not present in annotations 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?

The description is three sentences with no wasted words. First sentence states the primary purpose, second explains the mechanism, third gives a concrete use case and return format. Every 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 the tool has 4 well-documented parameters, no output schema, and rich annotations, the description covers what the tool does, how it works (probes, ranks), and what it returns (score, confidence, signal density). It is complete enough for an agent to understand and invoke correctly.

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

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

Schema description coverage is 100% with clear parameter descriptions. The description adds context about the first entity being treated as the subject for narrative, which is not explicitly in the schema. This small addition raises it above 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 compares AI visibility across multiple entities side-by-side, probing each with ai_visibility_check and ranking by score. It provides a concrete use case ('does Claude know about us as well as our competitors?') and differentiates from sibling tools like ai_visibility_check (which is a sub-operation) and compare_entities (general comparison vs AI-specific). The verb 'scan' and resource 'competitor AI presence' are specific.

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

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

The description explicitly frames the tool as useful for competitive AI-marketing audits, giving a clear scenario. However, it does not mention when not to use it or provide alternative tools for non-competitive contexts. The usage context is clear but lacks exclusion guidelines.

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?

While annotations already indicate read-only, idempotent, and non-destructive behavior, the description adds significant context: composite nature, graceful partial failures, and the specific sources queried. It discloses that bundlephobia's first measurement may take 5-30 seconds and that sources_failed will list timeouts.

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

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

The description is well-structured and front-loaded with the core purpose. Every sentence adds value: sources, usage guidelines, limitations, return content, and partial failure behavior. It is appropriately sized for the complexity of the tool.

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

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

Given no output schema, the description fully covers the return format: summary block fields, per-advisory detail, links, and alternative versions. It also covers edge cases (partial failures, ecosystem limitations, timeout delays). No gaps identified.

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 does not add meaningfully to the already detailed schema descriptions; it mentions scoped packages and version defaults, but these are already in the schema. No additional parameter semantics beyond schema.

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

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

The description clearly states the tool's purpose as a composite check for npm packages, specifying the sources (deps.dev and bundlephobia) and the exact metrics returned (license, advisories, bundle size, etc.). It distinguishes itself from siblings by focusing on npm and providing a unified query for safety, popularity, and size.

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 to use it when an agent asks about package safety, popularity, or cost. It also specifies when not to use it (non-npm ecosystems fall under deps.dev directly) and warns about potential delays with bundlephobia's first measurement, providing clear expectations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds valuable behavioral details: truncation at 200K chars, embedding model (BGE-base-en), cosine similarity, overlapping 500-char windows, and return of offsets. No contradiction with annotations.

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

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

The description is a single dense paragraph that front-loads the purpose and packs useful details. Every sentence adds value, though it could be slightly 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?

No output schema exists, but the description adequately covers return format (top-N passages with offsets and similarity scores), technical details (embedding model, windowing), and limits. The information is sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples for the 'query' parameter and confirms the character cap for 'text', but does not add significant new semantics beyond what the schema provides.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific examples (SEC 10-K, article) and distinguishes from sibling ask_pipeworx_grounded by explaining how they pair together.

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 the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded, providing clear context. However, it doesn't cover when not to use or list alternatives beyond the paired tool.

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

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

Annotations indicate idempotent and non-destructive, but the description adds substantial behavioral details: OAuth requirement, return value, delivery channel constraints (phone verification, SMS cap, webhook signing secret, auto-disable). 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 well-structured and concise: first sentence states purpose and return, then prerequisites, then type details, then delivery channels. Every sentence adds unique information without redundancy.

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

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

Covers prerequisites, types, delivery options, and return value. Lacks explicit error handling or behavior on duplicates, but is sufficient for an agent to invoke correctly given the detailed 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%, but the description significantly enhances each parameter with concrete examples and context (e.g., type-specific details, delivery constraints). 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's purpose: 'Create a proactive monitoring subscription to a live-data event stream' and mentions it returns the new subscription id. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides explicit prerequisites (Pipeworx OAuth account), lists supported types with detailed examples, and briefly covers delivery channels. It lacks explicit comparison to alternatives, but the context is clear enough for selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true. Description adds meaningful behavioral context: it returns 'category-bucketed example questions' and 'exact tool + argument shape' from a 'live catalog of thousands of tools', going 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?

Description is detailed but focused, with the main purpose front-loaded. Every sentence adds value, but it could be slightly trimmed without losing information. Still very well-structured for an onboarding tool.

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

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

Given no output schema, the description adequately explains return values (category-bucketed examples with tool+argument shapes). It covers all key aspects: purpose, arguments, usage order, and includes examples of topics. Complete for an exploratory 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% for the single optional parameter. Description adds substantial meaning: lists possible topic values (finance, pharma, etc.), explains that omission gives a cross-category spread, and states the purpose of the parameter (to focus). This fully compensates for the schema's minimal description.

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

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

Description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It lists specific example queries ('What can I ask Pipeworx?') and distinguishes it from sibling tools like ask_pipeworx or discover_tools by focusing on learning what to ask rather than executing queries.

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

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

Description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and explains how to call with no arguments or with a topic. While it doesn't explicitly state when not to use, the context makes it clear this is an exploratory tool, not for direct data retrieval.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool's safety profile is clear. The description adds minimal context beyond 'parse,' which aligns with the annotations. 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 extremely concise at one sentence, front-loaded with the verb 'Parse,' and contains no superfluous information. Every word earns its place.

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

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

Despite having an output schema that may define return values, the description is too brief for a tool with many date/time siblings. It lacks usage context, supported format patterns, or error behavior, which is incomplete given low schema coverage.

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

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

Schema description coverage is 0%, and the description does not elaborate on the 'date' and 'format' parameters. While examples exist in the input schema, the description itself adds no parameter meaning, leaving the agent to rely on external context.

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 'Parse custom-format date to ISO' clearly states the verb (parse) and resource (date), and differentiates from sibling tools like convert_time_zone and current_time by focusing on format conversion rather than time zone or current time.

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

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

The description does not provide explicit when-to-use or when-not-to-use guidance. While the purpose implicitly suggests usage for date format conversion, it does not mention alternatives or exclusions, leaving the agent to infer applicability.

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 significant behavioral context beyond annotations: describes deactivation (not deletion) and that historical events remain via recent_alerts. Ownership enforcement is also disclosed. 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?

Three sentences, each providing distinct value: action, ownership constraint, and side effect. 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 only one parameter and no output schema, the description covers purpose, usage constraint, and behavioral effect. Complete enough for the tool's simplicity.

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

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

Schema coverage is 100% for the single parameter. Description adds relational context ('returned by subscribe'), which helps the agent understand the expected value format.

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

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

The description clearly states 'Cancel a subscription by id', a specific verb and resource, which distinguishes it 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?

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), providing clear context on when to use; however, it does not explicitly state when not to use or mention alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: how it routes claims to structured or grounded pipelines, uses exact math for financial data, and returns verdicts with citations. 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 verbose (over 100 words) and includes tangential details like replacing sequential calls. While front-loaded with triggers, it could be more concise without losing clarity. Some sentences are non-essential.

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

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

Given the tool's complexity and lack of output schema, the description adequately explains the two processing paths, return value components (verdict, actual value, citation, reasoning), and eliminates ambiguity about scope. It is complete for the intended use.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description mentions tolerance_pct implicitly ('percent-delta math', 'capped at 5') but does not add significant new meaning beyond the schema. 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 is for verifying natural-language factual claims against authoritative sources. It provides specific trigger phrases and distinguishes its purpose from general QA tools like ask_pipeworx by focusing on fact-checking.

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 whenever the agent needs to check whether something a user said is factually correct.' It outlines two processing paths (financial vs. other claims) but does not explicitly list exclusion cases or alternatives. However, 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.