videogames

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

With annotations already marking the tool as read-only and safe, the description adds transparency about external LLM calls, cost implications ('you pay Anthropic directly'), and the free default model. This goes beyond the annotation baseline and provides useful operational context.

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

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

The description is three sentences, front-loaded with the core action and output, followed by the default behavior and example use cases. Every sentence contributes meaning, 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?

The description covers purpose, per-model return structure, combined view, defaults, optional call behavior, and practical use cases. Since there is no output schema, the explicit return format is valuable and makes the tool self-contained.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by naming the concrete default model (Llama-3.3-70b), clarifying the cost for Anthropic usage, and noting the raw response output. These details are not fully present in the schema descriptions.

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

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

The description clearly states the tool's purpose with a specific verb ('Probe'), resource ('LLMs'), and output ('score visibility 0-100'). It is more specific than its name, but it does not explicitly distinguish itself from sibling tools like scan_competitor_ai_presence, so it misses the full sibling-differentiation criterion.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional Anthropic key. However, it does not mention when not to use the tool or point to alternatives, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds context about internal routing, 'one fast call', 'works on every tier', and stable 'pipeworx:// citation URIs' — useful behavioral details not present in annotations. No contradictions.

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

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

The description is longer than average but well-structured: a bolded preference directive, use-case list, example queries, and escalation guidance. It remains focused and front-loaded; a minor redundancy like 'START HERE' repeating 'default entry point' keeps it from a 5.

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

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

Despite no output schema, the description fully covers return behavior (structured answer with citation URIs), scope (5,354 tools), and edge cases (breaking news routed to live news packs). It also references sibling tools for alternative needs, making the tool self-sufficient 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 description coverage is 100% and all parameters are aliases for 'question', with each alias explicitly documented. The description adds real-world question examples but no new parameter syntax or semantics; the schema already carries the full burden, 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 states a specific action ('routes the question to the right one of 5,354 tools') and resource ('verified sources'), and clearly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research. It also lists concrete example queries, making the 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?

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', then gives clear alternatives: 'for a hallucination-resistant single answer use ask_pipeworx_grounded; for broad/multi-part fan-out use deep_research'. This provides when/when-not guidance with exact sibling names.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds crucial context: it's experimental, may have live candidate routing changes, and currently matches ask_pipeworx exactly. It also clarifies it is a full working router, not a fallback stub. This goes beyond annotations without contradiction.

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

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

The description is moderately detailed but each sentence serves a purpose: explaining beta status, current state, usage, and fallback. It could be slightly trimmed but is well-structured and front-loaded with the most important differentiator.

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 universal router with no output schema, this description is remarkably complete: it covers what the tool does, how it differs from stable, when to use it, and that response shape is identical. It also addresses the experimental aspect and evaluation process, leaving little ambiguity.

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

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

Schema covers 100% of parameters (question with aliases), and the description adds that arguments are the same as ask_pipeworx, reinforcing cross-tool consistency. However, it does not elaborate on syntax or behavior beyond what the schema provides, so it stays at 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?

Description clearly identifies this as a beta version of ask_pipeworx, a universal router that routes questions to 5,354 tools. It distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements. This specific verb+resource clarity sets it apart from sibling tools.

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

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

Description states to use it exactly like ask_pipeworx when wanting the newest routing, and notes that results are compared against the stable router to decide merges. It does not explicitly list when-not-to-use scenarios, but the alternative stable router is implicitly referenced. This gives clear context for selection.

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

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

Even though annotations declare read-only and idempotent, the description adds rich behavioral details: the exact success return object with evidence, confidence, source, and refusal_reason:null, as well as enumerated refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also discloses the extra LLM call, which is not in annotations. No contradiction.

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

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

The description is front-loaded with the core purpose and then efficiently conveys routing, output contract, refusal reasons, use cases, and cost trade-off. Every sentence provides actionable detail; there is no fluff or repetition.

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

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

With no output schema, the description fully covers the return value structure, refusal reasons, and when to use the tool. It also clarifies the difference from the sibling ask_pipeworx and the cost implication, making the tool self-contained for correct invocation.

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

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

The input schema has 100% coverage—all six parameters are documented aliases for the same 'question' parameter. The description mentions 'fills arguments' but provides no additional parameter-specific semantics or syntax beyond the schema. Thus, the schema is sufficient and the description adds no extra value here.

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 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes it from ask_pipeworx by emphasizing evidence extraction and refusal behavior. It states the specific action: routes to appropriate tools, fetches data, and extracts answers using only tool results.

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

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

Explicitly states when to use the tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples. It also provides an exclusion and alternative: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost.

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, non-destructive, idempotent behavior. The description goes far beyond by detailing the resolver contract (match confidence, alternatives, suggestions), response shapes (market, analysis, evidence), news fallback flags, wide-spread tradeability warnings, and cancellation-rule parsing. This is exceptional transparency.

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

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

The description is long but exceptionally well-structured, using all-caps section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loading the core purpose in the first sentence. Every section adds substantive information, making the length justified.

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

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

With no output schema, the description must explain return values, and it does so comprehensively: market fields, analysis fields (including the 24h-move warning), evidence keyed by source, parent_event extractor, news fallback flags, and blocking statuses. It also covers resolution-rule risk, a critical edge case. This is a model of completeness.

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

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

