Rick And Morty

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: default model is free, probing Anthropic requires a user-provided API key and direct payment, and it returns per-model plus combined views. This goes beyond the structured annotations.

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

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

Three sentences, front-loaded with the core function, then model provisioning, then use cases. Every sentence adds information without redundancy.

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

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

With no output schema, the description explicitly describes the return shape (per-model {score, confidence, signals, raw_response} + combined view). It also covers model selection, cost, and use cases, making it sufficient 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?

All four parameters are fully described in the schema (100% coverage), so baseline is 3. The description reinforces the default model behavior and the _apiKey cost implication, but does not add significant new parameter-level 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 uses a specific verb ('probe') and resource ('LLMs for what they know about a business/brand/product/topic') and clearly states the output (visibility score 0-100). It distinguishes itself from siblings like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on multi-model visibility scoring.

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

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

The description lists explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the Anthropic model (BYO key). It does not mention alternatives by name or state when not to use the tool, so it stops short of full exclusion guidance.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond these: it routes to 5,366 tools, fills arguments, returns structured answers with pipeworx:// citation URIs, works on every tier, and makes one fast call. No contradiction with annotations.

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

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

The description is long but every sentence adds value: the opening command, the domain list, the routing behavior, the trigger phrases, examples, positioning, and escalation paths. It is well-structured with the most important guidance up front and 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?

For a tool with 6 parameters and no output schema, the description fully covers what the tool does, how to invoke it, what to expect in return (structured data with citations), and when to choose alternatives. It addresses the tool's role in the broader tool ecosystem and handles edge cases like breaking news.

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 covers all parameters with full descriptions, including aliases for 'question'. The description supplements this by giving concrete example queries and clarifying that the tool accepts natural language questions, which helps the agent formulate the required parameter. However, it doesn't add much per-parameter semantics beyond examples.

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

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

The description clearly states the tool's function: it routes questions to the appropriate source among thousands and returns structured answers with citations. It distinguishes itself from siblings by explicitly naming alternatives like ask_pipeworx_grounded and deep_research, and positions itself as the default entry point.

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: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE'. It also gives clear when-not-to-use instructions by pointing to ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad questions, plus notes about breaking news.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context about the experimental nature, the fact that no candidate is currently active, that it is a full working router (not a fallback), and that results are compared to decide merges. This goes beyond the annotations without contradicting them.

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

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

The description is four sentences long, but each sentence earns its place by covering definition, current state, usage instruction, and clarification about not being a fallback. It is front-loaded with the core purpose and remains tightly structured without redundancy.

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

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

For a complex router tool with thousands of underlying tools, the description is remarkably complete. It explains what the tool is, its relationship to the stable version, its current behavioral equivalence, its experimental purpose, and the response shape. No output schema exists, but referencing the same response shape as ask_pipeworx provides sufficient completeness for invocation.

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

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

Schema description coverage is 100%, with all six parameters clearly documented as aliases for 'question'. The description mentions 'same arguments' but does not add further parameter-level meaning beyond what the schema already provides, so the 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 this is the beta version of ask_pipeworx, an identical universal router with the same 5,366 tools, arguments, and response shape. It clearly differentiates from the stable ask_pipeworx by noting experimental routing improvements and directly naming ask_pipeworx in the sibling context.

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

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

It provides explicit usage direction: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes the current state (no active candidate, matches stable exactly), but does not explicitly state when not to use it or mention alternative tools beyond the comparison to the stable router.

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 discloses extensive behavioral details beyond the annotations, including exact success/refusal return structures, refusal reason enums, the extra LLM call cost, and the guarantee not to invent facts. This is fully consistent with the readOnlyHint, openWorldHint, and idempotentHint annotations, with 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 dense but well-organized, starting with the core value proposition and then covering mechanics, output formats, use cases, and cost trade-offs. It is slightly long, but every sentence contributes to the agent's decision-making, so the minor verbosity is 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?

Despite having no output schema, the description fully specifies success and refusal response shapes, when to use the tool, and how it compares to the sibling ask_pipeworx. It provides all necessary context 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?

The input schema already provides 100% coverage, documenting the 'question' parameter and all five aliases with descriptions. The tool description does not add new parameter-level detail beyond the general context of natural language questions, 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 is a hallucination-resistant answer mode that routes to relevant tools, fetches data, and extracts answers strictly from tool results. It explicitly differentiates itself from the sibling ask_pipeworx by emphasizing grounded evidence and refusal 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?

It explicitly tells the agent when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'), naming the alternative directly. This leaves no ambiguity about 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?

The description goes far beyond the readOnlyHint/idempotentHint annotations, documenting resolver match confidence, low-confidence short-circuits, market_closed_or_inactive blocking routes, illiquid wide-spread warnings, cancellation rule risks, and fallback behavior for news. This is rich, actionable behavioral disclosure that directly prevents misuse.

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 highly structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, SAFETY, RESOLUTION-RULE RISK). Every section adds critical operational detail. It is not concise in length, but it is efficiently organized and front-loaded with purpose and usage. Slight deduction for verbosity.

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 compensates by enumerating response fields (result.market, result.analysis, result.evidence), edge-case statuses, resolver behavior, and cancellation-rule risk. It is exceptionally complete for a complex, multi-source research tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining how the 'market' parameter accepts slug, URL, or question text (also in schema), but more importantly clarifies fan-out depth and include_raw tradeoffs via examples and size expectations. This is a modest improvement over the structured data, earning a 4.

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

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

