videogames

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

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

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

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

The description is three sentences, front-loaded with the core action and output, followed by the default behavior and example use cases. Every sentence contributes meaning, with no redundancy or filler.

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

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

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

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

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

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

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

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

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

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

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

The description gives explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional Anthropic key. However, it does not mention when not to use the tool or point to alternatives, so it stops short of full when/when-not guidance.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavior beyond those annotations: it routes queries, fills arguments on behalf of the user, and returns structured answers with stable pipeworx:// citation URIs. No contradiction with annotations exists.

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

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

The description is long, but it is front-loaded with the 'PREFER OVER WEB SEARCH' directive and every major section earns its place: coverage areas, examples, and sibling routing. The breadth of the domain list adds length without much marginal value, so it falls just short of a 5.

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

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

There is no output schema, but the description compensates by stating the return type: a structured answer with stable pipeworx:// citation URIs. With one required parameter, clear examples, explicit usage guidance, and alternative routing, the description 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 description coverage is 100%, with question and all aliases (q, text, input, query, prompt) already documented. The description gives examples of natural-language questions, but those examples reinforce rather than add meaning beyond the schema. Baseline 3 is appropriate because the schema carries the parameter-documentation 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 uses specific verbs and resources: it 'routes the question to the right one of 5,798 tools across 1517 verified sources' and 'returns the structured answer with stable pipeworx:// citation URIs.' It also clearly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, so an agent can tell exactly what this tool is for.

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 is explicit about when to use this tool: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions.' It also gives exclusion criteria by directing users to ask_pipeworx_grounded for hallucination-resistant single answers and to deep_research for broad multi-part questions, which is strong alternative 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 valuable behavior beyond the annotations: candidate routing improvements may be live, no candidate is currently active, and the tool is a full working router with no fallback safety net. This complements the readOnly/idempotent annotation set without contradicting it.

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

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

The description is somewhat long but each sentence serves a purpose: defining the beta relation, current state, usage intent, and fallback clarity. The retirement date is a small extra but supports the claim that no candidate is active.

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, it references ask_pipeworx's response shape rather than describing it directly, which is acceptable given the sibling context. It covers current behavior, safety, and usage conditions well enough for an agent to decide when to invoke it.

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

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

Input schema coverage is 100%, with all aliases documented. The description only adds 'same arguments as ask_pipeworx,' which does not materially improve parameter understanding beyond the schema, 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 identifies the tool as a beta variant of ask_pipeworx, a universal router with the same tool set, arguments, and response shape. It distinguishes this from the stable ask_pipeworx and grounded sibling without being a tautology, though it leans heavily on the sibling for the core semantic.

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 says to use this like ask_pipeworx when you want the newest routing and notes that results are compared against the stable router. It does not explicitly list when-not-to-use cases, but the stable-vs-beta contrast makes the intended context clear.

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

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

Even with readOnlyHint and destructiveHint annotations already covering safety, the description adds significant behavioral context: the refusal contract with specific refusal_reason values, the evidence-quote guarantee, and the extra LLM call cost. It clearly explains how the tool behaves on success and failure, which is far beyond what annotations convey.

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

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

The description is detailed but every sentence earns its place: it front-loads the core mode, explains the mechanism, specifies the return shape, enumerates refusal reasons, states when to use it, and closes with the cost trade-off versus ask_pipeworx. No filler or redundant restatement of the schema exists.

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

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

There is no output schema, so the description fully documents the success return fields and all refusal_reason values, making the tool's behavior complete from an agent's perspective. Combined with read-only and idempotent annotations and the explicit sibling comparison, nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, and the schema already documents question plus all aliases (query, q, prompt, text, input). The description does not add new parameter-specific meaning, so the baseline of 3 is appropriate; no compensation is needed because the schema fully covers the 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 identifies a specific mode ('hallucination-resistant answer mode') and the exact behavior: routing through 5,798 tools, extracting an answer only from tool results, and returning a refusal if the data doesn't answer. It also distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction and evidence, 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 states when to use this tool: 'whenever an answer will be quoted, cited, or acted on' and where hallucination is unacceptable (financial, legal, medical, public statements). It also gives a clear exclusion: 'prefer ask_pipeworx for casual lookups' because of the extra LLM call cost, providing the agent with actionable selection criteria.

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

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