Schema description coverage is 100%, with each parameter (market, depth, include_raw) already described in the input schema. The description adds contextual examples (e.g., fan-out variations) but does not materially enhance parameter-level semantics beyond the schema, so a baseline 3 is appropriate.

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

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

The description opens with a clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further specifies input types (slug, URL, question text) and the classification/fan-out process, distinguishing it from sibling tools like polymarket_edges or deep_research.

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

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

Explicitly states intended use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides fan-out examples and mentions blocking conditions for closed markets and low-confidence matches. However, it does not explicitly name alternative tools or state when NOT to use it, so a 4 instead of 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds substantial context: sourcing from SEC EDGAR/XBRL and FAERS, handling off-calendar fiscal years, sorting by primary metric, and returning citation URIs. This goes well beyond annotation hints and gives the agent accurate expectations of behavior.

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

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

Although somewhat long, every sentence provides distinct value: triggers, core function, per-type details, sorting, return format, and efficiency. The structure is front-loaded with user intents, then implementation details, making it scannable and information-dense without fluff.

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

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

Given no output schema, the description fully compensates by stating it returns paired data + citation URIs, sorted by primary metric. It also covers edge cases (off-calendar fiscal years) and the number of entities allowed. No critical usage aspect is left unexplained.

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

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

Schema covers both parameters, but the description enriches meaning by detailing that type='company' pulls specific financial metrics, while type='drug' pulls adverse-event and trial counts. It also provides concrete examples for values (e.g., tickers vs drug names), adding practical semantics not present 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 tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with explicit trigger phrases like "X vs Y" and "which is bigger." It distinguishes itself from sequential lookups and scope-limits to 2–5 entities, which disambiguates it from potential sibling tools 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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear when-to-use directive and an implicit alternative (sequential lookups). This is strong usage guidance for an AI agent to select it over other tools.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description reveals key behaviors: account/paid-plan requirements, output structure (findings packet with evidence, confidence, gaps[], contradictions[]), the hop mechanism, semantic excerpting, and expected latency (15-90s). This is rich behavioral disclosure that adds substantial context beyond the structured fields.

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 and dense, but every clause serves a purpose (auth, output format, timing, depth differences, limitations). It is front-loaded with the most actionable info (ACCOUNT REQUIRED and the ask_pipeworx fallback). However, it reads as a run-on paragraph; clearer structuring (bullets or sections) would earn a 5.

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

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

Given no output schema, the description thoroughly covers return values: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also addresses auth, cost, latency, and edge cases (breaking news yielding empty gaps), making it fully complete for a complex 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?

With 100% schema coverage, the baseline is 3. The description adds extra meaning by explaining that depth:'thorough' requires a paid plan and that 'standard' and 'thorough' also return contradictions[] — details not fully captured in the schema's enum descriptions. This pushes it above 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 clearly states the tool's function: grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets and routing to 5,354 tools in parallel. It explicitly distinguishes itself from siblings by noting 'this is NOT open-web search' and naming ask_pipeworx as the alternative for simpler lookups.

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

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

The description provides explicit when-to-use and when-not-to-use guidance. It says 'Best for broad/multi-part questions over structured data', directs users to ask_pipeworx for single lookups and breaking/current-news topics, and even notes the account requirement with a fallback. This excels beyond typical sibling differentiation.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it explains the return format ('top-N most relevant tools with names, descriptions, and full input schemas'), notes that results include curated examples, and clarifies that no second schema lookup is needed. This goes beyond the safety profile covered by annotations.

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

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

The description is three sentences and front-loaded with the core purpose. The domain list is lengthy but directly supports the discoverability function, and each clause provides useful information (scope, return behavior, usage directive). No filler sentences are present, though the domain enumeration could be trimmed if the schema already covered it.

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

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

With no output schema, the description must explain return values, and it does: 'names, descriptions, and full input schemas (with curated examples)' and 'ready to call directly.' It also covers when to use the tool. The absence of output schema is compensated by this description, though it doesn't mention error cases or edge behavior, which would warrant a 5.

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

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

Schema coverage is 100% for all 6 parameters, so the schema already documents each parameter. The description adds minimal semantic value for parameters, only reinforcing 'top-N' (for limit) and 'describing the data or task' (for query). Since the schema carries the heavy lifting, the baseline of 3 is appropriate.

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

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

Description clearly states the tool's function: 'Find tools by describing the data or task.' It specifies a concrete verb ('find') and resource ('tools'), and the list of domains (SEC, FDA, FRED, etc.) makes the scope explicit. The addition 'Call this FIRST' distinguishes it from sibling tools that are task-specific.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also hints at when not to use it ('not just one answer'), but it does not name specific alternatives among sibling tools, so it falls short of a 5.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds substantial behavioral detail: it fans out across multiple sources in parallel, lists exactly which fields are returned, discloses the patents API sunset ('soft-fails until reactivated'), and explains the GDELT→GNews fallback chain for news. It also mentions the sort order for fundamentals and the URI scheme for filings, all valuable context not provided by annotations.

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

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

The description is front-loaded with user-intent examples and a clear purpose statement. It is lengthy but information-dense: every sentence covers a distinct aspect (sources, return fields, fallbacks, input constraints). The opening example list could be slightly trimmed, but the structure is logical and each element 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 complex (multi-source, no output schema), yet the description is remarkably complete: it lists all return fields (cik, recent_filings, fundamentals, patents, news, LEI), specifies limitations (US public company, patents sunset), explains fallback behavior, and details input requirements. This is sufficient for an agent to invoke and correctly interpret results.

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

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