The description opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call'—a specific verb, resource, and scope. It further distinguishes itself from sibling tools by stating explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). No ambiguity.

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 clearly states when to use the tool with examples of user intents. It doesn't explicitly say when NOT to use it or name alternative sibling tools (like polymarket_arbitrage), but the context is strong enough that an agent can infer appropriate use. Missing explicit exclusions keeps this at 4.

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 behavior. The description adds substantial context: pulls LATEST 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. 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 dense but front-loaded with trigger phrases and every sentence adds value—data sources, fiscal-year handling, sorting behavior, and output format. It is appropriately sized for the tool's complexity and contains no filler.

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

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

With no output schema, the description adequately explains return value (paired data + citation URIs) and result ordering. It also covers constraints like 2–5 entities and edge cases like off-calendar fiscal years, making it complete for a comparison tool.

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

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

Schema coverage is 100%, but the description adds meaningful semantics: type='company' specifies financial fields (revenue, net income, cash, long-term debt) and type='drug' specifies FAERS and FDA/trial counts. It also clarifies values as 2–5 tickers or drug names, with examples like ["AAPL","MSFT"].

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 a specific verb+resource: side-by-side comparison of 2–5 companies or drugs in one call. It distinguishes from siblings by explicitly recommending against sequential single-pack lookups and providing trigger phrases like 'which is bigger' and 'head to head'.

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

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

It provides explicit when-to-use guidance with trigger phrase examples (e.g., 'X vs Y', 'rank these companies') and an 'ALWAYS PREFER' statement over sequential single-pack lookups, which differentiates it from tools like entity_profile. The description clearly conveys the intended use case for multi-entity comparisons.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds far more: account requirements, parallel decomposition across 5,366 tools, gaps[] never inventing, contradiction[] scanning, hop/citation_uri fields, semantic excerpting, and expected latency. No contradiction with annotations.

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

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

The description is long, but front-loaded with the critical account caveat and alternative tool. Each paragraph adds distinct value (mode comparison, return format, excerpting, timing). Minor repetition like 'never invented' and 'ONE call' could be trimmed, but the complexity of the tool 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?

With no output schema, the description fully specifies return values: findings packet with evidence/confidence/source/fetched_at/citation, gaps[], contradictions[], and hop field. It also covers edge cases (empty gaps for non-catalog topics), auth depth tiers, and latency. Exceptionally complete for a tool with this many modes and behaviors.

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 at 100%, but the description enriches them: depth is expanded with facet counts (quick=3, standard=5, thorough=8) and hop/contradiction behaviors, while question is clarified as accepting broad/multi-part natural language. This goes well beyond the schema text.

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: 'Grounded multi-source research across Pipeworx's 1396 STRUCTURED data sources'. It clearly differentiates from siblings by stating 'this is NOT open-web search' and explicitly contrasts with ask_pipeworx for single lookups and current-news topics.

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 versus alternatives: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also states it is 'Best for broad/multi-part questions over structured data'.

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

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

Beyond the read-only/idempotent annotations, the description adds concrete behavioral details: returns 'top-N most relevant tools with names, descriptions, and full input schemas', and notes results are 'ready to call directly, no second schema lookup needed.' This explains output format and saves the agent a step, adding real value beyond annotations.

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

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

The description is longer than a simple two-liner but each sentence earns its place: purpose, usage, output format, and strategic guidance. The domain list is somewhat verbose but provides immediate context for the agent, so it's not wasted.

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

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

For a discovery tool with no output schema, the description fully explains the return value (top-N tools with schemas and examples) and the workflow benefit. It covers what the tool does, when to use it, and what to expect, making it complete without needing a formal output schema.

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

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

Schema coverage is 100% and every parameter (including aliases) is already documented in the input schema. The description only vaguely references 'top-N' without adding any new parameter semantics, so the schema carries the burden and 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 opens with 'Find tools by describing the data or task', a specific verb+resource combination that clearly states the tool's function. It also distinguishes itself from siblings by positioning itself as a first-stop discovery tool ('Call this FIRST') rather than a direct-answer 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?

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and provides a strategic directive: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear context without needing to name alternatives.

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

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

Beyond the read-only/idempotent annotations, the description discloses concrete behaviors: fans out across multiple sources, returns up to 5 filings with specific URIs, sorts fundamentals by period_end DESC, soft-fails on the patents API sunset, and falls back from GDELT to GNews for news. This adds substantial operational context without contradicting 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 appropriately detailed and front-loaded with example prompts, followed by the fan-out behavior, return fields, and input requirements. It is slightly verbose—repeating schema examples (e.g., AAPL/CIK)—but every sentence conveys useful context and the structure is logical.

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

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

With no output schema, the description compensates by enumerating all return fields and caveats (patents soft-fail, news fallback, LEI source, name unsupported). It is complete enough for an agent to understand the tool's scope and output expectations, though the exact response shape and error handling are not specified.

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

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

The input schema already covers both parameters completely (type enum with only 'company', value documented as ticker or CIK with examples and a note about names not being supported). The description repeats these examples and constraints but does not add new parameter-level meaning, so it meets the baseline for 100% 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 explicitly states the tool produces a full cross-source profile of a US public company in one parallel call, enumerating the return fields (CIK, filings, fundamentals, patents, news, LEI) and citing example queries. It distinguishes itself from sibling tools like resolve_entity by noting that names are not supported and that it should be preferred over chaining single-source 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 context with example prompts ("Tell me about X", "research Acme") and an ALWAYS PREFER directive over chaining single-pack SEC/XBRL/news lookups for holistic views. It also gives a clear exclusion and fallback: "names not supported (use resolve_entity first if you only have a 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 destructiveHint=true and idempotentHint=true, so the safety profile is clear. The description adds the 'sensitive data' rationale but does not disclose additional behavioral details like irreversibility or side effects. There is no contradiction with annotations.

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

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