Annotations already establish read-only, non-destructive, idempotent behavior. The description goes far beyond by detailing the resolver contract (match confidence, alternatives, suggestions), response shapes (market, analysis, evidence), news fallback flags, wide-spread tradeability warnings, and cancellation-rule parsing. This is exceptional transparency.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema covers both parameters, but the description enriches meaning by detailing that type='company' pulls specific financial metrics, while type='drug' pulls adverse-event and trial counts. It also provides concrete examples for values (e.g., tickers vs drug names), adding practical semantics not present in the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with explicit trigger phrases like "X vs Y" and "which is bigger." It distinguishes itself from sequential lookups and scope-limits to 2–5 entities, which disambiguates it from potential sibling tools like entity_profile.

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

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

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

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

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

Annotations already mark the tool read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral detail beyond those annotations: account/pricing gating, parallel decomposition across 5,798 tools, gaps[] for unanswered facets, contradictions[] scanning, fetchable pipeworx:// citation URIs, semantically excerpted records, and latency expectations. Nothing in the description contradicts 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 long but information-dense and largely front-loaded with the account requirement, core purpose, and primary alternative before moving into behavioral details. Minor redundancy exists around 'thorough' being paid and repeated mentions of gaps/citations, which prevents a perfect score, but every major section earns its place for such a complex tool.

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

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

There is no output schema, yet the description specifies the return envelope: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and hop fields. It also covers account requirements, latency, depth semantics, and when to prefer a sibling tool, giving an agent everything it needs to call and interpret 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 already documents both parameters at 100% coverage, but the description meaningfully extends that: it quantifies depth behavior (quick=3, standard=3, thorough=6), explains the gap-recovery hops and contradictions scan per depth, and explicitly states that the question parameter accepts natural-language broad/multi-part questions. This adds operational meaning beyond the schema's enum wording.

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 capability—grounded multi-source research over Pipeworx's 1,517 structured data sources—and explicitly contrasts it with open-web search and sibling tools by saying 'this is NOT open-web search.' It names the resource, the decomposition approach, and the output style ('findings packet'), so an agent can clearly distinguish it from ask_pipeworx and other research-related tools.

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

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

The description gives explicit routing rules: if not signed in, use ask_pipeworx; for a single lookup, use ask_pipeworx; for breaking or current news, prefer ask_pipeworx; and for broad/multi-part structured-data questions, use deep_research. This is concrete when-to-use and when-not-to-use guidance that directly steers an agent to the correct sibling.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already mark the tool read-only and idempotent, and the description adds substantial behavioral context: sources_failed vs sources_used semantics, USPTO soft-fail via sunset, empty sections meaning real 'no data,' and private-company resolved:false behavior. It also clarifies expected absence of FDA products for non-biologic companies, preventing false failure interpretation.

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 it is front-loaded with trigger phrases and the most critical usage rule, and the dense middle section earns its place by documenting numerous source-specific quirks. A little redundancy exists around the interchangeable 'type' behavior, but overall it is organized and information-dense rather than padded.

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

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

Given no output schema, the description thoroughly covers the return shape, each data section, source failure behavior, input formats, and edge cases like private companies. An agent has enough context to call this tool correctly and interpret unexpected or empty results without needing additional documentation.

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

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

Schema coverage is already 100%, and the description enriches both parameters by giving concrete examples, explaining zero-padded CIK format, and emphasizing that 'type' values are interchangeable. This goes beyond the schema without duplicating its definitions.

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

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

The description opens with concrete natural-language triggers and the core action: 'full cross-source profile of a US public company in ONE parallel call.' It names the resource (SEC EDGAR, XBRL, USPTO, USAspending, FDA, DOL, GDELT, GLEIF) and clearly distinguishes itself from single-pack lookup chains, making the tool's identity 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?

It explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies when to expect a non-failure result for private companies and states that both 'company' and 'ticker' type values behave identically, giving the agent actionable routing and handling guidance.

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

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

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

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

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

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

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

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

Given the tool's simplicity, the presence of an output schema, and comprehensive annotations, the description covers the important aspects: what is filtered, how the tag format works, and what data is returned. It doesn't mention error handling or invalid tag formats, but these are not critical for simple read-only filtering and are likely covered by the output schema.

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

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

The schema already describes both parameters (tag and platform) with examples, achieving 100% coverage. The description repeats these examples and adds the concept of a 'dot-separated tag combination', but this is already in the schema's example and description. Thus the description adds minimal new meaning beyond the schema.

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

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