The input schema fully covers both parameters: type has an enum description and value clearly states 'Ticker (e.g., AAPL) or zero-padded CIK (e.g., 0000320193). Names not supported — use resolve_entity first.' The description repeats these details and adds example queries but does not introduce new parameter semantics. With 100% schema coverage, 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 explicitly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides multiple concrete example queries ('Tell me about X', 'company profile for Microsoft') and lists the data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), making it clear and distinctive. It also differentiates from sibling tools by recommending it over chaining single-pack lookups.

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a clear exclusion: 'names not supported (use resolve_entity first if you only have a name),' directly naming an alternative tool.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description doesn't need to repeat that. It adds behavioral context by explaining the tag-matching format and the fields returned, which goes beyond the schema. No contradictions found.

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

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

Two sentences deliver all essential information: the filter action, required/optional inputs, and output fields. The first sentence is front-loaded with the main purpose, and every clause earns its place without redundancy.

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

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

Given the tool's simplicity, the presence of an output schema, and comprehensive annotations, the description covers the important aspects: what is filtered, how the tag format works, and what data is returned. It doesn't mention error handling or invalid tag formats, but these are not critical for simple read-only filtering and are likely covered by the 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 already describes both parameters (tag and platform) with examples, achieving 100% coverage. The description repeats these examples and adds the concept of a 'dot-separated tag combination', but this is already in the schema's example and description. Thus the description adds minimal new 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 action ('Filter free-to-play games'), the specific resource (FreeToGame), and the distinguishing mechanism (dot-separated tag combination, optional platform). It also lists the return fields, making the purpose unambiguous and distinct from sibling tools like list_games or get_game.

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 clear context on when to use this tool (when filtering by tags and platform), but it does not explicitly name alternatives or state when not to use it. The examples help clarify expected inputs, so context is solid, just lacking 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 provide destructiveHint=true and idempotentHint=true. The description aligns with these but doesn't add new behavioral details such as irreversibility, no-op behavior for missing keys, or return format. It does clarify the scope of previously stored memories.

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

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

Two sentences, front-loaded with the action, then usage guidance. No unnecessary words.

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

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

For a simple one-parameter deletion tool with annotations covering destructive and idempotent hints, the description adequately covers purpose, usage, and pairing. Missing return value behavior, but no output schema exists and this is a simple tool.

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

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

Schema covers 100% of parameters, with the key property described as 'Memory key to delete'. The description reinforces 'by key' but adds no additional format 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 uses the specific verb 'Delete' with the resource 'previously stored memory' and method 'by key'. This clearly distinguishes 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?

Explicitly states three use cases: stale context, task done, clearing sensitive data. It also suggests pairing with remember and recall, giving complementary tool context. However, it doesn't state when not to use or mention alternative tools by name.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', which goes beyond the annotations and informs the agent about the operation flow.

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

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

The description is two sentences plus a use-case list, all front-loaded. The first sentence covers the core purpose, the second the process, and the list provides context—no wasted words.

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

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

Despite having no output schema, the description explicitly states 'Output is a single text blob ready to drop at site-root/llms.txt', covering the return format. Combined with annotations and clear process, it's complete enough for this simple read-only 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%, so the baseline is 3. The description mentions 'any URL' and the output format but doesn't add parameter-specific details beyond the schema. It clarifies the output is a single text blob, which is more about output than 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 clearly states 'Generate a production-ready llms.txt file for any URL', establishing the specific action and resource. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on generating the file itself rather than checking 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?

The description provides explicit 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.' It doesn't mention exclusions or alternative tools, but the context is clear enough to guide selection.

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

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

Annotations already establish the read-only, idempotent, non-destructive nature, so the description needs only add supplementary context. It lists return fields and implies the need for a valid FreeToGame ID, but does not disclose error behaviors or rate limits. Given the strong annotation coverage, the description is adequate but not rich, warranting a baseline score.

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 exceptionally concise and front-loaded: the first sentence states the exact action and scope, and the second enumerates the expected output fields. There is no redundant information, and every word contributes to clarity.

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

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

Given the tool's simplicity (one parameter), full schema documentation, an output schema, and comprehensive annotations, the description provides all necessary context. It clearly identifies the resource, the input, and the content of the response, making it complete without needing to restate structured data.

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 id parameter with a concrete example ('452 for Valorant'), and the description merely echoes that the ID is a FreeToGame ID without adding new meaning. With 100% schema coverage, the description adds no additional parameter semantics, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: retrieving complete details for a specific game by its FreeToGame ID. It explicitly lists the return fields (title, description, genre, platform, publisher, developer, release date, screenshots, and minimum system requirements), and differentiates it from sibling tools like list_games and filter_games, which operate on collections. The verb 'Get' and specific resource make the action 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 implies a targeted lookup context by specifying 'by its FreeToGame ID', suggesting usage when you already have an ID and need full details. However, it does not explicitly state when to prefer alternatives like list_games or filter_games, nor does it provide exclusion guidance. The context is clear but not formally articulated.

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 cover read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable context by specifying the data source (FreeToGame) and stating that it 'returns all matching games,' which implies no hidden pagination limits and sets expectations for output completeness.

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?

One succinct, front-loaded sentence covers all key aspects: the resource, source, optional filters, sort options, and return behavior. No wasted words; every phrase adds value.

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

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