The description is two short sentences with the core action front-loaded and no unnecessary words. Every sentence earns its place.

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

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

For a simple one-parameter destructive operation with annotations covering safety, the description fully specifies purpose, usage, and related tools. An output schema is absent, but the return behavior is not critical for a delete 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?

Schema description coverage for the single 'key' parameter is 100% ('Memory key to delete'). The description only references 'by key' without adding meaning beyond the schema, so the baseline score 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 the verb 'delete' and the resource 'previously stored memory by key', making the tool's purpose unambiguous. It also distinguishes from siblings like remember and recall by emphasizing deletion.

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

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

The description explicitly lists conditions for use: when context is stale, task is done, or to clear sensitive data. It also names related tools (remember and recall) to pair with, providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining the tool fetches the page, extracts key metadata, and outputs a markdown blob, which is non-obvious behavior beyond the safe-read annotation.

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

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

The description is concise, well-structured, and front-loaded with the main purpose. Every sentence contributes value: the core functionality, the output format, and practical use cases. No unnecessary repetition 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 moderate complexity, rich annotations, and complete schema, the description covers all essential context. It explains the output format ('single text blob ready to drop at site-root/llms.txt') and provides concrete use cases, making it complete for an agent to decide invocation.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters (url and max_links). The description mentions 'any URL' and the output format but does not add meaningful parameter-specific semantics beyond what the schema already provides.

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

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

The description clearly states the tool's purpose with a specific verb+resource: 'Generate a production-ready llms.txt file for any URL.' It further explains the process (fetches, extracts, emits) and distinguishes it from sibling tools by focusing on llms.txt generation specifically.

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 ('Useful for:') that give clear context for when to use the tool. However, it does not explicitly mention alternatives or when not to use it, though sibling differentiation is implied by the unique purpose.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds useful behavioral context by enumerating the return fields (name, status, species, origin, location, episodes, image URL), which informs the agent about the tool's output without needing to inspect the schema.

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, information-dense sentence. It front-loads the action and resource, then lists the return fields. No filler words or redundant clauses.

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 read operation, the description is sufficient: it explains the input, the purpose, and the output fields. The existence of an output schema further reduces the need for the description to detail return formats. Minor gap: it does not mention error behavior for invalid IDs, but this is not critical for such 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?

The input schema has 100% coverage with a clear description for the 'id' parameter, including a valid range and an example. The tool description only repeats 'by numeric ID' without adding new semantic details, so the schema carries the full explanatory burden.

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 ('Get'), the specific resource ('a single Rick and Morty character'), and the access method ('by numeric ID'). It distinguishes from sibling tools like search_characters, get_episode, and get_location by targeting a single character with a known ID.

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

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

The description implies when to use this tool (when you have a numeric character ID) and the context is clear. It does not explicitly mention alternatives or exclusions, but the 'by numeric ID' phrasing effectively signals that it is not for searching or for episodes/locations.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds the expected return fields but does not disclose other behavioral traits such as error conditions or rate limits. This adds some value beyond annotations but not extensive.

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

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

The description is a single, focused sentence that front-loads the action and resource, followed by a concise list of return fields. No superfluous words, making it highly efficient.

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

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

With one simple parameter, comprehensive annotations, and an output schema, the description is complete for invocation. It even summarizes the return payload, covering all necessary context for an agent to select and 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?

The input schema has 100% description coverage for the single parameter 'id', with type and example provided. The description's mention of 'numeric ID' reinforces the schema but does not add new semantic meaning, 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 'Get' and clearly identifies the resource as a single Rick and Morty episode by numeric ID. It explicitly lists the return contents (title, code, air date, characters), which distinguishes it from sibling tools like get_character and get_location.

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 clearly states the tool returns a single episode by numeric ID, indicating when to use it (when you have a known ID). It does not explicitly mention alternatives like search_episodes, but the context is clear and not misleading.

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, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds that the tool returns a single location and lists return fields, which is modest extra context. It does not mention error behavior or rate limits, but given the simple read-only nature, this is acceptable.

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

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

The description is a single concise sentence, front-loaded with the verb and resource, and includes relevant return fields without any repetition of schema or annotation details. Every word earns its place.

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

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

For a straightforward read-only lookup with one parameter, supported by rich annotations and an output schema, the description is largely complete. It could mention not-found behavior, but this is a minor gap for such 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?

The input schema already fully documents the only parameter 'id' with an example (1 = Earth (C-137)). The description does not add parameter-specific info, but schema coverage is 100%, 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 specifies the operation ('Get a single Rick and Morty location/planet/dimension by ID') and differentiates the tool from siblings like get_character and get_episode. It also lists key return fields (name, type, dimension, residents), making the resource scope explicit.

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

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

The description conveys that this tool is for direct single-location lookup by ID, which implies usage context. It does not explicitly state when not to use it or name alternatives, but the presence of sibling search tools (search_characters, search_episodes) makes the distinction clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint false. The description adds value by specifying the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and scoping the result to the caller's active subscriptions, which goes beyond the annotation 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?

Two concise sentences that front-load the purpose, then list return fields, then state usage. Every sentence earns its place with no unnecessary verbosity.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers purpose, scope, return fields, and usage scenarios. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for the single parameter include_inactive, which already has a clear description. The tool description does not add any additional parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifies the return fields, and distinguishes its purpose from adding or canceling subscriptions by mentioning 'before adding more' and 'to find an id to cancel.' This is a specific verb+resource with scope.

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

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