The description clearly states the action ('Filter free-to-play games'), the specific resource (FreeToGame), and the distinguishing mechanism (dot-separated tag combination, optional platform). It also lists the return fields, making the purpose unambiguous and distinct from sibling tools like list_games or get_game.

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

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

The description gives clear context on when to use this tool (when filtering by tags and platform), but it does not explicitly name alternatives or state when not to use it. The examples help clarify expected inputs, so context is solid, just lacking explicit exclusions.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description aligns with these but doesn't add new behavioral details such as irreversibility, no-op behavior for missing keys, or return format. It does clarify the scope of previously stored memories.

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

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

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

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

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

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

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

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

Schema covers 100% of parameters, with the key property described as 'Memory key to delete'. The description reinforces 'by key' but adds no additional format or semantic details beyond the schema.

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

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

The description uses the specific verb 'Delete' with the resource 'previously stored memory' and method 'by key'. This clearly distinguishes from sibling tools like remember and recall.

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

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

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

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

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

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

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

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

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

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

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

Despite having no output schema, the description explicitly states 'Output is a single text blob ready to drop at site-root/llms.txt', covering the return format. Combined with annotations and clear process, it's complete enough for this simple read-only tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions 'any URL' and the output format but doesn't add parameter-specific details beyond the schema. It clarifies the output is a single text blob, which is more about output than parameter semantics.

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

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

The description clearly states 'Generate a production-ready llms.txt file for any URL', establishing the specific action and resource. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on generating the file itself rather than checking presence.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It doesn't mention exclusions or alternative tools, but the context is clear enough to guide selection.

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

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

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

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

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

The description is exceptionally concise and front-loaded: the first sentence states the exact action and scope, and the second enumerates the expected output fields. There is no redundant information, and every word contributes to clarity.

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

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

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

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

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

The input schema fully documents the id parameter with a concrete example ('452 for Valorant'), and the description merely echoes that the ID is a FreeToGame ID without adding new meaning. With 100% schema coverage, the description adds no additional parameter semantics, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: retrieving complete details for a specific game by its FreeToGame ID. It explicitly lists the return fields (title, description, genre, platform, publisher, developer, release date, screenshots, and minimum system requirements), and differentiates it from sibling tools like list_games and filter_games, which operate on collections. The verb 'Get' and specific resource make the action unambiguous.

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

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

The description implies a targeted lookup context by specifying 'by its FreeToGame ID', suggesting usage when you already have an ID and need full details. However, it does not explicitly state when to prefer alternatives like list_games or filter_games, nor does it provide exclusion guidance. The context is clear but not formally articulated.

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

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

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

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

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

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

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

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

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

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

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

The schema description coverage is 100%, with each parameter already having a clear description of allowed values. The tool description restates the filterable fields and provides examples, but adds little beyond the schema. Baseline 3 is appropriate since schema does the heavy lifting.

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

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

The description uses a specific verb ('List') and resource ('free-to-play games from FreeToGame'), and clearly conveys the tool's scope via optional filters and sorting. This distinguishes it from siblings like get_game and filter_games, which target specific entities or more refined filtering.

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

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

The description implies when to use the tool (when you need a list of free-to-play games with optional filtering/sorting) but does not explicitly mention exclusions or alternatives. The sibling list makes it easy to infer, but there is no direct 'use X instead' guidance, so it falls short of a 5.

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

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

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

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

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

The description is two sentences, front-loaded with the primary purpose, then return fields, then a practical use case. Every sentence carries useful information with no fluff or repetition.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

All annotations are false, so the description carries the full burden. It discloses the claim_token workflow for later retrieval, rate limiting ('5 per identifier per day'), that it is free and doesn't count against quota, and that the team reads digests daily. These are meaningful behavioral traits 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 long (9 sentences), but every sentence carries information and is front-loaded with the core purpose. The sections on usage, exclusions, workflow, and limits are logically structured. It earns its length, though it is not as minimal as the TDQS 4.3 example.

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 covers the return mechanism via claim_token, explains resolution timing, and provides all necessary context for correct invocation. Nothing critical is missing, making it a complete description for a non-trivial 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 significant value beyond the structured fields. It explains the claim_token mechanism with an example call, and gives guidance for the message parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt').

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from sibling tools by restricting its scope to tools served by this Pipeworx connection, unlike ask_pipeworx or other query tools.

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

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