Given the tool's moderate complexity, the rich parameter schema, output schema availability, and comprehensive annotations, the description is complete. It covers source, filtering, sorting, and return semantics, so an agent has enough context to invoke it correctly.

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

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

The schema description coverage is 100%, with each parameter already having a clear description of allowed values. The tool description restates the filterable fields and provides examples, but adds little beyond the schema. Baseline 3 is appropriate since schema does 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 uses a specific verb ('List') and resource ('free-to-play games from FreeToGame'), and clearly conveys the tool's scope via optional filters and sorting. This distinguishes it from siblings like get_game and filter_games, which target specific entities or more refined filtering.

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 need a list of free-to-play games with optional filtering/sorting) but does not explicitly mention exclusions or alternatives. The sibling list makes it easy to infer, but there is no direct 'use X instead' guidance, so it falls short of a 5.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the description doesn't need to repeat that. It adds value by revealing the exact fields returned (id, type, params, created_at, last_fired_at, fire_count) and clarifying that only the caller's subscriptions are shown. This goes beyond the structured metadata.

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 primary purpose, then return fields, then a practical use case. Every sentence carries useful information with no fluff or repetition.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is reasonably complete. It covers the scope ('caller's subscriptions'), the returned fields, and the intended use case. It does not mention potential quirks like pagination or rate limits, but these are not critical for a basic list operation and the annotations cover safety aspects.

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

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

The input schema covers the only parameter (include_inactive) with a complete description, so the schema already documents the semantics. The tool description does not add additional meaning to the parameter, but it does imply the default behavior by saying 'active subscriptions'. This aligns with the schema's default of false, yet no extra detail is provided.

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

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

The description clearly states the tool lists the caller's active subscriptions, using a specific verb and resource. It distinguishes itself from sibling tools like subscribe and unsubscribe, and even enumerates the return fields for clarity.

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

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

The description provides explicit when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies this is the appropriate tool for reviewing subscriptions before subscribe/unsubscribe actions, though it does not explicitly state when not to use it or mention alternative tools.

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

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

Annotations are all false, so the description carries full behavioral disclosure. It adds key behavioral traits: rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and asynchronous processing ('The team reads digests daily'). However, it doesn't explicitly state what the tool returns (though no output schema exists), leaving a minor gap about response/confirmation behavior.

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

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

The description is a single, well-structured paragraph with a clear opening statement, followed by usage scenarios, content guidance, and practical constraints. Every sentence serves a purpose—no fluff or repetition. It is dense but readable, and key facts (rate limit, quota) are 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?

For a simple feedback tool with no output schema, the description covers purpose, use cases, message formatting, rate limit, and cost. It even notes that the team reads digests daily, giving the agent an expectation of delayed impact. Minor omission: it doesn't state explicitly that the tool sends data to human reviewers or confirm receipt, but this is largely implied and not critical for a feedback submission tool.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. The description adds value beyond the schema by linking the 'type' enum to real-world situations ('bug = something broke or returned wrong data') and by providing content guidance for the 'message' field ('don't paste the end-user's prompt'). This enriches parameter understanding without redundancy.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names specific categories (bug, feature, data_gap, praise) and distinguishes itself from sibling tools like ask_pipeworx by focusing on feedback submission rather than asking questions. The verb+resource structure is explicit and actionable.

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 the tool: '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 clear content guidance, such as 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which tells the agent how to phrase feedback appropriately.

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 and non-destructive behavior. The description adds meaningful context beyond that: it reveals the data source (CF analytics-engine), confirms no PII, specifies the output shape (pack, tool, count), and explains caching (5min-1h). This is valuable transparency not derivable from 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 efficiently organized: the core function in the first sentence, a bulleted list of use cases, and two concise sentences about data provenance and caching. No redundancy with schema fields, and every sentence contributes unique 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?

As a simple one-parameter tool with no output schema, the description sufficiently covers the return contents (top tools, top packs, total call volume, and packet structure). It lacks an example but is complete enough for effective selection and invocation. Minor gap: no explicit statement about response format (e.g., JSON structure), but the description gives a clear mental model.

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 covers the window parameter with a description that already explains the tradeoff between short and long windows. The tool description merely restates the windows without adding new semantic detail, so it meets the baseline 3 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 opens with a specific, informative question ('What other AI agents are calling on Pipeworx right now?') and clearly states the output ('top tools, top packs, and total call volume'). This distinguishes it from sibling tools like discover_tools or ask_pipeworx by clarifying it provides aggregated usage trends, not individual discovery or Q&A.

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 'Useful for' section explicitly lists three concrete use cases (hot data sources, canonical tool confirmation, use-case alignment). This provides clear context but does not name alternative tools or explicitly state when not to use this tool, so it falls slightly short of full exclusionary guidance.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations by disclosing specific behaviors: the Jaccard similarity threshold of ≥0.30, the placeholder filter dropping will-person-X slugs, the 20% placeholder fraction rule, and the fill check against live CLOB depth with the warning that realizable_edge_pp ≤ 0 means 'do not trade it'. These are essential behavioral traits not present in annotations.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded key info. Every sentence adds unique value for a tool of this complexity, though it could be tightened slightly without losing critical 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 has 2 optional parameters, no output schema, and is a complex arbitrage scanner. The description fully compensates by outlining response fields (opportunities[], partition_check), filters, and edge-case handling (thin_legs, null arb signal). It also references the sibling tool for custom sizing, making it complete for an agent to select 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?

Although the input schema already provides 100% description coverage for both parameters, the tool description adds substantially more meaning: it explains what happens under the hood for both event and topic modes, gives concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), and describes the semantic anchor and partition filter that affect results. This is far beyond what the schema-only descriptions provide.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes between event and topic modes, and the level of detail about each mode differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly states when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It also notes that cross-event mode catches patterns single-event misses, and explicitly references polymarket_fill_risk for custom sizing. This provides clear context and 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?