The description provides clear context for when to use the tool: to review current monitoring before adding subscriptions or to find an id to cancel. It implies alternatives (subscribe/unsubscribe) without explicitly naming them, so it's close to explicit but lacks a direct 'use X instead' statement.

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

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

The annotations provide no positive hints (all false), so the description carries the burden. It discloses a rate limit ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and how feedback is processed ('The team reads digests daily and signal directly affects roadmap'). This adds useful behavioral context beyond the schema.

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 primary purpose, followed by usage scenarios and practical constraints. Every sentence earns its place; no fluff or redundancy.

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

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

Despite having no output schema and minimal annotations, the description fully covers what the tool is for, when to use it, how to format the message, rate limits, and cost. Nested context parameters are self-explanatory via the schema. For a feedback tool, this is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value by instructing users to 'Describe the issue in terms of Pipeworx tools/packs' and to avoid pasting the end-user's prompt, which refines how the `message` parameter should be used. It also clarifies the `type` categories by mapping them to concrete scenarios (bug, feature/data_gap, praise) even though the schema already lists them.

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, actionable purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly identifies the tool as a feedback channel and distinguishes it from all sibling tools, which focus on data retrieval, research, or subscriptions.

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

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

Explicitly states 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 a key exclusion: 'don't paste the end-user's prompt.' This is comprehensive usage guidance.

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

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

The description adds substantial behavioral detail beyond the annotations: it explains the data source ('derived from CF analytics-engine'), privacy guarantees ('no PII'), the data shape ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This is useful operational transparency that complements the readOnlyHint and idempotentHint annotations without contradicting them.

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

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

The description is three well-organized sentences: the first states the core function and output, the second lists use cases, and the third provides technical context. Every sentence earns its place, with no fluff or redundancy. The front-loading of the purpose makes it instantly scannable.

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

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

For a simple read-only aggregation tool with one optional parameter, the description is complete: it covers purpose, use cases, data characteristics, privacy, and caching. Since there is no output schema, the description's mention of the return contents (top tools, top packs, call volume) provides adequate 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?

While the schema already documents the 'window' parameter with an enum and description, the tool description reinforces its meaning and adds decision guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This extra semantic layer helps the agent choose an appropriate window value, going beyond the schema's 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 concrete statement of what the tool does: 'What other AI agents are calling on Pipeworx right now' and then specifies the exact outputs: 'top tools, top packs, and total call volume over a recent window.' This clearly distinguishes it from related sibling tools like ask_pipeworx (Q&A) or discover_tools (tool discovery) by focusing on aggregate usage trends.

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 three explicit, actionable use cases: discovering hot data sources, confirming a canonical tool choice, and checking alignment with other agents' needs. It gives clear context for when to use the tool, though it does not explicitly state when not to use it or name alternative tools, which prevents a perfect score.

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

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

Annotations already mark read-only/idempotent; the description goes much further, disclosing the 3pp threshold for partition deviations, the 0.30 Jaccard similarity anchor, the >20% placeholder filter returning null, and the CLOB-depth fill-check distinction between theoretical and realizable edge. Nothing contradicts the readOnlyHint.

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

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

The description is long but structured into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) with front-loaded main usage. Each sentence adds operational detail rather than filler; the length is justified by 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?

With no output schema, the description carries the responsibility for explaining return values, and it lists the key fields: opportunities[] with gap_pp, suggested_trade, reasoning, and partition_check fields including sum_yes_prices and placeholders_filtered. It also covers the null-arb case and custom sizing fallback, making it complete for the intended use cases.

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 documents both optional params at 100% coverage, the description enriches them with examples (fed-decision-may-2026), accepted URL formats, and behavior differences: event walks child markets and partition-checks, topic flattens related events for cross-event patterns. This goes well beyond the schema.

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

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

The description opens with a specific action ('Find arbitrage opportunities') and names the exact method (monotonicity violations + partition-sum checks). It clearly targets Polymarket and distinguishes three modes (trending_scan, event, topic), which also helps separate it from siblings like polymarket_edge_tracker.

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

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

It gives explicit when-to-use for each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. It even provides a cross-tool pointer, 'For custom sizing use polymarket_fill_risk', and warns not to trade when fill-check shows realizable edge ≤ 0.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description goes far beyond this by detailing output segmentation, model families, Kelly caps, slippage handling, caching behavior, and the 'edge may already be in the price' warning. It also explains why Fed signals are excluded and how diagnostics reveal why a segment might be empty. This provides comprehensive behavioral transparency.

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

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

The description is dense and long, but it is logically structured into numbered model families, response top-level, and knob explanations. Every sentence carries information—no filler. The length is justified given the tool's complexity and the absence of an output schema. Still, the wall-of-text format could be more scannable with headers or bullets, so it earns a 4 rather than 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 the 9 parameters, 100% schema coverage, and no output schema, the description covers all necessary context: response structure (by_segment), diagnostics for empty results, caching behavior, limitations (Fed signal reliability), and usage knobs. It is a complete picture for an agent to select and 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?