It 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 clear exclusion: if the tool came from a different MCP server, report it there instead, saying 'we cannot fix it and reporting it here only delays you.'

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

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

Annotations already establish read-only and non-destructive behavior. The description adds meaningful context beyond that: it reveals the data source (CF analytics-engine), confirms no PII, specifies the output shape (pack, tool, count), and explains caching (5min-1h). This is valuable transparency not derivable from annotations.

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

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

The description is efficiently organized: the core function in the first sentence, a bulleted list of use cases, and two concise sentences about data provenance and caching. No redundancy with schema fields, and every sentence contributes unique information.

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

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

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

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

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

The input schema fully covers the window parameter with a description that already explains the tradeoff between short and long windows. The tool description merely restates the windows without adding new semantic detail, so it meets the baseline 3 for high schema coverage.

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

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

The description opens with a specific, informative question ('What other AI agents are calling on Pipeworx right now?') and clearly states the output ('top tools, top packs, and total call volume'). This distinguishes it from sibling tools like discover_tools or ask_pipeworx by clarifying it provides aggregated usage trends, not individual discovery or Q&A.

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

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

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

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

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

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

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded key info. Every sentence adds unique value for a tool of this complexity, though it could be tightened slightly without losing critical detail.

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

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

The tool has 2 optional parameters, no output schema, and is a complex arbitrage scanner. The description fully compensates by outlining response fields (opportunities[], partition_check), filters, and edge-case handling (thin_legs, null arb signal). It also references the sibling tool for custom sizing, making it complete for an agent to select and invoke correctly.

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

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

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

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes between event and topic modes, and the level of detail about each mode differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

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

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

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

Beyond the annotations (readOnly, idempotent), the description discloses substantial behavior: caching at KV level ('Cached 1h at the KV level keyed on all knobs'), diagnostics for empty segments, model-specific caveats (unreliable Fed signal, placeholder-slug filters, per-sport alpha), and slippage handling. This provides far more transparency than the structured annotations.

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

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

The description is long but well-structured with sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and front-loaded with the core purpose. Every sentence carries unique information; while verbose, it is appropriately sized for the tool's complexity.

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

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

No output schema is provided, but the description thoroughly explains the response top-level (by_segment, fed_candidates, _diagnostics), model families, filter behavior, and knob effects. It also covers edge cases like placeholder filtering and time-based staleness, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds value by grouping parameters as 'TRADEABLE-EDGE KNOBS' and explaining subtle interactions (e.g., min_partition_leg_kelly applies to per-leg Kelly because parent-level is 0 by design). This elevates it above baseline.

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

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

The description opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' – a specific verb, resource, and unique value proposition. It also states 'Built for "what should I bet on today"', which clearly distinguishes it from general market scanners and sibling tools.

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

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

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

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

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

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

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

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

The description is long but every sentence is substantive. It is cleanly structured with 'Args:', 'RESPONSE:', and 'LIMITS:' sections, making it easy to scan. The opening sentence immediately conveys the core value proposition. No filler or redundant restatement of the tool name or annotations.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so exhaustively: tracked[], expired[], and snapshot_dates[] are all defined with their inner fields and semantics. It also covers edge cases (gaps, age limits, signed edge values). This is a model of completeness for a telemetry tool.

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

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

The schema covers both parameters completely (100% coverage), so the baseline is 3. The description adds meaning beyond the schema by defining 'window' as a 'snapshot family' and explaining that snapshot dates correspond to days with actual data. It also reiterates defaults and clamps in a way that reinforces the schema. This extra context nudges the score to 4.

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

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

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

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

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

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

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

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

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

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

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

Though lengthy, the description is densely packed and every sentence adds value. It is structured with capitalized section markers (SINGLE-MARKET, BASKET) and front-loaded with the core purpose. The length is justified by the complexity of the tool, and there is no redundancy or filler.

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

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

Given the tool's complexity—two modes, multiple return fields, and integration with sibling tools—the description is complete. It explains inputs, outputs, defaults, constraints (size clamp), risk scenarios, and recommended usage context. Since there is no output schema, the description fully compensates by enumerating all returned metrics and verdict values.

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

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

While the input schema already covers all parameters at 100%, the description enriches their meaning significantly. It clarifies how size_usd is interpreted in single-market vs basket mode ('max spend on buys, target proceeds on sells' vs 'settlement notional — shares per leg, each paying $1'), explains the default behavior of side in basket mode, and distinguishes market vs event parameters with concrete usage context. This is far beyond schema coverage.

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

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