Beyond the annotations (readOnly, idempotent), the description discloses substantial behavior: caching at KV level ('Cached 1h at the KV level keyed on all knobs'), diagnostics for empty segments, model-specific caveats (unreliable Fed signal, placeholder-slug filters, per-sport alpha), and slippage handling. This provides far more transparency than 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 long but well-structured with sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and front-loaded with the core purpose. Every sentence carries unique information; while verbose, it is appropriately sized for the tool's complexity.

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

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

No output schema is provided, but the description thoroughly explains the response top-level (by_segment, fed_candidates, _diagnostics), model families, filter behavior, and knob effects. It also covers edge cases like placeholder filtering and time-based staleness, making it complete 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% with detailed parameter descriptions, so the baseline is 3. The description adds value by grouping parameters as 'TRADEABLE-EDGE KNOBS' and explaining subtle interactions (e.g., min_partition_leg_kelly applies to per-leg Kelly because parent-level is 0 by design). This elevates it above 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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' – a specific verb, resource, and unique value proposition. It also states 'Built for "what should I bet on today"', which clearly distinguishes it from general market scanners and sibling tools.

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

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

The 'Built for' phrase provides a clear intended use case, and the description later explains when certain segments are applicable (e.g., Fed bets excluded from ranking). However, it does not explicitly name alternative tools to use instead or list when-not-to-use conditions, so it stops short of a 5.

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

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

Annotations already declare read-only and idempotent, but the description goes far beyond that. It discloses data freshness behavior (snapshots written on cache-miss causing gaps), the 60-day TTL bound, the fact that decay is computed from daily closes rather than intraday, and the exact semantics of response fields like first_seen, trend, and decay_pp_per_day. This is rich behavioral context that helps the agent set expectations.

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 every sentence is substantive. It is cleanly structured with 'Args:', 'RESPONSE:', and 'LIMITS:' sections, making it easy to scan. The opening sentence immediately conveys the core value proposition. No filler or redundant restatement of the tool name or annotations.

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 exhaustively: tracked[], expired[], and snapshot_dates[] are all defined with their inner fields and semantics. It also covers edge cases (gaps, age limits, signed edge values). This is a model of completeness for a telemetry 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 covers both parameters completely (100% coverage), so the baseline is 3. The description adds meaning beyond the schema by defining 'window' as a 'snapshot family' and explaining that snapshot dates correspond to days with actual data. It also reiterates defaults and clamps in a way that reinforces the schema. This extra context nudges the score to 4.

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

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

The description opens with a specific, resource-bound statement: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers a distinct question ('how long has this edge existed and is it shrinking?') and differentiates from sibling tools like polymarket_edges by focusing on persistence and decay rather than edge computation. It also explicitly frames the output (tracked/expired) which further clarifies purpose.

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

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

The description provides clear usage context by stating the exact question it answers and contrasting fresh vs. old wide edges. It also explains the data source (daily snapshots) and limitations (TTL, cache-miss gaps). However, it does not explicitly name sibling tools to use instead, nor does it provide when-not-to-use guidance, so it stops short of a 5.

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

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

Although annotations already declare readOnlyHint and idempotentHint, the description adds substantial behavioral context: detailed return fields, default sizes and clamping (1,000 USD default, 10–1,000,000 clamp), per-leg fill details, thin_legs[], and the risk of forced directional exposure from partial basket fills. This goes well beyond the annotations and fully discloses edge cases and failure modes.

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

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

Though lengthy, the description is densely packed and every sentence adds value. It is structured with capitalized section markers (SINGLE-MARKET, BASKET) and front-loaded with the core purpose. The length is justified by the complexity of the tool, and there is 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 complexity—two modes, multiple return fields, and integration with sibling tools—the description is complete. It explains inputs, outputs, defaults, constraints (size clamp), risk scenarios, and recommended usage context. Since there is no output schema, the description fully compensates by enumerating all returned metrics and verdict values.

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?

While the input schema already covers all parameters at 100%, the description enriches their meaning significantly. It clarifies how size_usd is interpreted in single-market vs basket mode ('max spend on buys, target proceeds on sells' vs 'settlement notional — shares per leg, each paying $1'), explains the default behavior of side in basket mode, and distinguishes market vs event parameters with concrete usage context. This is far beyond 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 opens with a specific, action-oriented purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes its function from sibling tools by naming polymarket_arbitrage and polymarket_edges, and it fully explains the two modes (single-market and basket), leaving no ambiguity about what the tool does.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why this tool is the correct choice over simply trusting theoretical edges, citing real-world failure modes like thin books and partial fills, which constitute clear exclusions and alternative contexts.

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

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

Annotations already indicate a safe read-only, idempotent operation. The description adds substantial behavioral context beyond this: it details compatibility_warning scenarios (matched_pairs:0 with skipped_cross_type>0 vs skipped_cross_type:0), temporal_alignment semantics, and skipped_cross_type/subtype counters. It also discloses that most pre-mapped topics are not tradeable, which is a critical behavioral trait not inferable from annotations.

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

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