Although schema coverage is 100%, the description adds substantial semantic layer: it explains what each knob does in the context of edge discovery (e.g., min_partition_leg_kelly's special behavior for partition arbs, slippage_pp being subtracted net of slippage, tradeable-edge filters). It references concrete defaults and rationale, making parameter choices meaningful beyond their schema definitions.

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

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

The description opens with a specific action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly identifies the tool's purpose (discovering betting edges) and differentiates it from sibling tools like polymarket_arbitrage by emphasizing it surfaces Pipeworx data disagreements without paging hundreds of markets. The scope and intended use case ('what should I bet on today') are unambiguous.

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

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

The description states it is 'built for' a particular agent task and explains design decisions (e.g., excluding Fed bets due to unreliable data, grouping model families, diagnostics for empty segments). It provides clear context for when to use the tool, though it does not explicitly name alternative tools for excluded scenarios (e.g., when needing detailed per-market fills, polymarket_fill_risk might be more appropriate). Still, the guidance is strong enough to infer appropriate usage.

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

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

The description goes far beyond annotations by disclosing: response structure (tracked, expired, snapshot_dates), how snapshots are written (on cache-miss, gaps mean no scan), TTL limits (60-day), and decay calculation methodology (daily closes of edge_pp_net, not intraday). This rich behavioral detail is fully consistent with readOnlyHint, openWorldHint, and idempotentHint.

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 with clear sections (Args, RESPONSE, LIMITS) and front-loaded purpose. Every sentence carries meaningful information about behavior, response fields, and edge cases. No wasted words; the length is justified by the tool's complexity.

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

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

Given there is no output schema, the description thoroughly explains the response structure, including tracked opportunities, expired opportunities, and snapshot_dates with their semantics. It also covers operational limits (TTL, snapshot gaps) and calculation details, making the tool fully understandable without external documentation.

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

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

The input schema already provides complete descriptions for both parameters, including defaults and clamps, so the baseline is 3. The description adds minor context (e.g., days max 30, window family) but does not substantially enrich beyond schema. There is a slight inconsistency (description says max 30, schema says clamp 2-30) but not a contradiction.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the question 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling polymarket_edges by focusing on historical snapshots and decay, not current edges.

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

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

The description provides strong contextual guidance by framing when edge history matters ('a fresh wide edge and a 3-week-old wide edge are different trades'), implying this tool should be used for persistence/decay analysis. However, it does not explicitly name alternatives or state when not to use it, 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 read-only, open-world, idempotent, non-destructive, but the description adds a wealth of behavioral detail: it walks the order book ladder, returns fields like top_of_book, vwap_fill_price, slippage_pp, verdict, and per-leg fill detail; it also discloses forced_directional_risk and the dominant loss mode. No contradiction with annotations.

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

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

Although long, the description is exceptionally well structured: it starts with the core purpose, then clearly partitions SINGLE-MARKET vs BASKET with distinct returns, and ends with an explicit when-to-use callout. Every sentence adds value; no filler, no repetition.

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

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

Despite having no output schema, the description lists all major return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs[], max_clean_notional_usd, forced_directional_risk). It covers prerequisite state, mode selection, and failure modes. For a tool with this complexity, the description is remarkably 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?

The schema already covers all 4 parameters, but the description significantly enriches them: it explains the meaning of size_usd differently for single-market (spend/proceeds) versus basket (settlement notional), clarifies side meanings in both modes, and clarifies the requirement to pass either market or event. This is far more than restating schema strings.

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 precise verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from sibling tools like polymarket_arbitrage and polymarket_edges by positioning it as the risk/fill check on top of those signals, and it explicitly names the two modes (single-market and basket) with distinct behaviors.

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?

Usage guidance is explicit and actionable: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when to use market vs event mode, what side defaults apply, and why (partial basket fills convert an arb into unhedged directional risk). This goes far beyond generic advice.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses detailed behavioral traits: compatibility_warning triggers, temporal_alignment semantics, and skipped_cross_type counters. It even explains why non-equivalent bet shapes produce no arbitrage, which is far more transparent than typical tool descriptions.

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-organized, with clear sections for modes, response, safety fields, and limitations. Every sentence adds substantive value, and the front-loaded purpose sentence anchors the reader. For a tool of this complexity, the length is justified, though it could be slightly tightened.

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

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

With no output schema, the description thoroughly explains the response structure (leg-by-leg prices, top_spreads_pp) and the meaning of safety fields. It covers edge cases like temporal misalignment and unmatched pairs, making it nearly complete. However, it could benefit from a concrete example, so a 4 is warranted.

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

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

The input schema has 100% coverage, with each parameter described, including override behavior. The tool description adds context about auto-fetching in topic mode and the relationship between topic and explicit overrides, but this is marginal beyond the schema. Thus the 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 opening sentence 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' precisely states a specific verb+resource. It also distinguishes the tool from siblings like polymarket_arbitrage by emphasizing the cross-venue comparison and detailing two distinct operation modes.

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 clearly explains when to use topic mode ('10 pre-mapped macro shortcuts') versus explicit mode with overrides. It explicitly warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' guiding agents on trustworthiness. However, it does not name alternative 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?

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds meaningful context beyond annotations by explaining scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the fact that omitting the key lists all saved keys. No contradiction with annotations.

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

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

The description is two sentences, front-loads the primary action, and contains no fluff. Every clause contributes (behavior, usage, scope, pairing), making it 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 one-parameter read tool with strong annotations, the description covers what it does, when to use it, scoping, and sibling relationships. No output schema is needed since the action (retrieve/list) is clear. This is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% (the 'key' property documents 'omit to list all keys'). The description reinforces the omit behavior but adds little new semantic detail; the phrase 'previously saved via remember' provides some context about what the key refers to, but the schema already captures the core semantics. 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 states a specific action ('Retrieve a value previously saved via remember, or list all saved keys') and clearly distinguishes from sibling tools like remember (save) and forget (delete). The verb+resource is unambiguous and the dual behavior (get one or list all) is explicitly noted.

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

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