The description opens with a specific, action-oriented purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes its function from sibling tools by naming polymarket_arbitrage and polymarket_edges, and it fully explains the two modes (single-market and basket), leaving no ambiguity about what the tool does.

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

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

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

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

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

Given annotations already mark the tool read-only and idempotent, the description adds substantial behavioral context: matching is keyword/word-overlap based, compatibility_codes can be non-empty even with matched pairs, unclassified legs are never paired, spreads are gross (fees not modeled), and temporal_alignment null does not mean aligned. These disclosures give the agent a realistic picture of how to interpret results.

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, using labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and explicit code names, with every sentence adding operational value. It front-loads the core purpose and mode selection, and 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?

There is no output schema, so the description carries the full burden of explaining return semantics; it covers top_spreads_pp, compatibility_codes, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and cross-type/subtype counters. Combined with the strong annotations, an agent has everything needed to invoke and interpret this tool correctly.

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

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

The schema already documents all three parameters (100% coverage), so the baseline is 3, but the description goes well beyond by explaining mode semantics: topic is a pre-mapped shortcut, kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and both modes run the same matcher. This is critical for an agent to understand how to combine parameters correctly.

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 statement of what the tool does: compute a cross-venue spread between Kalshi and Polymarket for the same resolving question. It further details two input modes and the output shape, making it easy to distinguish from siblings like polymarket_arbitrage or polymarket_edges.

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

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

The description clearly explains the two invocation modes (topic shortcuts vs explicit ticker/slug) and warns that most pre-mapped topics currently return compatibility_warning, signaling when the macro shortcuts are not reliable. However, it does not explicitly name sibling tools as alternatives, so the when-not-to-use guidance is implied rather than directly stated.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Three sentences, each earning its place: the first states what the tool returns, the second covers filtering and mark_read, and the third addresses polling and an alternative access route. Concise and well-structured.

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

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

Even without an output schema, the description covers return fields (source, citation_uri, raw payload), parameter semantics, polling suitability, and an external endpoint. This is complete enough for an agent to invoke the tool correctly.

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

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

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

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

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

The description uses a specific verb ('Pull') and names the exact resource ('fired events from your subscription feed'). It clearly distinguishes this tool from siblings like list_subscriptions by describing returned alert content and persistence behavior.

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

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

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

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

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

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

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

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

The description is dense but every sentence adds value, from user-facing examples to source details to output summary. It is well-structured, front-loaded with the query patterns the tool answers, and avoids fluff.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Three concise sentences, each serving a distinct purpose: purpose, usage context, and operational details. No filler or redundant content. Highly efficient and well-structured.

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

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

For a simple two-parameter tool with no output schema, the description covers all critical aspects: what it does, when to use, storage lifetime, scoping, and relationship to sibling tools. No meaningful gaps for the agent to misuse it.

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

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

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

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

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

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

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

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

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

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

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

Beyond the read-only/idempotent annotations, the description discloses substantial behavior: graceful degradation when GLEIF/OpenFIGI is unavailable, returning `figi_candidates` when a name matches multiple instruments, labeling identifiers by source, and explicitly listing unresolved identifiers rather than omitting them. This is far more than annotations alone convey.

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 section earns its place: examples front-load the purpose, supported types and their behavior come next, and crucial parameter caveats follow. It is structured by use case rather than being a wall of text, and there is no filler.

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

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

There is no output schema, but the description compensates by explaining what the tool returns: source-labelled identifiers, `unresolved`, and `figi_candidates`. It also covers external-service outages, supported input types, and the ISIN-to-LEI path. An agent has everything needed to invoke this tool correctly in a variety of situations.

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?

Even though schema coverage is 100%, the description adds high-value semantics: for `value`, it instructs passing only the entity name, warns against full phrase for bonds, and provides specific formats like ticker, CIK, ISIN, or name. This prevents a real failure mode and is meaningfully beyond the schema's brief property 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 concrete user queries and a crisp statement: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly names the supported entity types (company, drug) and what identifiers each returns, so an agent can distinguish this from sibling tools like entity_profile or compare_entities.

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

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

It gives an explicit usage rule: 'Use FIRST whenever you have a name but need an ID,' and explains that one call replaces 2-3 manual lookups. It does not name sibling alternatives or give explicit when-not-to-use cases, but the positive guidance is strong and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds meaningful context: it probes each entity using ai_visibility_check, ranks results, and returns a ranked list with score/confidence/signal density. This goes beyond structured annotations without contradicting them.

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

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