The description is long but well-structured, using labeled sections like 'TWO MODES,' 'RESPONSE,' and 'SAFETY FIELDS.' Every sentence provides substantive detail, such as the exact shortcut list and the meaning of skipped_cross_subtype. While compact would be an overstatement, the density of useful information 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?

Given no output schema, the description thoroughly covers return values: leg-by-leg prices, matched spread, compatibility_warning conditions, temporal_alignment, and skip counters. It also explains failure modes and edge cases, making the tool self-contained for an agent. The complexity of cross-venue comparison is fully 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?

The input schema already provides 100% coverage with descriptions for all three parameters. The description adds meaning by explaining how the parameters interact: topic auto-fetches pre-mapped events, while kalshi_event_ticker and polymarket_event_slug override the mapped sides. It also enumerates the shortcut values, which reinforces the schema's enum-like list without being purely redundant.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly distinguishes it from siblings like polymarket_arbitrage and polymarket_edges by emphasizing cross-venue comparison. It also explains the two operational modes, making the tool's purpose unambiguous.

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

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

The description provides explicit usage guidance: it explains the two modes (topic shortcuts vs explicit tickers) and when each is appropriate. It also warns that 'most pre-mapped topics return compatibility_warning today' and 'pre-mapped ≠ tradeable,' which tells users when not to rely on it. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage, so it stops short of a full when/not-alternatives breakdown.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds valuable behavioral context about scoping (anonymous IP, BYO key hash, account ID) and the dual-mode behavior (omit key to list all keys), going beyond the annotations.

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

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

The description is three sentences, front-loaded with the core action, and each sentence earns its place: action, use case, and scoping/alternatives. No redundancy or fluff.

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

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

For a simple read-only tool with one optional parameter and strong annotations, the description covers purpose, usage context, scoping, and related tools. It does not need to explain return format since there is no output schema and behavior is straightforward.

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 describes the single 'key' parameter with 100% coverage ('Memory key to retrieve (omit to list all keys)'). The description reinforces this but adds no substantially new parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves a value previously saved via remember or lists all saved keys, with concrete examples (ticker, address, research notes). It also distinguishes itself from sibling tools by explicitly referencing remember and forget.

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

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

The description gives explicit usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also says 'Pair with remember to save, forget to delete,' naming alternatives and when to use each.

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 explicitly discloses a state-changing behavior via mark_read:true, which flags events as read and affects future calls. However, annotations declare readOnlyHint=true, which normally means the tool does not modify state. This is an annotation contradiction, so the transparency score drops to 1 per the rubric.

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

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

Three sentences, each earning its place: the first states what the tool returns, the second covers filtering and mark_read, and the third addresses polling and an alternative access route. Concise and 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?

Even without an output schema, the description covers return fields (source, citation_uri, raw payload), parameter semantics, polling suitability, and an external endpoint. This is complete enough for an agent to 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?

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving a concrete type example ('sec_8k'), clarifying since as an ISO timestamp filter, and explaining the mark_read side effect on future calls.

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

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

The description uses a specific verb ('Pull') and names the exact resource ('fired events from your subscription feed'). It clearly distinguishes this tool from siblings like list_subscriptions by describing returned alert content and persistence 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?

The description gives clear context for when to use this tool (retrieve recent alerts, poll, filter) and even offers an alternative HTTP endpoint for scripts/dashboards. It lacks explicit 'use X instead' guidance for sibling tools, but the context is strong enough.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses rich behavioral details: source fan-out (SEC EDGAR, GDELT→GNews fallback), rate-limit fallback logic, USPTO soft-fail due to PatentsView sunset, and return structure (changes[], total_changes, citation URIs). No contradictions with annotations.

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

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

The description is dense but every sentence adds value, from user-facing examples to source details to output summary. It is well-structured, front-loaded with the query patterns the tool answers, and avoids 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?

The description fully covers the tool's complexity: multiple data sources, fallback behavior, date parsing, output shape, and alternative tool link. Since there is no output schema, the description adequately explains return values and identifiers.

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

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

Schema already covers 100% of parameters, but the description adds extra semantics: it explains `since` accepts ISO or relative shorthand with examples, recommends typical values, and clarifies `value` can be ticker or CIK. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's function with specific verbs and resources: it provides a change feed for a company over a time window, with examples ('What's new with X'). It distinguishes from the sibling entity_profile tool by contrasting dynamic changes with static profiles.

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

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

Explicit guidance is given: mentions typical use ('Use 30d or 1m for typical monitoring') and names an alternative ('Use entity_profile instead when you want the static profile'). This clearly signals when to use this tool vs alternatives.

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

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

Annotations already cover read-only (false), idempotent (true), destructive (false). The description adds valuable context beyond annotations: scoping by identifier, persistence differences between authenticated (persistent) and anonymous (24 hours) sessions, and that data spans conversations/sessions. It does not contradict annotations.

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

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

Three concise sentences, each serving a distinct purpose: purpose, usage context, and operational details. No filler or redundant content. Highly efficient and 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 simple two-parameter tool with no output schema, the description covers all critical aspects: what it does, when to use, storage lifetime, scoping, and relationship to sibling tools. No meaningful gaps for the agent to misuse it.

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

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