The description explains when to use this tool ('to look up context the agent stored earlier... without re-deriving it from scratch') and how it relates to alternatives ('Pair with remember to save, forget to delete'). It lacks an explicit 'when not to use' or a specific alternative for listing/searching all memories (e.g., if a different search tool exists), but the context is clear enough for most use cases.

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 contradicts the readOnlyHint annotation by introducing the mark_read:true parameter, which changes the persisted feed state and affects future calls ('the next call only shows newer ones'). This is a write side-effect, yet the annotation declares the tool as read-only. This is a clear annotation contradiction, so the score is 1 despite the otherwise useful disclosure of event payload details and polling 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 four sentences, front-loaded with the core purpose, then expanding to return format, filtering, mark_read, poll behavior, and an alternative access URL. Every sentence adds useful information without redundancy or fluff, making it lean 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?

Given the five optional parameters, no output schema, and rich annotations, the description does a good job covering the tool's behavior: it specifies what each returned event contains (source, citation_uri, payload), how filtering works, the mark_read side-effect, and polling suitability. The only minor gap is lack of error handling or pagination details, but these are not essential for typical use.

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

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

The schema already covers all five parameters with descriptions (100% coverage), giving a baseline of 3. The description adds extra meaning by providing a concrete filter example ('sec_8k'), explaining the ISO timestamp format for 'since', and detailing the behavioral consequence of mark_read (flagging events read so future calls ignore them). These clarifications go beyond the schema 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 states the tool's function: pulling fired events from the subscription feed and returning recent alerts. It specifies the resource ('subscription feed'), the action ('Pull fired events'), and distinguishes itself from sibling tools like 'recent_changes' by focusing on subscription alerts with details like source, citation_uri, and raw payload.

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: when to use the tool (to retrieve alerts), how to filter by type or since, and how mark_read affects subsequent calls. It also mentions polling and offers an alternative HTTP endpoint for scripts/dashboards, giving practical guidance. However, it does not explicitly state when not to use this tool versus other alert-related siblings (e.g., list_subscriptions).

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

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

The description discloses that the tool fans out to SEC EDGAR, GDELT with GNews fallback (GDELT preferred, GNews on rate-limit/5xx), and USPTO with a soft-fail due to PatentsView API sunset. This goes well beyond the readOnly/idempotent hints, informing the agent about potential incomplete data and source priorities.

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 contributes: user intents, data sources, fallback logic, date formats, return structure, and alternative tool. The initial example phrases front-load the tool's purpose efficiently, 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?