Two sentence description, front-loaded with core purpose. Every clause adds value—how it works, use case, and return format—with no redundancy or filler.

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

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

For a tool with 4 parameters, important behavioral traits, and no output schema, the description covers purpose, use case, probing mechanism, ranking logic, and return structure. It lacks only minor details like entity count limits, but these are already present in the schema, so the description is sufficiently complete.

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

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

Schema coverage is 100%, with each parameter fully described (e.g., entities explains first-entry-as-subject). The description echoes the entities semantics ('your brand + N competitors') but adds no new detail beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly identifies the action ('Compare AI visibility across multiple entities side-by-side') and explains the mechanism (probes each entity with ai_visibility_check, ranks by score). It distinguishes from siblings by focusing on competitive multi-entity comparison, directly referencing an underlying single-entity tool.

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

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

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

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

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

Beyond the readOnly/idempotent annotations, the description discloses partial failure behavior (bundlephobia first measurement can take 5-30s, sources_failed lists timeouts, rest still returns), plus it enumerates the exact return fields. This adds substantial operational context.

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

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

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

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

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

Despite lacking an output schema, the description lists all return components (summary block fields, advisory details, links, alternative versions) and covers edge cases like scoped packages and timeouts. It is complete for a tool of this complexity.

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

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

The input schema already provides complete descriptions for both parameters (package name and version, with default behavior for version). The description adds no new parameter-level detail beyond what the schema states, so the baseline of 3 applies.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It differentiates from siblings by emphasizing internal search over a previously fetched text, and the 'too big to cram into the prompt' context clarifies its unique role.

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

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

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

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

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

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

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

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

The description is dense but well-structured, front-loading the core purpose and then methodically covering authentication, supported types, and delivery channels. It is longer than typical but every sentence contributes essential information, with no redundant filler.

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

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

Given the tool's complexity (nested objects, multiple types, no output schema), the description is remarkably complete: it states the return value, auth prerequisites, all subscription types, and delivery methods. The only minor gap is that webhook delivery details are not in the main description, but they appear in the delivery schema, so overall coverage is strong.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is two sentences: the first states the action, the second explains the key side effects. It is front-loaded with the primary purpose and contains no redundant or filler content.

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

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

For a simple single-parameter tool with strong annotations and schema coverage, the description fully covers the essential context: what the tool does, key constraints (ownership), and the non-destructive behavior. No output schema exists, but one is unnecessary for this straightforward operation.

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

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

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

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

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

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

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

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

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

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

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

The description goes far beyond the annotations by explaining two distinct execution paths (SEC EDGAR fast path and grounded pipeline), listing all six verdicts, and adding the crucial caveat that 'could_not_verify' does not constitute evidence and carries verification_error{stage,detail}. It also clarifies the nuanced difference between 'unsupported' and 'could_not_verify.' This is exemplary behavioral disclosure.

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 compact and front-loaded, starting with trigger phrases and a one-sentence definition, then organizing routing, return values, and caveats logically. Every sentence adds value—even the 'Replaces 4–6 sequential calls' line is informative. It strikes a good balance between completeness and brevity.

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 adequately specifies the return format (verdict, actual value with citation, reasoning) and explains edge cases that could be misused ('could_not_verify' vs. 'unsupported'). It covers the full agent-facing surface: when to invoke, what routing happens, what the verdicts mean, and how failures are reported. No significant operational gap remains.

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

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

The input schema already provides 100% coverage for both parameters, including natural-language claim examples and a thorough description of tolerance_pct semantics. The tool description adds no parameter-specific details beyond the higher-level claim concept already present in the schema. So the baseline of 3 applies, as the description doesn't meaningfully supplement 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 is exceptionally clear about the tool's purpose: it verifies natural-language factual claims against authoritative sources and returns a verdict. It provides concrete trigger phrases ('Is it true that…', 'fact check') and distinguishes itself from more general Q&A tools by specifying the verdict output and the SEC/grounded routing. No ambiguity remains about what the tool does.

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

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

The description gives an explicit when-to-use directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal routing for company-financial vs. other claims, which helps the agent anticipate behavior. However, it does not explicitly name alternative tools or state when NOT to use it, so it misses the 'when-not' element for a top score.

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