timezone

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

Annotations already declare readOnly/idempotent safe behavior. The description adds context about default model ('Workers AI Llama-3.3-70b (free)') and cost implications ('you pay Anthropic directly'), plus return structure ('{score, confidence, signals, raw_response}'). This exceeds baseline but doesn't mention potential rate limits or response size.

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 deliver the full picture: what it does, default behavior/cost, and use cases. Each sentence earns its place with no filler or repetition, and the most important info is front-loaded.

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

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

With no output schema, the description fully explains the return format ('per-model {score, confidence, signals, raw_response} + a combined view'). It also covers optional parameters, default model, and cost, making it self-sufficient for a 4-parameter tool.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds value by clarifying that the default model is free and that `_apiKey` incurs direct Anthropic costs ('BYO key — you pay Anthropic directly'), which is not in 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 action ('Probe one or more LLMs') and the resource ('what they know about a business / brand / product / topic'), with a specific output ('score visibility (0-100) per model'). It also differentiates from sibling tools by focusing on AI-model visibility scoring, not knowledge-base queries or research synthesis.

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

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

It explicitly lists relevant use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to pass `_apiKey` (to also probe Anthropic). However, it doesn't compare to alternatives like `scan_competitor_ai_presence` or state when not to use this tool, so it lacks full exclusion 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 useful behavioral context beyond annotations: it mentions that the tool routes to 5,439 tools, fills arguments automatically, and returns structured answers with stable citation URIs. It also notes that it works on every tier and is 'one fast call', providing performance expectations. It does not describe potential rate limits or error handling, but the annotation coverage lowers the burden.

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 highly organized: the first sentence establishes primacy over web search, followed by a concise mechanism explanation, then usage triggers, examples, and escalation guidance. Every sentence serves a purpose, but it is somewhat verbose; a 5 would require trimming redundant phrases. Despite length, it is front-loaded with the most critical information.

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

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

Given the tool's complexity (6 parameters, no output schema), the description is remarkably complete. It explains the routing behavior, return format (structured answer with citation URIs), the breadth of covered sources, and the tier/performance characteristics. It also addresses edge cases like breaking-news queries and explicitly directs users to sibling tools when needed. No critical information seems missing for selecting and invoking the tool.

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

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

The schema already documents the 'question' parameter and its aliases with 100% coverage. The description adds meaningful semantic guidance by listing question types it handles (SEC filings, FDA data, weather, etc.) and providing concrete examples (e.g., 'current US unemployment rate', 'Apple's latest 10-K'). This goes beyond the schema's generic 'question or request in natural language' by clarifying scope and expected input style.

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

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

The description clearly states the tool's function: it routes questions to the appropriate tool among 5,439 verified sources and returns structured answers with citation URIs. It uses a specific verb ('routes') and resource ('questions to the right tool'), and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying different use cases.

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 this tool versus alternatives: it says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and explicitly names alternatives for specific scenarios (ask_pipeworx_grounded for verbatim evidence, deep_research for multi-part questions). It also gives concrete example queries and lists sessional triggers like 'what is', 'look up', 'find'.

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

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

The description adds valuable behavioral context beyond the annotations: it's a beta experiment with candidate routing improvements enabled live when under test, currently no candidate is active so it matches ask_pipeworx exactly, and it is a full working router rather than a fallback. This complements the read-only, idempotent, open-world, non-destructive 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 front-loaded with the beta identity, then covers current state, usage, and clarifies it's a full router. Each sentence serves a purpose; it's compact and structured.

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

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

Given the annotations and full schema, the description covers the experimental nature, current behavior, and usage guidance. It references identical response shape to ask_pipeworx, making it complete without an output schema.

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

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

The schema fully describes all six parameters as aliases for 'question', with 100% coverage. The description doesn't discuss parameters, so it adds no additional meaning beyond the schema. Baseline 3 applies.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,439 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by noting it runs candidate routing improvements. This is specific and informative.

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

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

It explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. This provides a clear when-to-use guideline and the primary alternative. It doesn't explicitly mention when not to use, but 'newest routing' is enough 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 and non-destructive, but the description adds rich behavioral context: the tool uses only the tool result contents, returns a structured output with verbatim evidence, and explicitly refuses with enumerated refusal_reason values. It also discloses a cost tradeoff ('Costs one extra LLM call'), which goes far beyond annotation signals.

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 efficient: it front-loads the core purpose, then systematically covers return format, refusal reasons, use cases, and cost comparison. Every sentence contributes unique information, and the explicit refusal list is a compact way to convey behavior.

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

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

For a complex tool with no output schema, the description covers all necessary context: what it does, how it differs from siblings, when to use it, the exact return shape, and refusal semantics. It even explains the extra-cost tradeoff, making it fully self-contained for an AI agent to decide and invoke correctly.

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

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

Schema coverage is 100% with all six parameters documented as aliases for the same 'question' argument. The description confirms natural language input but adds no new parameter-level detail beyond the schema. Baseline 3 is appropriate since the schema fully covers parameter semantics.

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

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

The description opens with a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly differentiates from siblings by explaining the grounded extraction approach and explicit refusal mechanism, and contrasts with ask_pipeworx by stating 'Same routing as ask_pipeworx' but with grounded answering and refusal on insufficient 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?

Provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, etc.). It also names the alternative: 'prefer ask_pipeworx for casual lookups,' directly addressing when not to use this tool.

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

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