Despite lacking an output schema, the description specifies the return shape (changes[], total_changes, pipeworx:// URIs). It also covers source behavior and a clear alternative, making it complete for a complex multi-source tool.

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

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

The input schema already covers all parameters in detail, including examples for `since` and `value`. The description's mention of ISO/relative dates and ticker/CIK values largely repeats schema info, adding little new semantic meaning beyond tying the `since` window to the feed's time range.

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

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

The description clearly states it provides a 'change feed for a company' in a time window, with explicit examples like 'What's new with X'. It also distinguishes from the sibling entity_profile tool by naming it as an alternative for static profiles, making the tool's purpose unmistakable.

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

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

The description explicitly says 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window,' providing a clear alternative. The opening query examples also signal when this tool is appropriate (recent updates/news), though it does not discuss all 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 mark this as non-read-only, idempotent, and non-destructive. The description adds essential behavioral context beyond annotations: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours, and it is stored as a key-value pair. No contradiction with annotations.

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

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

Four sentences, front-loaded with the central purpose, followed by usage, storage characteristics, and companion tools. Every sentence provides distinct value, with no filler.

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

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

The description fully contextualizes a simple 2-parameter tool: what it stores, when to use it, persistence semantics, and relationship to recall/forget. With the schema covering parameter details and annotations covering safety traits, no important information is missing.

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

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

The input schema already documents both parameters with explanatory examples and 100% coverage. The description reinforces the key-value structure but doesn't add significant new semantic detail beyond what's already 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 opens with a clear verb phrase 'Save data the agent will need to reuse later' and specifies the resource (memory key-value store). It distinguishes from siblings by naming recall and forget as pairing tools, so there's no ambiguity about its 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?

It explicitly states when to use: 'Use when you discover something worth carrying forward...' and gives concrete examples. It also names alternatives/companions: 'Pair with recall to retrieve later, forget to delete,' making the usage context fully explicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it cascades through multiple lookup endpoints internally, auto-disambiguates company names, and returns citation URIs. It could mention rate limits or failure behavior, but the provided context is substantial and non-redundant.

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

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

The description is dense but well-organized: it starts with user-facing query examples, states the core purpose, gives explicit usage instruction, then breaks down supported types with clear bullet-like structure. Every sentence adds value, and the length is appropriate for a tool with two entity types and multiple output details. 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 parameter count (2), full schema coverage, strong annotations, and no output schema, the description is comprehensive. It explains what each type returns, what input formats are accepted, how disambiguation works, and even provides citation URI formats. The tool's complexity (multi-endpoint cascade) is acknowledged, and the description fully equips an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds meaning by explaining the impact of each parameter value: for 'type', it details what each enum returns (ticker+CIK+company_name for company, RxCUI+ingredient+brand for drug). For 'value', it enumerates accepted formats (ticker, CIK, name) and gives examples. This goes beyond the schema's terse 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 uses specific verbs ('resolve', 'look up', 'find') and clearly identifies the resource: converting user-spoken names to official identifiers (ticker, CIK, RxCUI) for both company and drug types. It distinguishes itself from sibling tools by stating it provides the identifiers that other tools require as input, and includes concrete examples and output details.

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

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

Explicit usage guidance is provided: 'Use FIRST whenever you have a name but need an ID.' It also differentiates from manual alternatives by noting that it replaces 2-3 manual lookups, and the supported types section clarifies when to use company vs. drug, including acceptable input formats and disambiguation behavior.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. No contradiction with annotations.

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

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

The description is concise (three sentences) with the main action front-loaded. Each sentence adds value: what it does, how it works, why it's useful, and what it returns. 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?

With no output schema, the description sufficiently explains the return format (ranked list with score, confidence, signal density per entity). It covers the use case and process. It does not mention limitations like entity count (handled in schema) or error handling, but these are not critical for selection.

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 each parameter (models, _apiKey, context, entities) already has clear descriptions. The description does not add additional parameter-level semantics beyond what the schema provides, 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 the tool compares AI visibility across multiple entities side-by-side, using a specific verb ('Compare') and resource ('AI visibility across entities'). It distinguishes itself from sibling tool ai_visibility_check (single entity) by focusing on multi-entity competitive comparison and ranking.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') with an illustrative question, making it clear when to use this tool. It implies it is the multi-entity counterpart to ai_visibility_check but does not explicitly state when not to use it or name alternatives beyond mentioning the underlying probe.

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 readOn, idempotent, non-destructive. The description adds valuable context beyond annotations: fan-out behavior across external services, partial failure degradation, bundlephobia's first-measurement delay (5-30s), and the sources_failed field. This significantly helps agents anticipate latency and incomplete results. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, then gives usage cues, return format, ecosystem scope, and failure behavior. Every sentence adds necessary information for a composite tool with external dependencies. 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?

Despite having no output schema, the description enumerates the return block fields, per-advisory details, links, alternative versions, and sources_failed. It also covers ecosystem scope and timeout behavior. For a tool of this complexity, this is a complete and self-sufficient description.

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

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

The input schema already describes both parameters (package name, version) with clear descriptions and default behavior. The description adds no new parameter-level meaning beyond the schema, which has 100% 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 opens with a specific composite check for npm packages ('should I add this npm package to my project'), names the two data sources (deps.dev and bundlephobia), and lists the exact criteria. This clearly distinguishes it from sibling tools like scan_competitor_ai_presence or validate_claim.

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

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

Explicitly states when to use it ('is X safe / popular / small' or 'what does adding lodash cost me') and notes NPM-only scope for v1, directing non-NPM ecosystems to another route. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already establish the tool as read-only, idempotent, and non-destructive, and the description adds meaningful behavioral context: it returns paginated results (20 per page) and specifies the output fields. This goes beyond the annotations by clarifying the response structure and pagination behavior, though it doesn't cover rate limits or auth (likely not applicable).

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

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

The description is a single, well-structured sentence that front-loads the core purpose ('Search Rick and Morty characters by name') and then efficiently packs in optional filters and return details. Every phrase adds value, with 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 search tool with a rich schema and output schema, the description covers the essential aspects: the search target, optional filters, pagination limit, and returned fields. The schema fills in parameter specifics, so the description is complete enough on its own to guide 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 provides 100% coverage with detailed descriptions for all five parameters, including defaults and partial-match behavior. The description reiterates the filter names (status, species, gender) but does not add new semantic meaning beyond what the schema already offers. The pagination detail ('20 per page') relates to output, not parameter semantics.

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

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

The description uses a specific verb ('Search') and resource ('Rick and Morty characters'), and clearly distinguishes from sibling tools like get_character (exact lookup) and search_episodes (episode search) by emphasizing name-based search with optional filters. It also outlines the returned data, leaving no ambiguity about the tool's function.

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

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

The description provides clear context for when to use the tool: when searching characters by name or filtering by status, species, or gender. It does not explicitly mention exclusions or alternatives (e.g., using get_character for exact IDs), but the search-oriented wording implies this distinction. This is clear context but lacks explicit '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 cover read-only, open-world, idempotent, and non-destructive behavior. The description adds a summary of returned metadata (air date, character list, ID), which is useful but does not disclose deeper behavioral traits like pagination or partial-match handling. No contradiction with annotations.

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

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

The description is a single, well-structured sentence that efficiently conveys the action, resource, search criteria, and output. There is 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?

The tool is a simple search operation with rich annotations, a fully described input schema, and an output schema. The description covers the core purpose and return type, providing adequate context for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% coverage with descriptions for name, page, and episode. The description reinforces the search modes and gives an episode code format example, but it does not add significant semantic value beyond what the schema already provides.

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

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

The description clearly states a search action on Rick and Morty episodes, specifies search criteria (name or episode code), and notes return metadata. It distinguishes itself from sibling tools like get_episode by framing the tool as a search rather than an exact lookup.

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

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

The description implies usage for searching by name or episode code, but it does not explicitly state when to use this tool versus alternatives like get_episode or search_characters. There are no exclusion criteria or alternative recommendations, leaving usage guidance somewhat implicit.

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

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

The description discloses detailed behavior beyond the annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and offsets for verification. This goes well beyond the simple readOnly/idempotent hints.

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

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

The description is front-loaded with the primary action and each of the five sentences adds useful information. However, it's slightly longer than strictly necessary, with some implementation detail that could be trimmed without losing core value.

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

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

Given no output schema, the description conveys a complete picture: input requirements, return format (passages with offsets and scores), use case, and technical constraints. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with each parameter described in the schema. The description reinforces the semantics (e.g., 'Pass the text you already pulled' for text) but adds little beyond what the schema already provides, 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's purpose: 'Semantic search INSIDE a fetched record' with specific mechanics (pass text + query, get top-N passages). It distinguishes itself from siblings like ask_pipeworx_grounded (which grounds over the whole document) and search_characters (which searches by structured attributes).

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

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

Explicit usage guidance is provided: 'Use when the record is too big to cram into the prompt' and it pairs with ask_pipeworx_grounded, explaining the complementary workflow. This gives clear when-to-use and alternative context.

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

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

Beyond annotations, the description adds concrete behavioral details: OAuth account requirement, SMS phone verification and 10/day cap, webhook signing secret returned only once, and auto-disable after 10 failing runs. These go well beyond the idempotentHint and readOnlyHint annotations, with 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 dense but well-structured, front-loaded with the core purpose then expanding into types and delivery details. Every sentence carries useful information, though the length is justified by the tool's complexity.

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

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

Given the lack of an output schema and the tool's complexity (nested params, multiple types, delivery channels), the description is remarkably complete. It covers all subscription types, return value, constraints, and delivery behaviors, leaving little ambiguity for an agent.

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

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

Schema coverage is 100% and the schema already provides detailed descriptions for all parameters. The description adds meaningful examples (e.g., sec_8k items mapping, fred_series series_id) and clarifies delivery semantics, enhancing the schema without being redundant.

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

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

The description states the verb 'Create' and the resource 'proactive monitoring subscription to a live-data event stream', and it clearly differentiates from siblings like list_subscriptions, unsubscribe, and recent_alerts. It also mentions the return value (new subscription id), making the purpose unambiguous.

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

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

The description clearly implies proactive monitoring versus pulling via recent_alerts, and it gives strong usage context with account requirements and specific channel constraints. It does not explicitly name alternatives or say 'use X instead', but it provides sufficient contextual guidance for when to use this tool.

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

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

The description adds significant behavioral context beyond annotations: it details the return format (category-bucketed example questions with exact tool + argument shape), notes the data source ('drawn from the live catalog'), and explains invocation modes (no args vs. with topic). Annotations already cover read-only/idempotent safety, so the description does not need to repeat that, but it adds valuable dynamic behavior 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?

Although long, every sentence earns its place: it front-loads with user-like query examples, explains the output structure, describes parameter behavior, and concludes with explicit when-to-use guidance. The structure is logical and avoids redundancy, making it appropriately sized 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?

For a tool with no output schema, this description is remarkably complete: it covers what the tool returns, how to invoke it in both modes, the categories of questions, and where it fits in the broader tool ecosystem. It gives an agent everything needed to decide when and how to use it correctly.

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

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

Schema coverage is 100% for the single optional parameter, giving a baseline of 3. The description adds meaning by providing concrete examples ('finance', 'pharma', 'betting'), explaining that omitting the parameter returns a full spread, and framing the parameter as a way to 'focus.' This goes beyond the schema's basic listing of allowed values.

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+resource ('suggest questions') and clearly identifies the tool as 'the onboarding entry point' for an agent that just connected. It distinguishes itself from siblings by explicitly stating 'Use this FIRST' and referencing meta-tools like ask_pipeworx, entity_profile, and compare_entities, making its unique role 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?

It provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also names alternative tools and explains how to call the tool with or without the topic parameter, giving clear usage context.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses that subscriptions are deactivated rather than deleted, and that ownership is enforced. This adds meaningful behavioral context not captured in 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?

Three sentences with no wasted words: action, ownership rule, and behavioral outcome (deactivated not deleted). Front-loaded and each sentence contributes essential information.

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

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

For a single-parameter tool with no output schema, the description fully covers the action, the key constraint (ownership), and the post-condition (deactivation with historical events retained). No missing information needed for an agent to invoke it correctly.

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

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

The parameter 'id' is fully described in the schema (UUID returned by subscribe), and the description reinforces its use ('by id') while adding the ownership constraint. Since schema coverage is 100%, the description's extra context about ownership provides modest added value beyond the schema.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource, distinguishing it from related tools like subscribe and list_subscriptions. The ownership enforcement adds specificity without ambiguity.

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 this tool (to cancel a subscription) and provides a relevant alternative ('recent_alerts') for accessing historical events after cancellation. However, it does not explicitly enumerate when not to use it or compare with subscribe/list_subscriptions beyond context.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds significant context: the two routing paths (SEC EDGAR/XBRL vs. grounded pipeline), the specific verdict types, the return of 'verbatim evidence' with pipeworx:// citations, and the claim that it replaces 4–6 sequential calls. This goes well beyond annotations, though it does not discuss latency, rate limits, or potential failure modes beyond 'inconclusive'/'unsupported'.

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 not bloated. It front-loads user-intent examples, then explains the utility, routing, output, and efficiency benefit. Every sentence adds value, though it is longer than strictly necessary. The structure is logical and easy to parse.

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

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

Given the tool's complexity (routing, multiple verdict types, citations, and replacement of multi-step pipelines), the description is exceptionally complete. It covers both the financial and general claim paths, describes the returned data (verdict, actual value, citation, reasoning), and states the benefit (reduces sequential calls). No output schema exists, so the description fully carries the burden of explaining returns, and it does so thoroughly.

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 parameters thoroughly documented. The description does not add meaning beyond the schema for parameters, except for providing natural-language example claims in the opening. The tolerance_pct parameter's semantics are already fully explained in the schema, so the description offers no additional semantic value. Baseline 3 is appropriate.

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

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

The description clearly states that the tool verifies natural-language factual claims and provides examples of user phrasings. It distinguishes itself from sibling tools by specifying the output (verdict types, actual value with citation, reasoning) and the routing logic (SEC EDGAR/XBRL fast path vs. grounded pipeline). This is a specific verb+resource pairing with strong differentiation.

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

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

The description explicitly states when to use the tool ('whenever the agent needs to check whether something a user said is factually correct') and covers both financial and non-financial claim routing. However, it does not explicitly name alternatives or mention when *not* to use it, though the routing explanation implies it handles any claim. Slight gap in exclusion guidance.

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