Schema description coverage is 100%, with both key and value already explained via examples. The description adds minimal extra semantic value by reinforcing that these are 'key-value pairs' and giving conceptual examples of keys, but this mostly overlaps with schema. Baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Save') and clearly names the resource ('data the agent will need to reuse later') and mechanism ('key-value pair'). It explicitly distinguishes from sibling tools by naming recall and forget, making the purpose unambiguous.

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

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

Provides explicit when to use ('Use when you discover something worth carrying forward') with concrete examples. It also states what not to use it for indirectly via pairing: 'Pair with recall to retrieve later, forget to delete.' This directly guides tool selection relative to 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?

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds significant behavioral context beyond those hints: it mentions that each call cascades through several lookup endpoints internally, returns specific citation URIs, and auto-disambiguates inputs. This gives the agent a clear model of what happens inside the tool without contradicting any annotations.

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

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

The description is moderately long but every sentence adds value. It is front-loaded with natural language examples that quickly orient the agent, then provides structured details on supported types, returns, and internal behavior. The structure is logical and avoids fluff, making it efficient despite its length.

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

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

Given the tool's complexity and no output schema, the description is fully complete. It explains the purpose, input variants, output details per type, and internal cascading behavior. There are no missing pieces the agent would need to know 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?

Although the schema already covers both parameters with detailed descriptions, the tool description adds substantial semantic meaning. For the 'company' type, it clarifies that the value can be a ticker, CIK, or company name and that auto-disambiguation occurs. For 'drug', it specifies that brand or generic names are accepted and details the return fields (RxCUI, ingredient, brand). This enriches the parameter understanding 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 identifies the tool's purpose: resolving user-spoken names to canonical identifiers. It uses a specific verb ('resolve') and resource ('user-spoken NAME to the canonical/official identifier'), and distinguishes itself from sibling tools like compare_entities or entity_profile by focusing on the lookup of IDs that other tools require. The examples of natural language queries make the purpose instantly clear.

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

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

The description provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It details when to use the tool for company or drug lookups and explains what inputs are accepted for each type. It also notes that the tool replaces 2-3 manual lookups, giving a clear sense of when it is the right choice. No alternative tools are named, but the context and examples make the usage scenario unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds meaningful context: it probes each entity using ai_visibility_check, ranks results, and returns a ranked list with score/confidence/signal density. This goes beyond structured 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?

Two sentence description, front-loaded with core purpose. Every clause adds value—how it works, use case, and return format—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?

For a tool with 4 parameters, important behavioral traits, and no output schema, the description covers purpose, use case, probing mechanism, ranking logic, and return structure. It lacks only minor details like entity count limits, but these are already present in the schema, so the description 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 each parameter fully described (e.g., entities explains first-entry-as-subject). The description echoes the entities semantics ('your brand + N competitors') but adds no new detail 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 clearly identifies the action ('Compare AI visibility across multiple entities side-by-side') and explains the mechanism (probes each entity with ai_visibility_check, ranks by score). It distinguishes from siblings by focusing on competitive multi-entity comparison, directly referencing an underlying single-entity 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?

Provides an explicit use case ('Useful for competitive AI-marketing audits') with a relatable example question. Though it doesn't explicitly mention when not to use it, referencing ai_visibility_check implies that this tool is for multi-entity comparison, while the sibling handles single-entity checks.

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 partial failure behavior (bundlephobia first measurement can take 5-30s, sources_failed lists timeouts, rest still returns), plus it enumerates the exact return fields. This adds substantial operational context.

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

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

Though dense, the description is well-structured: purpose first, then usage triggers, output summary, ecosystem scope, and failure handling. Every sentence earns its place with no redundant padding.

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

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

Despite lacking an output schema, the description lists all return components (summary block fields, advisory details, links, alternative versions) and covers edge cases like scoped packages and timeouts. It is 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 input schema already provides complete descriptions for both parameters (package name and version, with default behavior for version). The description adds no new parameter-level detail beyond what the schema states, so the baseline of 3 applies.

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

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

The description clearly states it is a composite 'should I add this npm package' check that fans out to deps.dev and bundlephobia. This specific verb+resource combination with the multi-source aggregation distinguishes it from any sibling tools.

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

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

Explicitly states when to use: whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also provides a clear exclusion: NPM only in v1, other ecosystems should use deps.dev:version directly.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, but the description adds further behavioral details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K char cap with truncation flagging. This goes well beyond the annotations.

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

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

The description is three sentences, front-loaded with the core purpose, then usage context, then technical trade-offs. Every sentence contributes distinct information: what it does, when to use it, and how it behaves. No filler or redundancy.

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

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

Without an output schema, the description fully explains what the agent receives (top-N passages with offsets and similarity scores). It also covers input constraints (200K char cap, truncation flag), technical mechanism, and pairing with ask_pipeworx_grounded. This is sufficient for a tool with this complexity.

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

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

Schema covers all 3 parameters at 100%, so baseline is 3. The description adds illustrative examples (e.g., SEC 10-K body, natural-language query) and mentions 'top-N passages' but does not significantly add meaning beyond the schema's own parameter descriptions. It earns the baseline, not more.

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 'Semantic search INSIDE a fetched record' with a specific verb and resource. It differentiates from siblings by emphasizing internal search over a previously fetched text, and the 'too big to cram into the prompt' context clarifies its unique role.

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 'Use when the record is too big to cram into the prompt' instruction. It also names the alternative ask_pipeworx_grounded and explains the pairing pattern: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear when and how to use it versus alternatives.

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

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