The description goes far beyond annotations, disclosing resolver confidence levels (high/medium/low/none), status routes (low_confidence_match, market_closed_or_inactive), safety suppression of analysis on low-confidence matches, and cancellation-rule risks (refund_50_50, etc.). It also explains fan-out behavior and fallback handling when GDELT 429s. No contradiction with readOnlyHint/idempotentHint/destructiveHint, and it aligns with those 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?

Although long, the description is well-structured with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK), making it scannable. It front-loads purpose and usage before going into detailed behaviors, and every segment adds operational value for an agent invoking this complex 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 describes response shapes (result.market, result.analysis, result.evidence), success and failure/edge-case statuses, safety mechanisms, and resolution pitfalls. It also clarifies what to inspect before trusting analysis (resolver contract) and explains when fields are suppressed. This is comprehensive for a complex tool with many branches.

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

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

The schema covers all 3 parameters with detailed descriptions (including depth enum values and include_raw size implications), and the tool description largely restates that information (e.g., market input types, depth default). It adds no new parameter-level semantics beyond what the schema already provides, so baseline 3 is appropriate. Some context about fan-out behavior relates to the tool's overall behavior, not parameter semantics.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It then specifies input types (slug, URL, question text) and explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. This clearly distinguishes it from sibling tools like validate_claim or ask_pipeworx.

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

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

It provides clear usage context with explicit 'Use for' examples and fan-out illustrations (BTC, Fed, Hormuz, etc.), but it does not name alternative tools or say when NOT to use this tool. For example, it doesn't mention that validate_claim might be better for a yes/no outcome check. This gives clear context without 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, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial non-obvious behavioral context: data sources (SEC EDGAR/XBRL vs FAERS), fiscal-year edge cases (AAPL Sep, NVDA Jan), sorting by primary metric so 'largest' reads off the top, and the return format (paired data + citation URIs). This goes well beyond the structured annotations.

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

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

The description is dense but front-loaded with query examples and usage scope, then efficiently covers data sources, edge cases, sorting, and output format. Every sentence contributes, though the opening sentence is long and packs many examples, making it slightly less scannable than ideal.

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

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

With only 2 parameters and no output schema, the description covers everything needed: supported entity types, count limits (2–5), data sources, fiscal-year handling, sorting behavior, return shape (paired data + URIs), and the performance advantage over sequential lookups. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

The schema documents both parameters with descriptions, but the tool description enriches them significantly: it explains what each type means for data pulling (latest 10-K for companies, FAERS/approval/trials for drugs) and provides concrete examples for values ('AAPL','MSFT','ozempic','mounjaro'). This adds meaning beyond the schema's enum and array item 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 concrete query patterns ('Compare X and Y', 'X vs Y', 'which is bigger') and explicitly states a side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes itself by the 'ALWAYS PREFER over sequential single-pack lookups' note, clearly separating it from single-entity lookup siblings like entity_profile.

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

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

The description explicitly enumerates when to use the tool (comparison queries like 'rank these companies' or 'head to head') and advises preferring it over sequential single-pack lookups. However, it does not name a specific alternative tool or state when NOT to use it (e.g., when only one entity is needed), so it stops short of full when/when-not specification.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds the default current-time behavior, which is a useful behavioral trait beyond the annotation metadata. 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?

Two short sentences, front-loaded with the primary action, no redundant information. Every word contributes to clarifying purpose or 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 conversion tool with a full input schema, output schema, and annotations, the description covers the essential purpose and the one non-obvious behavior (default time). No significant gaps remain.

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

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

Schema coverage is 100%, but the description adds semantic context for the optional 'time' parameter, explaining that omitting it defaults to current time in the source timezone. This enhances understanding beyond the schema.

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

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

Description uses a specific verb ('convert') and resource ('datetime from one timezone to another'), clearly distinguishing from sibling tools like list_timezones or get_time_by_timezone. The action and scope are 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 clear context for when to use this tool (converting between timezones) and specifies the behavior when 'time' is omitted. It does not explicitly name alternative tools, but the intended use is unambiguous and no exclusions are needed.

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

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

Beyond the read-only/open-world/idempotent annotations, the description reveals return structure (findings packet with evidence, confidence, source, fetched_at, pipeworx:// citation), gap handling (gaps[] and never invented), contradiction scanning, hop fields, citation_uri behavior, semantic excerpting, time expectations, and account tier requirements. 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 long, dense paragraph with repetitive mentions of gaps[], contradictions[], and hop details. While each sentence adds some value, the structure would benefit from bullets or shorter sentences. It is not appropriately concise for a tool description, even for a complex 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?

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: findings packet fields, gaps, contradictions, citation URIs, and semantic excerpting. It also covers prerequisites (account plan), timing, supported/unupported topics, and differentiation from alternatives. Highly complete for a research tool.

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

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

Schema coverage is 100% and both parameters already have detailed descriptions. The description adds meaningful context beyond schema: maps depth values to hop behavior and time costs, warns that 'thorough' requires a paid plan, and clarifies that the question can be broad/multi-part. This is more than the baseline 3, though schema already covers the core enum semantics.

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

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

The description states a specific verb and resource: "Grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources" and explains the decomposition + parallel routing to 5,439 tools. It clearly distinguishes from siblings, especially ask_pipeworx, by emphasizing this is NOT open-web search and is for broad/multi-part structured-data questions.

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

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

Explicit when-to-use and when-not-to-use guidance is provided: "Best for broad/multi-part questions over structured data," and "For a single lookup use ask_pipeworx (one LLM call, not many)" plus a strong exclusion for breaking news topics. It also names the alternative tool and warns that unsigned-in users should use ask_pipeworx.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds valuable context about the return payload (top-N results with names, descriptions, and full schemas) and that results are directly callable without further lookups, which is useful behavioral information 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?

Three sentences communicate purpose, usage, and return format efficiently. The list of domains is slightly long but serves to set expectations about coverage, and every sentence earns its place.

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

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

The tool is a meta-search with a simple input schema; the description fully covers what it returns, how to invoke it, and when to use it. Although there is no output schema, the return format is explicitly stated, making the description complete 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%, with all 6 parameters described, including aliases. The description adds no parameter-level detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description opens with a specific verb-resource pair ('Find tools') and scopes it by 'describing the data or task.' It clearly distinguishes this meta-tool from the domain-specific siblings by identifying it as a discovery/search tool rather than a data access tool.

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

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

It explicitly states when to use ('Use when you need to browse, search, look up, or discover...') and provides a 'Call this FIRST' directive, plus notes it's for exploring the option set rather than retrieving a single answer. It doesn't name alternative tools, but the directive is strong and contextually clear.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive. The description adds substantial behavioral details beyond annotations: the parallel fan-out across SEC EDGAR, XBRL, USPTO, GDELT→GNews, GLEIF; the return structure; patents API's sunset soft-fail; and sorting/filtering behavior. It doesn't contradict annotations and enhances 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 dense but remains well-structured with examples up front and a semicolon-separated breakdown of return values. It is long due to the tool's breadth, yet every sentence adds value; a minor deduction for the slightly run-on style and repetitive reference to the resolve_entity fallback.

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 correctly explains the full return payload (CIK, filings with URIs, fundamentals, patents, news, LEI) and caveats (patents soft-fail, name unsupported). It also covers the query intent and alternatives, making it self-contained for an agent to invoke correctly.

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

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

The input schema covers both parameters fully (type enum and value with examples and name limitation), and the description largely restates the same information. With 100% schema coverage, the baseline is 3; the description adds no new semantic detail beyond what the schema already provides.

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

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

The description clearly states the tool's core purpose: "full cross-source profile of a US public company in ONE parallel call." It provides multiple natural-language examples ("Tell me about X", "research Acme") and explicitly distinguishes from sibling tools by advising preference over chaining single-pack lookups and directing name-only requests to 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?

The description explicitly says when to use this tool: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also gives guideline for unsupported inputs: "names not supported (use resolve_entity first if you only have a name)." These clear directives help the agent choose correctly.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context by clarifying the deletion targets 'previously stored memory' and noting it can clear sensitive data, which is beyond the annotation's binary flags.

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

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

The description is three sentences, front-loaded with the core action, and every sentence adds useful context: what it does, when to use it, and how it relates to siblings. 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?

For a one-parameter tool with strong annotations, the description covers purpose, usage triggers, and sibling relationships. No output schema is needed for a simple delete operation, and the description is sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, and the parameter 'key' is already described as 'Memory key to delete.' The description only restates 'by key' without adding new format or constraint details, so it does not elevate beyond 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 a specific verb and resource: 'Delete a previously stored memory by key.' This clearly identifies the tool's function and distinguishes it from sibling tools like remember and recall.

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

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

The description provides explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, but does not explicitly state when not to use it.

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

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

Annotations already declare readonly/idempotent/non-destructive, and the description adds behavioral detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format. Output is a single text blob ready to drop at site-root/llms.txt.' This explains the process and output beyond the safety hints.

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

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

The description is front-loaded with the core action, followed by process detail and use cases in just three sentences. Every sentence earns its place with no redundant or vague content.

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 two-parameter tool with no output schema, the description covers purpose, behavior, output format, and typical scenarios. It lacks error case details, but given the tool's simplicity and the annotation coverage, it is sufficiently complete.

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

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

Schema coverage is 100%, with clear descriptions for both 'url' and 'max_links'. The description does not add additional parameter-specific semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with 'Generate a production-ready llms.txt file for any URL', using a specific verb and resource with clear scope. It distinguishes itself from sibling tools by focusing on generating llms.txt specifically, versus scanning or checking AI presence.

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

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

Explicitly lists three concrete use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' While it doesn't name alternatives to avoid, it gives clear context for when this tool is 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 readOnly and idempotent behavior. The description adds the external resolution chain (ip-api.com → timeapi.io), which is useful behavioral context beyond annotations, indicating dependency on external services. 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, well-structured sentence that introduces the action and method without extraneous words. It front-loads the core purpose and efficiently communicates the essential information.

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

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

Given the low complexity (single parameter) and the presence of an output schema, the description is complete. It explains the external resolution chain, which is sufficient for an agent to understand dependencies and invoke correctly.

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

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

Schema coverage is 100%, with the description of the 'ip' parameter fully specifying IPv4/IPv6. The description adds no additional semantic meaning beyond the schema, so baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: retrieving current date/time for an IP's timezone. It distinguishes from sibling get_time_by_timezone by explicitly referencing IP address as the input. The verb 'Get' is specific and the resource is clearly defined.

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

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

The description implies when to use the tool (when you have an IP address) but does not explicitly mention alternatives or exclusions. It provides clear context that the tool resolves time via IP, so agents can infer its appropriate use. However, no explicit 'use X instead' 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool's safety profile is known. The description adds no further behavioral details beyond stating it returns the current date and time, which is consistent with 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 a single, focused sentence with no redundant information. It conveys the tool's purpose efficiently.

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

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

Given the tool's simplicity—one parameter, a read-only operation, and an output schema presumably documenting return values—the description is sufficiently complete. It covers the purpose and parameter format without unnecessary elaboration.

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

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

The input schema fully documents the timezone parameter with type and description. The description adds value by giving concrete examples of IANA timezone formats (America/New_York, Europe/London, Asia/Tokyo), which aids correct invocation.

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

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

The description clearly states the verb 'get' and the resource 'current date and time in a specific IANA timezone'. It is unambiguous and distinguishes the tool's core function, but it does not explicitly differentiate it from sibling tools like get_time_by_ip or convert_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 provides no guidance on when to use this tool versus alternatives. Sibling tools such as get_time_by_ip and convert_time exist, but the description neither mentions them nor excludes any scenarios. Usage is only implied by the description.

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

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

Annotations already mark this as read-only and idempotent, so the description doesn't need to restate that. It adds value by disclosing that it returns only active subscriptions by default and listing the specific return fields, which is useful behavioral context beyond the annotations. The description does not contradict 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 two sentences, front-loaded with the purpose, and immediately followed by return field details and usage guidance. Every sentence earns its place, with no fluff or repetition of annotation information.

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

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

Given the simple tool (one optional param, no output schema), the description is complete: it states what is returned, the default scope (active only), and when to use it. The lack of pagination details is acceptable for a straightforward read-only list tool, and the annotations cover 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?

The single parameter include_inactive is fully described in the schema (100% coverage), so the description does not need to add parameter semantics. It provides no extra explanation of the parameter, but the schema already covers its meaning and default, meeting the baseline for schema-description 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 lists the caller's active subscriptions, using the specific verb 'list' and resource 'subscriptions'. It also enumerates the exact fields returned, making the purpose unambiguous and distinct 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?

The description explicitly tells when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly addresses the decision points for using list_subscriptions versus subscribe or unsubscribe, providing clear contextual 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, covering the safety profile. The description adds value by specifying the exact data source (timeapi.io) and the count of timezones (590+), which reflects the tool's scope and potential size of response. No contradiction with annotations.

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

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

The description is a single, concise sentence that front-loads the verb and resource, followed by a valuable qualifier ('590+', 'from timeapi.io'). Every word contributes meaning, and there is no redundancy or irrelevant detail.

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

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

The tool is extremely simple with no parameters, rich annotations, and an output schema (though not shown). The description provides the essential context: what is listed, the source, and the approximate size. Nothing critical is missing, and the description fully suffices for an agent to select and invoke the tool correctly.

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

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

The tool has zero parameters, so the baseline score is 4. The description does not need to elaborate on parameters, and the schema already reflects an empty parameter set. No additional parameter meaning is required.

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

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

The description clearly states the tool lists all 590+ IANA timezone strings from timeapi.io, using a specific verb ('List') and resource ('timezone strings'). This unambiguously distinguishes it from sibling time-related tools like get_time_by_timezone or convert_time, which perform different operations.

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 context: use when you need a comprehensive list of IANA timezones. It does not explicitly mention when not to use or name alternatives, but given the tool's simplicity (zero parameters), the context is clear enough. The '590+' detail suggests it's the definitive source for supported timezones.

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 all false provide no safety hints, so the description carries the burden. It adds rich behavioral context: rate-limited to 5 per identifier per day, free and not counted against tool-call quota, team reads digests daily, and content policy (describe in terms of Pipeworx tools, don't paste end-user prompt). This fully discloses constraints and side effects.

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, but every sentence serves a purpose: purpose, use cases, exclusion, content policy, rate limit, quota impact. It could be more concise by removing redundancy (e.g., 'broken, missing, or needs to exist' overlaps with the type enum), but the structure is front-loaded and scannable.

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

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

For a feedback tool with a nested context object and no output schema, the description is fully complete. It covers why, when, what, and constraints. It even explains the operational impact ('signal directly affects roadmap') and boundary conditions ('ONLY for tools served by this Pipeworx connection'). No critical gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful guidance for the message parameter: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This is not present in the schema and clarifies expected content. No new info for type or context, so a 4 is appropriate.

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

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

The description opens with an explicit verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback categories (bug, feature/data_gap, praise) and distinguishes itself from sibling tools by stating this is specifically for Pipeworx-served tools, not other MCP servers.

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

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

The description gives explicit when-to-use criteria: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'if the tool came from a different MCP server in your client... file it with that server instead.' This is textbook guidance for tool 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses important behavioral traits: the source ('CF analytics-engine'), privacy ('no PII'), data format ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This adds significant context not captured elsewhere.

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 a clear opening statement, followed by enumerated use cases and a concise note on data source and caching. Every sentence contributes useful 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?

Given the tool's simplicity (1 optional parameter, no output schema), the description is fully adequate. It clearly states what is returned, the available windows, the use cases, and underlying data characteristics, leaving no significant gaps.

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

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

The schema already provides 100% coverage for the single 'window' parameter, including its enum values and semantic distinction between short and long windows. The description adds a minor note about cache duration depending on the window, but overall it adds little beyond the schema.

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

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

The description states a specific verb ('Returns') and resource ('the top tools, top packs, and total call volume'), clearly defining the tool's function. It also distinguishes itself from siblings like discover_tools or recent_alerts by emphasizing the trending/aggregated nature of the 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 ('Useful for: (1)... (2)... (3)...'), providing clear context on when to employ the tool. It does not name specific alternatives or exclusions, but the guidance is otherwise strong.

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

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

Annotations already indicate read-only, open-world, idempotent behavior, and the description adds rich context: partition filter placeholder rules, semantic similarity threshold (≥0.30 Jaccard), and fill-check pricing against live CLOB depth with the warning that realizable_edge_pp ≤ 0 means 'do not trade it.' No contradiction with annotations.

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

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

The description is long but structured with labeled modes and clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that each contain necessary information. It is front-loaded with the core purpose and every section earns its place, though a slightly tighter edit would be possible.

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

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

Despite having no output schema, the description explains the response shape ('opportunities[] (gap_pp, suggested_trade, reasoning...)' and 'partition_check{...}') and covers edge cases such as skipped_low_similarity, placeholder filtering, and non-tradable book conditions. This is complete for a tool with two optional params and complex behavior.

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

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

Schema coverage is 100%, but the description significantly enriches semantics: it explains event/topic modes, gives concrete examples like 'fed-decision-may-2026' and 'Strait of Hormuz traffic returns to normal,' and clarifies that no args triggers a trending scan. This exceeds 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?

Clearly states the tool's function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling Polymarket tools by naming the detection method and providing mode-specific behavior.

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

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

Provides explicit guidance: 'Call with NO args for a trending_scan... pass event... or topic...' It also recommends when to use each mode ('event recommended for a specific market') and directs users to polymarket_fill_risk for custom sizing, explaining when to use an alternative.

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

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

The description adds extensive context beyond the annotations: it details response structure (by_segment, fed_candidates, _diagnostics), mentions 1-hour KV caching, discloses the Fed signal unreliability, and explains the 24h-move warning. It also clarifies the meaning of knobs like min_partition_leg_kelly and the fact that partition arbs return kelly_fraction_half=0 by design. 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?

This description is heavily overlong and contains numerous details that are not needed for invocation, such as alpha values (tennis 1.02, soccer 1.10), gate thresholds (85%/5%/50:1), and model internals (FRED log-returns, GDELT article-volume ratio). While it is front-loaded with the core purpose, the sheer volume and lack of bullet-point structuring make it hard to parse and extract actionable 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 no output schema, the description thoroughly explains the return structure: by_segment with three segments, fed_candidates, _diagnostics, and per-opportunity fields like edge_pp_net, kelly_fraction, market.liquidity, and the 24h-move warning. It also explains caching and filter behavior, making it entirely self-contained for an agent to understand what to expect.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some high-level context by summarizing the 'TRADEABLE-EDGE KNOBS' group and mentioning that edge is evaluated net of slippage, but most of this is already present in the parameter descriptions. It does not add substantial meaning that the schema lacks.

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

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

The description clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This is a specific verb+resource combination, and it distinguishes itself from siblings like polymarket_arbitrage by emphasizing the Pipeworx data source and the 'what should I bet on today' use case.

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

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

The description provides clear usage context — it's for discovering opportunities without paging through hundreds of markets and mentions it filters by tradeable-edge knobs. However, it does not explicitly describe when to use this tool versus siblings like polymarket_edge_tracker or polymarket_arbitrage, so it lacks explicit exclusions or alternative comparisons.

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 readOnlyHint and other annotations, the description discloses extensive behavioral details: decay is computed on |edge_pp_net| using daily closes, value sign indicates trade direction, history is bounded by a 60-day TTL, snapshot gaps signify no scan, and expired opportunities represent closed/resolved/arbed-away events. These limitations and semantics materially help an agent interpret results correctly.

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

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

Although lengthy, the description is tightly structured: purpose, use-case analogy, arguments, detailed response fields, and limits. Every sentence carries unique information—no filler or redundancy. The front-loaded purpose and response schema analogue make it easy to scan.

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

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

Given the complexity of telemetry across time-series snapshots and the lack of an output schema, the description is exceptionally complete. It explains all response components (tracked[], expired[], snapshot_dates[]), the meaning of trend/decay, the impact of TTL and gaps, and the source of snapshots. An agent can confidently invoke the tool and interpret results without further clarification.

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

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

Schema description coverage is 100% for both parameters, so the schema already fully documents days and window. The description adds minor context by calling window a "snapshot family" and restating defaults, but it does not introduce new syntactic or semantic details beyond the schema.

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

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

The description opens with a specific verb and resource: "Edge persistence and decay telemetry built from daily polymarket_edges snapshots," and immediately frames the question it answers: "how long has this edge existed and is it shrinking?" This clearly distinguishes it from the sibling polymarket_edges tool, which likely shows current edges, by focusing on temporal history and trend.

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

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

The description provides clear context for when to use the tool: when edge age and decay matter, as in "a fresh wide edge and a 3-week-old wide edge are different trades." It also explains how snapshots are produced and what gaps mean. However, it does not explicitly name alternatives or state when NOT to use this tool, leaving the comparative guidance implicit.

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

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

Annotations already declare read-only, idempotent, non-destructive, but the description adds critical behavioral context: it walks the order book ladder, returns a verdict, and warns that partial basket fills convert an arb into an unhedged directional position. This goes well beyond the annotations and covers risk implications.

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

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

The description is long but dense with value; it front-loads the purpose and follows with mode-specific details and return fields. While verbose, each sentence contributes essential information for a complex tool, making it appropriately sized for the capability.

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

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

With no output schema, the description enumerates the key return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; basket: theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also explains edge cases like partial fills and thin books, making the tool's behavior and potential pitfalls clear.

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

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

Schema description coverage is 100%, but the description adds essential meaning: it explains the single-market vs basket interpretation of each parameter, the default behavior of 'side' in basket mode (auto from partition sum), and the meaning of 'size_usd' as settlement notional (shares per leg paying $1). It also highlights the logical requirement to provide one of 'market' or 'event', which is not captured in the schema's optional fields.

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly stating the tool's function. It explicitly differentiates from sibling tools by naming them ('polymarket_arbitrage', 'polymarket_edges') and specifying when this tool should be used relative to them.

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

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

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains mode selection (single-market vs basket) and the required parameter ('REQUIRES one of market or event'), including value constraints and defaults.

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 a safe, read-only, idempotent operation, but the description adds substantial behavioral detail: two execution modes, compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and skipped cross-type/subtype counters. It even explains the meaning of specific warning conditions, going well 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 quite long but well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and uses bullet-like inline separators. Each sentence contributes important details given the lack of an output schema. Some redundancy could be trimmed, but the complexity justifies the 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?

Without an output schema, the description carries the full burden of explaining return values and edge cases. It clearly describes the response shape (leg-by-leg prices, matched spread, compatibility_warning, temporal_alignment, skipped counters) and what each means. The warning about non-equivalent bet shapes and temporal misalignment covers likely failure modes, making the description complete for a tool of this complexity.

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

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

The schema descriptions already cover the three parameters with 100% coverage. The description adds extra value by explaining the topic shortcut list, showing examples for kalshi_event_ticker and polymarket_event_slug, and clarifying the override behavior. This goes beyond the schema but is not overly verbose, earning a score 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 opens with a clear statement of purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the resource (Kalshi and Polymarket) and the action (computing spreads), and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison rather than single-venue strategies.

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

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

The description gives explicit context on when to use the tool and how to choose between the two modes: topic shortcuts vs explicit ticker/slug. It also warns that 'most pre-mapped topics return compatibility_warning today' and that 'pre-mapped ≠ tradeable,' steering users toward explicit pairings. However, it does not directly compare against alternative tools, so the guidance is strong within the tool but not across the sibling set.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by disclosing the scoping behavior: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' It also clarifies the dual behavior of listing all keys, which is not fully captured by 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 three sentences, each serving a purpose: the first states the action, the second provides use cases, and the third explains scoping and companions. No redundant filler.

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

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

Given the simple tool (one optional parameter, no output schema) and robust annotations, the description is complete. It covers the alternative behavior (list all), scoping, and integration with 'remember' and 'forget', which is sufficient for an agent to invoke it correctly.

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

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

Schema coverage is 100% and the parameter description already mentions omitting the key to list all keys. The description adds concrete examples of key values ('user's target ticker, an address, prior research notes') which aids the agent in choosing appropriate keys.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb+resource and distinguishes from the sibling tools by naming the companion 'remember' and 'forget' tools.

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

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

The description provides explicit use cases: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also establishes the relationship with sibling tools ('Pair with remember to save, forget to delete'), though it does not explicitly list exclusion conditions.

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 annotation readOnlyHint=true contradicts the description's statement that mark_read:true 'flag[s] returned events read so the next call only shows newer ones.' Marking events read is a state change, violating the read-only hint. This is a serious contradiction, so the score is 1 despite the useful context about payload.

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 concise, front-loaded sentences. Each sentence adds distinct value: purpose, return payload details, filtering options, mark_read behavior, and an alternative access method. 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?

The description covers the return fields, filtering by type and timestamp, mark_read semantics, polling suitability, and an external HTTP endpoint. It does not explain unread_only, but the schema covers that. For a 5-optional-param tool without an output schema, this is quite 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?

All five parameters are already described in the schema (100% coverage), but the description adds meaningful nuance for mark_read (explains the effect on subsequent calls) and clarifies the return payload. This exceeds the baseline for schema-covered 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?

The description clearly states 'Pull fired events from your subscription feed' with a specific verb and resource. It distinguishes from sibling tools like list_subscriptions and recent_changes by focusing on fired alerts from a persisted feed.

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

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

Provides clear context: polling works fine, and an alternative HTTP endpoint is given for scripts/dashboards, implying when to use an external alternative. Does not explicitly exclude specific MCP siblings but gives sufficient 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?

Discloses multi-source fan-out behavior (SEC, GDELT/GNews, USPTO), fallback logic (GDELT preferred, GNews on rate-limit/5xx), and the patent API sunset soft-fail. This goes well beyond the readOnly/idempotent annotations.

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

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

The description is dense but every sentence carries valuable information: user query examples, source details, fallback behavior, parameter syntax, output format, and an alternative tool reference. No fluff or redundancy.

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

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

With no output schema, the description fully explains return structure (changes[], total_changes, citation URIs) and covers error/fallback scenarios. It provides sufficient context for a complex multi-source tool.

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

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

Schema coverage is 100%, but the description adds meaningful parameter context: provides examples for the 'since' parameter (ISO vs relative shorthand), recommends '30d'/'1m', and clarifies accepted value formats (ticker or CIK). This exceeds 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 provides a change feed for a company over a time window, with examples of natural language queries. It explicitly distinguishes from sibling tool entity_profile, making its 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?

Provides clear usage context through example queries and explicitly directs users to entity_profile for static profile needs, effectively differentiating when to use this tool vs an alternative.

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

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

The description adds valuable behavior beyond annotations: memory is scoped by identifier, authenticated users get persistent memory, and anonymous sessions retain memory for 24 hours. These details go beyond the safety-oriented annotations.

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

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

The description is three concise, well-structured sentences. It front-loads the primary action and includes usage context and related tools without any wasted words.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, usage, persistence behavior, and relationships to recall/forget. It is fully sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100% and both parameters already have descriptive examples. The description reinforces the key-value nature but does not add significant new parameter 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 saves data for later reuse, with specific examples (resolved ticker, target address, user preference). It also distinguishes from sibling tools by mentioning recall and forget for retrieval and deletion.

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 'Use when' guidance with concrete scenarios and names alternatives (recall, forget). This makes it clear when to choose this tool over its siblings.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals that each call cascades through multiple lookup endpoints internally—an important behavioral trait that affects performance and usage. It also explicitly states the return structure (ticker, CIK, company_name, citation URI; RxCUI, ingredient, brand), which is not present in the schema or 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 well-structured: it starts with example user queries, then the main purpose, then supported types with return details, and ends with the substitution note. Every sentence carries meaningful information, and despite its length (~100 words), it remains focused and scannable.

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

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

Given the tool has no output schema, the description compensates fully by specifying return values for each entity type, including citation URIs. It also covers input flexibility, disambiguation, and internal cascading behavior, making the tool's behavior understandable without needing extra lookups.

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 full descriptions for both parameters (type and value), so the baseline is 3. The description goes further by giving concrete examples (e.g., 'AAPL', '0000320193', 'ozempic') and clarifying the auto-disambiguation behavior for company inputs, adding practical meaning beyond the schema.

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

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

The description clearly states the tool's function with a specific verb ('resolve') and a well-defined resource ('user-spoken NAME to the canonical/official identifier'). It also explains the two supported entity types (company, drug) and what each returns, making it easy to distinguish from sibling tools like entity_profile or compare_entities.

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

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

The description provides an explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' It also explains when the tool is appropriate via example queries. However, it does not mention when not to use it or mention alternative tools, so it stops short of a full when/when-not/alternatives structure.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also mentions the output fields (score, confidence, signal density). No contradictions with annotations; the description complements them well.

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

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

The description is two sentences, front-loaded with the main purpose, followed by the use case and output. Every sentence adds value: the first defines functionality, the second gives an example and return format. No fluff or repetition of schema details.

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

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

For a multi-entity comparison tool with no output schema, the description is complete. It specifies the probe mechanism, ranking behavior, and output fields, and ties it to a concrete use case. The schema covers entity count and API key details, and the description fills the behavioral gap. The tool's complexity is well addressed.

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

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

Schema description coverage is 100%, and the schema already documents all four parameters with meaningful descriptions (e.g., entities as 2-8 items, _apiKey for Anthropic). The description adds minimal parameter-level detail beyond the schema, such as the narrative subject role, but that is already present in the schema. Baseline 3 is appropriate as the schema carries the heavy lifting.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, with a specific verb ('Compare'), resource ('AI visibility across entities'), and scope ('side-by-side'). It distinguishes itself from siblings by explicitly mentioning it probes each entity with ai_visibility_check and ranks them, making it different from single-entity tools like ai_visibility_check or generic comparison tools like compare_entities.

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

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

The description provides a clear usage context: 'Useful for competitive AI-marketing audits' with an example query. It implies when to use this tool (when comparing multiple entities) but does not explicitly state when not to use it or mention alternatives like compare_entities. The context is clear enough for an agent to decide, but lacks explicit exclusions.

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

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

Annotations already indicate read-only/idempotent, and the description adds rich behavioral context: composite fan-out, partial failure degradation, potential 5-30s delay on first bundlephobia measurement, sources_failed listing, and that the rest of the data still returns. 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 information-dense but front-loaded with the core purpose. Each sentence adds value (usage, return contents, limitations, failure behavior). Slightly verbose but appropriate for the composite nature; not wastefully long.

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 return values—it enumerates the summary fields and mentions per-advisory detail, links, and alternative versions. It also covers ecosystem limitations, latency, and partial failures, making the tool's behavior well understood for an agent.

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

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

Schema coverage is 100%, so baseline 3 applies. The description does not add new parameter semantics beyond what the schema already states; it mentions version defaults and scoped packages implicitly, but those are already in the schema. No extra value.

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

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

The description opens with a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call'. It clearly distinguishes from sibling tools by naming the exact data sources (deps.dev, bundlephobia) and the scope (npm packages), which no sibling covers.

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

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

Explicit usage triggers are given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion/alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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

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

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, the description adds concrete behavioral detail: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K character cap with truncation flagging, and passage offsets for quote verification. This goes well beyond the annotation hints and no contradiction exists.

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

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

The description is concise despite its length: four sentences cover purpose, usage trigger, sibling pairing, return format, and algorithmic constraints. It uses bold key phrases and front-loads the core purpose. Every sentence adds actionable information.

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

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

For a search tool with 3 parameters and no output schema, the description fully compensates by detailing return values (top-N passages with offsets and similarity scores), the 200K character cap, truncation behavior, and the intended workflow with ask_pipeworx_grounded. The annotation set covers safety, so no critical behavioral gaps remain.

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

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

With 100% schema description coverage, the baseline is 3, but the description enriches semantics by clarifying that text is 'already pulled,' has a 200K char cap, and that longer inputs are truncated and flagged. It also ties the query to natural-language examples in the schema. This adds value beyond the schema's property 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 'Semantic search INSIDE a fetched record,' naming the specific verb (search), resource (text within fetched record), and operation (retrieve passages). It clearly distinguishes itself from siblings by contrasting with ask_pipeworx_grounded and by emphasizing that it operates on text already supplied, not on retrieval.

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

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

It explicitly states when to use it: when a record is too big to fit in the prompt, because it returns only relevant passages and saves context. It pairs with ask_pipeworx_grounded, instructing to fetch with the gateway and ground over relevant passages, giving clear alternative/complementary usage.

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

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

Beyond annotations, the description discloses authentication requirements (OAuth, anonymous/BYO cannot persist), delivery details (email/sms, phone verification, 10/day cap), and channel behavior. This adds significant context to the bare readOnly/idempotent hints.

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

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

The description is dense but well-organized: purpose, auth, types, delivery. Each clause adds distinct information. It's a bit long, but efficient for the complexity.

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

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

For a creation tool with nested params, the description covers auth, all supported types with examples, delivery options, constraints, and the always-on feed. There's no output schema, but the return value (subscription id) is stated. This is complete given the 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?

The description enriches the schema by providing concrete examples for each type and clarifies the meaning of params (e.g., items:['5.02'] for officer changes). It doesn't cover all enum types, but the schema already documents each, so the description adds value without redundancy.

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

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

The description opens with a specific action: 'Create a proactive monitoring subscription to a live-data event stream' and identifies the resource (subscription). It also states the return value (subscription id) and clearly distinguishes itself from sibling tools like list_subscriptions and unsubscribe.

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

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

It clearly implies when to use this tool (to create subscriptions) and even references related tools ('pull via recent_alerts'), giving context. However, it doesn't explicitly state alternatives or exclusions, so it's strong but not perfect.

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

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

Annotations already declare read-only and open-world hints, so the bar is lower. The description adds valuable context: it returns category-bucketed example questions with exact tool and argument shapes, derived from a live catalog, and explains the no-argument/full-spread behavior. 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 a single, dense paragraph that front-loads example questions before the purpose. While longer than the shortest options, every sentence earns its place, covering usage, return values, and parameter behavior. Slightly verbose but well-structured.

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

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

For a tool with one optional parameter, no output schema, and robust annotations, the description is fully complete. It explains the return format, parameter semantics, usage context, and even how it relates to other meta-tools, leaving no significant gap for an agent to infer incorrectly.

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

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

The input schema already documents the 'topic' parameter with 100% coverage, but the description expands on it by listing example values ('finance', 'pharma', 'betting') and clarifying that omitting it yields a cross-category spread. This adds meaning beyond the schema, so a score above baseline is warranted.

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 'the onboarding entry point for an agent that just connected' with a specific verb (suggest) and resource (questions). It distinguishes itself from siblings by emphasizing it should be used FIRST and that it teaches how to call meta-tools, making its 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?

Provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also says to omit 'topic' for a full spread, but does not explicitly state when not to use it or name alternatives, so a minor deduction.

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 reveals critical behavioral details beyond annotations: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' It also discloses ownership enforcement, which is not implied by the annotations. This adds significant context about side effects and permissions, going beyond the readOnlyHint/destructiveHint flags.

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

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

The description is two sentences long, with the action front-loaded ('Cancel a subscription by id') followed by a single behavioral note. Every word adds value: ownership enforcement and deactivation semantics are both essential. No unnecessary fluff.

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

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

For a simple tool with one parameter and no output schema, the description is fully complete. It covers the core action, a key constraint (ownership), and the important side effect (deactivation not deletion). This is sufficient context for an agent to select and invoke the tool correctly without needing additional 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?

With 100% schema description coverage, the schema already fully documents the id parameter as 'Subscription id (uuid) returned by subscribe.' The description simply repeats 'by id' without adding new semantic meaning, so it matches the baseline without enhancing parameter understanding.

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

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

The description clearly states the action 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from sibling tools like subscribe and list_subscriptions by focusing on cancellation. The title 'Unsubscribe from Alerts' adds context, making it unambiguous.

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

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

The description gives explicit instructions to cancel by id and notes ownership enforcement ('you can only cancel your own subscriptions'). While it doesn't explicitly name alternatives like subscribe or list_subscriptions, the context is clear that this is for canceling existing subscriptions, making it a clear usage directive with an implicit constraint.

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 readOnly/idempotent annotations, the description discloses the tool's routing behavior, the tolerance_pct override semantics with a default cap, and the output structure (verdict, actual value with citation, reasoning). It also mentions the replacement of a multi-step workflow, giving agents context on how the tool behaves internally.

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

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

The description is long but front-loaded with trigger phrases and core purpose. It packs substantial detail (routing, output, replacement value) into every clause. Minor redundancy in the trigger phrase listing, but overall appropriately sized for the tool's complexity.

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

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

Given the tool's complexity, the description covers usage scenarios, routing logic, output format (including verdict types), and explains the tolerance parameter thoroughly. No output schema exists, but the description compensates by fully detailing return information, making it contextually complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantics for tolerance_pct (how to set for hallucination detection, default implied by wording capped at 5) and clarifies that claim is a natural-language factual statement with examples, going beyond the schema.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, with specific trigger phrases like 'fact check' and 'verify the claim that…'. It distinguishes itself from sibling tools by detailing its dual-path routing (SEC EDGAR+XBRL fast path vs. grounded pipeline) and by noting it replaces 4–6 sequential calls.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides examples. It also differentiates when to use the structured financial path vs. the grounded pipeline for other claims, which serves as a clear usage guide compared to alternative tools.

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