Annotations already indicate readOnly=false, idempotentHint=true, and destructive=false. The description adds valuable context beyond these: the OAuth requirement, return of a subscription id, always-on feed behavior, SMS verification and daily cap, and webhook auto-disablement after consecutive failures. This significantly enriches the safety and operational profile without contradicting annotations.

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

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

The description is dense but well-structured, front-loading the core purpose and then methodically covering authentication, supported types, and delivery channels. It is longer than typical but every sentence contributes essential information, with 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 tool's complexity (nested objects, multiple types, no output schema), the description is remarkably complete: it states the return value, auth prerequisites, all subscription types, and delivery methods. The only minor gap is that webhook delivery details are not in the main description, but they appear in the delivery schema, so overall coverage is strong.

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

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

The input schema already provides 100% coverage with descriptions for all parameters. The description goes further by giving concrete examples for each type (e.g., items:['5.02'] = officer change, topic:'fed') and clarifying constraints like the phone verification and 10/day cap, which adds meaningful interpretation beyond the schema.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It also mentions the return value (new subscription id) and distinguishes it from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides strong context about when to use it, such as requiring an OAuth account and listing supported subscription types. However, it does not explicitly contrast this tool with alternatives like polling via recent_alerts or performing one-time queries, so guidance on when not to use it is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so safety is covered. The description adds valuable context beyond annotations: the return format (category-bucketed example questions with exact tool + argument shape), the behavior of calling with no arguments vs. with a topic, and that it draws from a live catalog. This is useful but not exhaustive (e.g., no mention of response size or performance), which is acceptable for a read-only onboarding tool.

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

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

The description is longer than typical but the first sentence immediately conveys the purpose with a list of natural-language queries. Subsequent sentences explain the return structure, parameters, and usage context. It is information-dense with no filler, though slightly verbose; every element serves a purpose for an onboarding tool.

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

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

The tool has only one optional parameter, no output schema, and rich annotations. The description fully covers what the tool returns, how to invoke it (with/without topic), and when to use it, including relation to meta-tools. This is complete for the tool's complexity and context, and the lack of an output schema is compensated by the explicit description of the return structure.

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

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

The schema describes the single optional `topic` parameter with the same focus areas and guidance as the description (100% schema coverage). The description reiterates this and adds example values like 'finance', 'pharma', 'betting', but does not add new meaning beyond the schema. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape to answer them. It uses specific verbs ('returns', 'learn how to call') and differentiates from siblings like ask_pipeworx and discover_tools by positioning itself as a meta-level guide rather than a question-answering or tool-search tool.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.)'. It also provides concrete example queries ('what can I ask Pipeworx?', 'show me examples') and explains optional topic filtering, giving clear when-to-use and how-to-use guidance.

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

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

The description goes beyond annotations by revealing behavioral traits: ownership enforcement, soft-deactivation instead of hard delete, and data retention for historical events. This is valuable context that aligns with the idempotent and non-destructive annotations while adding concrete detail.

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: the first states the action, the second explains the key side effects. It is front-loaded with the primary purpose and contains no redundant or filler 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 single-parameter tool with strong annotations and schema coverage, the description fully covers the essential context: what the tool does, key constraints (ownership), and the non-destructive behavior. No output schema exists, but one is unnecessary for this straightforward operation.

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

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

The input schema already provides 100% coverage for the single 'id' parameter, including its origin from subscribe. The description restates 'by id' but doesn't add new parameter-specific meaning beyond what the schema already documents, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Cancel') with a clear resource ('a subscription by id'), and the title 'Unsubscribe from Alerts' reinforces the purpose. It clearly distinguishes from siblings like subscribe and list_subscriptions.

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

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

The description provides important usage context: ownership is enforced, so you can only cancel your own subscriptions, and the row is deactivated rather than deleted, meaning historical events remain accessible via recent_alerts. It doesn't explicitly state when not to use it or name alternative tools, but the context is sufficient for correct selection.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial context beyond this: the dual-path routing (SEC EDGAR/XBRL vs grounded pipeline), percent-delta math, the specific verdict set, and the inclusion of pipeworx:// citations. It does not contradict annotations and discloses the fact that external live sources may be consulted.

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 typical but every sentence contributes value: example user phrasings help intent recognition, the core purpose is stated upfront, and the two-path behavior and output format are detailed. A minor redundancy is the list of phrasings, but it remains informative and well-organized.

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

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

Despite the lack of an output schema, the description fully specifies return values (verdict types, actual value with citation, reasoning), covers both invocation conditions and parameter semantics, and discloses the internal process. It is sufficiently complete for an agent to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100% for both parameters, giving a baseline of 3. The description enriches this by explaining that tolerance_pct overrides the wording-implied tolerance, suggests use cases like hallucination detection, and clarifies how the claim drives the pipeline (structured vs grounded). This goes beyond the schema's literal definitions.

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

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

The description clearly identifies the tool as natural-language claim verification against authoritative sources, with a specific verb ('verify', 'fact check', 'check') and resource ('claim'). It distinguishes from siblings by outlining its unique verdict-based pipeline and explicitly stating it replaces 4–6 sequential calls, making it distinct from research or retrieval tools.

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

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

The description states 'Use whenever the agent needs to check whether something a user said is factually correct', providing a clear invocation criterion. It further specifies behavior for company-financial claims vs other claims, but does not explicitly name alternatives or state exclusions, so it falls short of a perfect 5.

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