Ietf Datatracker

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

Annotations already provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context beyond that: it reveals external API calls to Anthropic when _apiKey is provided, including the cost implication (BYO key, pay Anthropic directly). This goes beyond the annotations and clarifies side effects.

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

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

The description is compact and front-loaded: first sentence states the core action, second describes the return format, third lists use cases. Every sentence adds value with 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?

The description covers the main aspects: what it does, return structure (score, confidence, signals, raw_response, combined view), model options with cost, and use cases. For a moderately complex tool with 4 parameters, this is sufficient, though it doesn't discuss error handling or time expectations.

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

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

Schema description coverage is 100%, so all parameters (entity, models, _apiKey, context) are already documented in the schema. The description reinforces the model defaults (Workers AI free, Anthropic requires key) but does not add significant 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 tool probes LLMs and scores visibility (0-100) per model, with a specific resource (business/brand/product/topic). However, it does not explicitly distinguish itself from similar siblings like scan_competitor_ai_presence, so it misses the top tier for sibling differentiation.

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

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

The description gives clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and indicates when to use the free default vs. Anthropic. It lacks explicit 'when not to use' or alternative tool mentions, but the context is sufficient for basic 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 reveals that the tool routes to 5,529 tools across 1455 verified sources, fills arguments automatically, returns stable citation URIs, and makes one fast call on every tier. These details go beyond the readOnlyHint and idempotentHint annotations, setting expectations about behavior without contradicting them.

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

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

The description is longer than most but every section contributes value: it starts with a commanding 'PREFER OVER WEB SEARCH' lead, provides examples, then gives explicit alternatives. It could be tightened slightly but is well-structured and front-loaded.

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

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

With no output schema, the description compensates by explaining the return format (structured answer with citation URIs), listing example queries, and providing usage context for different scenarios. It's complete for a complex tool, covering both general use and edge cases like breaking news.

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

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

The input schema already covers all six parameters with aliases and a clear description of the question field. The description adds no additional parameter-level semantics beyond the schema, but it doesn't need to since coverage is 100%.

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: it answers factual questions by routing to a large network of tools and returns a structured answer with citations. It distinguishes itself from siblings by naming comparisons like ask_pipeworx_grounded and deep_research, and emphasizes it's the default entry point.

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

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

The description explicitly advises to prefer this over web search and states 'START HERE for most questions'. It also provides concrete 'step up' alternatives: ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions, giving clear when-to-use vs when-not.

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 readOnly, openWorld, idempotent, and non-destructive traits. The description adds valuable context about candidate routing improvements, the current inactive candidate state, and that it is a full working router with no fallback. No contradiction with annotations.

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

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

Three sentences with the key 'Beta version of ask_pipeworx' front-loaded. Some specific details (5,529 tools, date) are included but are relevant to the beta status and current behavior. Not overly verbose.

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

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

For a simple question-routing tool, the description covers what it is, how to use it, and its current state relative to the stable version. It notes the same response shape, which compensates for the lack of an output schema. Complete enough for an agent to make an informed choice.

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 a full description for the question parameter and aliases. The description mentions 'same arguments' but does not add semantic depth beyond the schema. Baseline 3 applies as the 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 clearly identifies this as the beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx and siblings by its experimental status and mentions the 'newest routing' purpose. The verb+resource is somewhat implicit but clear enough.

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 instructs to use it exactly like ask_pipeworx when wanting the newest routing, and notes that results are compared against the stable router. It does not explicitly list when-not-to-use scenarios, but the experimental vs stable distinction gives clear context.

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

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

The description goes well beyond the annotations by detailing the exact return shape on success and on refusal, including specific refusal_reason values. It discloses the extra LLM call cost, the extraction-only-from-tool-result constraint, and the routing behavior. This adds significant context beyond the readOnlyHint and idempotentHint annotations. No contradiction.

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

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

The description is dense but well-organized, front-loading the core purpose ('Hallucination-resistant answer mode') before detailing mechanics, return formats, and usage. It is longer than minimal but every sentence adds distinct value. Slight redundancy with sibling differentiation but overall efficient 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?

The tool has no output schema, so the description carries the full burden of explaining return values. It provides a detailed JSON structure for both success and refusal cases, including all refusal_reason enums. It also covers higher-level context: high-stakes use cases, cost trade-off, and the fact that it routes across 5,529 sources. This is complete for a complex tool.

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

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

Schema coverage is 100% (all 6 parameters are question aliases with descriptions, and the required parameter is clearly documented). The description does not add parameter-level detail beyond mentioning that the tool 'fills arguments' for routing, but since the schema fully explains the parameters, the baseline 3 applies.

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

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

The description clearly states the tool's function: a hallucination-resistant answer mode that routes like ask_pipeworx, fetches data, and extracts answers only from the tool result. It explicitly distinguishes itself from siblings by contrasting with ask_pipeworx ('Same routing as ask_pipeworx... then EXTRACTS...') and noting the extra LLM call cost, making its unique role clear.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives an exclusion/alternative: 'prefer ask_pipeworx for casual lookups,' plus a cost-based trade-off. This is explicit 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?

Beyond the readOnly/idempotent annotations, the description reveals significant behavioral complexity: parallel fan-out, classifier taxonomy, response shapes, resolver match confidence, fallback mechanisms, low-confidence short-circuit, closed-market handling, spread illiquidity detection, and cancellation-rule parsing. This far exceeds annotation coverage.

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?

While long, the description is extremely well-structured with clear section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and every sentence carries operational information. It is front-loaded with the core purpose and then provides necessary edge-case 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 description leaves no obvious gaps: it covers input formats, resolution behavior, output shape, edge cases (low-confidence, closed markets, wide spreads), and a specific risk (cancellation rules). Given there is no output schema, this text bears the full burden of explaining results, and it does so thoroughly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds illustrative fan-out examples and default behaviors, but these are already present in the input schema (e.g., depth default and include_raw semantics). The description does not meaningfully add parameter semantics beyond what the schema provides.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet' and explains the resolution, classification, fan-out, and output in one clear sentence. It distinguishes from sibling tools like polymarket_edges by focusing on a single bet's evidence packet rather than cross-market comparisons.

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

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

It explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and gives concrete fan-out examples. However, it does not name explicit alternatives or when-not-to-use cases.

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

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

With annotations already declaring read-only and idempotent hints, the description goes far beyond by disclosing data sources (SEC EDGAR/XBRL, FAERS), handling off-calendar fiscal years, result sorting by primary metric, return format (paired data + pipeworx:// citation URIs), and the parallel single-call nature. This adds substantial behavioral context 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 longer than typical, but it is front-loaded with trigger phrases and a preference statement, and every sentence adds behavior or context. It could be slightly condensed without losing core meaning, but it remains well-structured and efficient for the richness it conveys.

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

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

Given the tool's complexity (two entity types, 2–5 items, data sources, sorting, output), the description covers type-specific behavior, input constraints, output format, sorting rationale, and the advantage over sequential lookups. With no output schema, this description makes the tool self-sufficient for an agent to select and invoke correctly.

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

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

Although schema coverage is 100%, the description enriches parameter semantics by specifying exactly what each type pulls (company: latest 10-K revenue, net income, cash, long-term debt; drug: FAERS adverse-event counts, FDA approval counts, active trial counts) and clarifying value formats (tickers/CIKs vs names). This goes well beyond the schema's generic 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 defines a parallel side-by-side comparison tool for 2–5 companies or drugs, with explicit trigger phrases ('Compare X and Y', 'X vs Y', 'which is bigger') and a specific verb+resource: 'side-by-side comparison of 2–5 companies or drugs.' It distinguishes itself from sequential single-pack lookups and sibling tools like entity_profile, making the purpose unambiguous.

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

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

It explicitly states when to use the tool: whenever the user requests a comparison, and even instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides concrete example queries, type-specific behavior, and notes it replaces 8–15 sequential lookups, giving strong contextual and 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses authentication requirements ('ACCOUNT REQUIRED'), pricing implications ('thorough needs a paid plan'), latency expectations ('15-60s'), the gaps[] behavior for unanswered facets, citation fetchability guarantees, and semantic excerpting of large records. This is rich behavioral context that the annotations do not provide.

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

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

The description is long but front-loaded with the most critical operational constraints (account requirement, fallback tool, and non-open-web nature). Each sentence contributes usefully, though the text is a dense single paragraph and repeats some points (e.g., using ask_pipeworx). It is more comprehensive than concise, but the structure is effective for a complex tool.

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

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

The tool is highly complex with parallel research, facets, citations, gaps, and contradictions. The description covers the return format (findings packet, gaps[], contradictions[], hop field, citation_uri), performance expectations, authentication, and edge cases. Even without an output schema, the description is complete enough for an agent to understand what to expect.

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

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

The input schema already provides 100% coverage for both parameters, including a detailed enumeration of the depth option ('quick=3... standard=5... thorough=8'). The description restates this information but does not materially add new parameter-specific semantics beyond the schema. Therefore the 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 defines the tool as 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and explicitly contrasts it with open-web search and ask_pipeworx, making the purpose specific and distinct. It also lists example use cases like 'compare X and Y's regulatory + financial exposure', which clarifies the intended resource and action.

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 guidance: 'Best for broad/multi-part questions over structured data' and directly names alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also provides an account-based fallback ('If you are not signed in, use ask_pipeworx instead'), covering when-to-use and when-not-to-use.

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

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

The annotations already declare this as a safe read-only, idempotent operation. The description adds valuable behavioral context: it returns top-N tools with names, descriptions, full input schemas, and curated examples, and explicitly notes that results are ready to call directly with no second schema lookup. This goes beyond the annotations and helps the agent understand the return value, though it doesn't discuss rate limits or error handling.

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

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

The description is front-loaded with the core purpose, then provides a list of covered domains (which, while long, is useful for matching agent intents), and ends with the output format and a strong usage directive. Every sentence earns its place, and the structure is clear. It is slightly longer than strictly necessary, but the domain list adds significant retrieval 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, a rich schema, and strong annotations, the description is mostly complete. It explains the return format (top-N tools with schemas), the use case, and when to call it. The only minor gap is not explaining what 'top-N' means in terms of ranking, but the provided examples and schema cover the essential information an agent needs 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 input schema has 100% coverage—every parameter (query and its aliases, limit) has a description. The description itself does not add any parameter-level meaning beyond what the schema already provides, so the baseline score of 3 is appropriate. The examples in the schema (e.g., 'look up FDA drug approvals') are more detailed than anything in the description.

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

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

The description opens with a specific verb and resource: 'Find tools by describing the data or task.' It clearly distinguishes itself from sibling tools by being a meta-tool that discovers other tools, rather than performing a specific data task. The scope is further clarified with a list of supported domains (SEC filings, FDA drugs, etc.), leaving no ambiguity about its 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 explicitly states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist' and adds a strong trigger: 'Call this FIRST when you have many tools available.' It implies when not to use it ('not just one answer') but does not name specific alternative tools or give explicit exclusions, so it stops short of a perfect 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the expected name format (RFC or IETF draft), but does not describe behavior like error handling or response size. Given the annotations, this is adequate but not rich.

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

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

The description is a single sentence with inline examples. It is front-loaded with the core action and the examples are directly relevant. No wasted words.

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

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

For a simple lookup tool with one parameter, rich annotations, and an output schema, the description is mostly complete. It defines the input format and the behavior is implicitly read-only. The main gap is not explaining the difference from sibling lookup tools, but that is a usage guideline issue rather than a completeness issue.

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 has 0% description coverage for the 'name' parameter, so the description must compensate. It provides concrete examples ('rfc9000', 'draft-ietf-quic-transport'), which give useful format context. It doesn't define a complete pattern, but the examples are sufficient for a single string parameter.

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 says 'Document by name' with examples, but the verb 'Document' is ambiguous—it could mean 'to document' or 'get the document'. The examples clarify it's a lookup, but it doesn't explicitly state the action (e.g., 'retrieve', 'fetch'). It does distinguish from 'documents_search' by implying a direct name-based lookup.

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

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

No guidance is provided on when to use this tool versus alternatives like 'documents_search', 'rfc', or 'wg'. The description only states what it does, not when to choose 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful context by specifying the return fields (names, titles, statuses) and filter categories. It does not mention pagination behavior, rate limits, or other behavioral details, but given the annotations, the bar is lower and this is adequate.

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

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

The description is a single, front-loaded sentence that states the action, resource, filters, and output. Every word earns its place, with no repetition or filler.

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

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

The description, combined with the rich output schema and safety annotations, gives the agent sufficient context to invoke the tool. It names the filter types and output fields, covering the core use case. A minor gap is that it does not mention pagination or default limit despite having offset/limit parameters, but the schema covers those details.

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

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

Schema description coverage is 80%, and the schema already explains each parameter (e.g., type values, states format, limit range). The description echoes the filter names but does not add semantics beyond what the schema provides. This meets the baseline but does not exceed it.

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 ('Search'), the resource ('IETF Datatracker documents'), and the output ('document names, titles, and statuses'). It specifies optional filters, which helps define scope. However, it does not distinguish this tool from sibling tools like 'rfc' or 'document', so it falls short of a 5.

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

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

The description implies usage for searching IETF documents with filters, but it does not provide explicit guidance on when to prefer this tool over alternatives or when not to use it. No alternatives are mentioned, and sibling tools like 'rfc' and 'wg' exist but are not referenced.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds valuable behavioral traits beyond that: it mentions the patent API 'sunset May 2025 — soft-fails until reactivated' and the parallel fan-out approach. No contradiction with annotations.

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

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

The description is long but well-structured: trigger phrases, output summary, behavioral notes, and usage caveats each earn their place. It is dense but justified given the tool's complexity; slight deduction for the open set of example queries.

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

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

No output schema exists, but the description fully compensates by detailing every return component (CIK, company_name, recent_filings with URIs, fundamentals with field names, patents, news, LEI) and edge cases (patent soft-fail, name unsupported). This is complete for a complex read tool.

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

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

Schema coverage is 100%, with descriptions for both parameters (type enum for 'company', value as ticker/CIK). The description reinforces with examples but adds no additional semantic meaning 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 states it creates a 'full cross-source profile of a US public company in ONE parallel call' and enumerates specific outputs (CIK, filings, fundamentals, patents, news, LEI). It explicitly contrasts with chaining single-pack lookups and directs name queries to resolve_entity, distinguishing it from siblings.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also gives a clear exclusion and alternative: 'names not supported (use resolve_entity first).' This fully tells the agent when to invoke this tool 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 declare destructiveHint=true and idempotentHint=true, covering core behavioral traits. The description adds no additional behavioral details beyond what annotations provide, such as permanence of deletion or what occurs if the key does not exist. It mentions a use case ('clear sensitive data') but this is usage guidance rather than a distinct behavioral trait.

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

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

The description is two sentences long, front-loaded with the core action, then usage context, and ends with sibling references. No unnecessary words; every sentence adds value.

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

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

For a simple one-parameter deletion tool with strong annotations (destructive, idempotent), the description covers purpose, when to use, and relationship to siblings. The absence of an output schema is acceptable given the low complexity; no further behavioral details are necessary.

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

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

Schema coverage is 100% with the 'key' parameter described as 'Memory key to delete'. The description reiterates 'by key' but adds no further semantic detail, such as key format, how to obtain valid keys, or naming conventions. Baseline of 3 is appropriate since the schema carries the parameter meaning.

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 ('Delete') and resource ('previously stored memory') with a clear method ('by key'). It explicitly distinguishes itself from sibling tools remember and recall by positioning itself as the deletion counterpart.

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 conditions for use: 'context is stale, the task is done, or you want to clear sensitive data.' It also names companion tools ('Pair with remember and recall'), providing clear guidance on when to use this tool versus its siblings.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, and the description adds useful behavioral details: fetches the page, extracts title/description/key links, and emits a single text blob in standard markdown. This goes beyond the annotations without contradicting them.

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

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

Three sentences with no waste: purpose, process, and use cases. Front-loaded with the action and resource, making it immediately scannable.

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

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

Even without an output schema, the description explains exactly what the output is (a text blob in llms.txt format) and when to use it. Annotations cover the safety profile, leaving no critical gaps for a two-parameter tool.

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

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

Schema coverage is 100% and both parameters already have descriptive text. The description adds no new parameter-specific meaning, so the baseline 3 applies.

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

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

The description starts with a specific verb+resource: 'Generate a production-ready llms.txt file for any URL'. It clearly distinguishes from sibling tools like scan_competitor_ai_presence and ai_visibility_check by focusing on llms.txt 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?

Explicitly lists real-world use cases: getting a client's site indexed, drafting your own llms.txt, and auditing a competitor. It doesn't name alternatives or exclusions, but the context is clear and sufficient for an agent to decide when to use it.

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

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

Annotations already indicate the tool is read-only, open-world, and idempotent. The description adds specific behavior beyond annotations: it returns the caller's active subscriptions only, and enumerates the exact fields (id, type, params, created_at, last_fired_at, fire_count). This clarifies scope and output format that the annotations do not cover.

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

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

The description is two sentences long, front-loaded with the purpose in the first sentence, and immediately follows with return fields and usage guidance. Every sentence earns its place 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 simple list tool with one optional parameter, strong annotations (read-only, open-world, idempotent), and no output schema, the description is sufficiently complete. It tells what it lists, what fields are returned, and when to use it, covering all essential context an agent needs.

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

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

Schema description coverage is 100% for the only parameter ('include_inactive'), so the schema fully explains its meaning. The description doesn't mention the parameter, but it doesn't need to—the schema handles it. The description adds no extra parameter semantics beyond what the schema already provides.

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

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

The description clearly states the verb 'List' and the specific resource 'caller's active subscriptions', making the tool's purpose unambiguous. It also lists the return fields, which further clarifies what the tool produces, and distinguishes it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description explicitly says to use this tool to review what you're monitoring before adding more subscriptions or to find an ID to cancel, which provides clear when-to-use guidance. It doesn't explicitly name alternatives but implies that this is the read tool to precedes 'subscribe' or 'unsubscribe'.

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 false, so safety is covered. The description adds value by disclosing the return fields (name, email addresses, affiliated organizations) and specifying the source domain (IETF Datatracker), which is beyond the structured metadata. No contradictions with annotations.

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

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

The description is a single, front-loaded sentence that efficiently conveys the action, resource, parameter, and return payload. Every word contributes value, 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 simple one-parameter fetch tool with a rich annotation set and an output schema, the description covers all necessary context: what it fetches, how (by numeric ID), and what it returns. No additional behavioral or procedural details are needed.

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

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

With schema coverage at 0%, the description must clarify parameter meaning. It does so by saying 'by numeric ID', which explains that the 'id' parameter is a numeric IETF Datatracker identifier, not an arbitrary number. This adds meaningful context beyond the schema's bare 'type: number'.

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 specifically states 'Fetch an IETF Datatracker person record by numeric ID', using a clear verb and resource, and distinguishes itself from sibling tools like rfc, wg, and document by targeting person records. It also specifies the return content (name, email addresses, affiliated organizations), making the purpose fully 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 usage context: use this when you have a numeric IETF Datatracker person ID. However, it does not explicitly mention alternatives or when not to use it, especially relative to similar-looking siblings such as entity_profile or resolve_entity. The context is clear but lacks explicit exclusions or 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?

Annotations are all false, so the description carries full burden and does so well. It discloses the claim_token return behavior for anonymous filing, rate limit (5/day), cost (free, no quota), and that the team reads digests daily. It also clarifies what not to include (end-user's prompt). No annotation contradiction exists.

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

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

The description is longer than average but every sentence adds functional value: purpose, usage, exclusions, token behavior, rate limit, quota. It is front-loaded with the main purpose and uses emphasis ('ONLY') to highlight the most critical constraint. Slightly dense but appropriately structured 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?

The description covers all necessary context given there is no output schema. It explains return behavior (claim_token), how to read status, time-to-resolution indication (team reads daily), exclusions, and rate limits. With 0 required parameters and nested objects, the description fully compensates for the lack of an output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining how to use claim_token as a follow-up ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed') and by advising feedback be phrased 'in terms of Pipeworx tools/packs.' This elevates it above the baseline.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes itself from siblings like ask_pipeworx by focusing on feedback rather than querying, and explicitly enumerates feedback categories (bug, feature/data_gap, praise).

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

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

Provides explicit when-to-use guidance: 'Use 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).' Also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and instructs users to file with a different server otherwise. This is exemplary and more thorough than the get_calls example.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, destructive=false), the description adds valuable behavioral context: it is 'derived from CF analytics-engine', contains 'no PII', and is 'cached 5min-1h depending on window'. These details inform the agent about data provenance, privacy, and freshness.

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 slightly longer than minimal but every sentence adds value: the opening sentence states the core function, then returns, use cases, and technical details. It is well-structured and front-loaded, though it could be trimmed slightly without losing content.

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

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

With no output schema, the description adequately explains the return values ('top tools, top packs, and total call volume', 'just (pack, tool, count)'). Combined with the good annotations and a single simple parameter, the description is complete for an agent to decide whether and how to invoke the tool.

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

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

The input schema already fully describes the 'window' parameter, including its enum values and meaning (100% coverage). The description merely reiterates the window options without adding new semantics. Since schema coverage is high, 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 what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' This is a specific verb, resource, and scope. It also distinguishes itself from siblings by focusing on what other AI agents are calling, which is a unique angle not seen in the sibling list.

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: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. It gives clear context for when to use the tool, though it doesn't explicitly state alternatives or exclusions relative to sibling 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?

The description adds substantial behavioral detail beyond the annotations: it explains the partition-check mechanism, semantic similarity threshold (Jaccard ≥ 0.30), placeholder filtering, and the fill-check logic with realizable edge. It clearly warns 'do not trade it' when realizable_edge_pp ≤ 0, and the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent with this read-only analytic description. No contradictions.

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

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

The description is long but highly structured and every sentence adds unique value. It front-loads the core purpose, then uses bolded labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize complex behavioral rules. No filler or redundant statements.

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 filters, output schema absent), the description covers response shapes, thresholds, edge cases, and failure signals (e.g., 'skipped_low_similarity surfaces the rejected pair count'). It even provides usage guidance for when the partition signal fires. This is as complete as needed for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description goes far beyond the schema by explaining not just what each parameter is but how the tool uses it: event slugs are resolved via walking child markets, topic seeds are expanded via search and flattened, and each mode returns different signal structures. It also provides concrete example values that illustrate the expected format.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) and contrasts with sibling tools by describing unique mechanisms and output types.

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

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

Explicit when-to-use guidance is provided: 'Call with NO args for a trending_scan', pass `event` for a specific market, or `topic` for cross-event scanning. It also gives examples of valid inputs, explains when `topic` is preferred ('catches ... patterns that single-event misses'), and directs users to `polymarket_fill_risk` for custom sizing—an explicit alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description adds significant extra context: cache behavior ('Cached 1h at the KV level keyed on all knobs'), model-family details, tradeable-edge filters, diagnostic structure, and the Fed-bet caveat. No contradiction exists; the description enriches 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 a dense wall of technical text but is front-loaded with purpose and each sentence earns its place. It could benefit from more structural formatting (bullets/sections), yet it remains information-rich 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 the tool has no output schema, the description thoroughly documents the response top-level fields, categories, diagnostics, warnings, and knob effects. It covers edge_pp_net, kelly fractions, liquidity, spread, volume, and the 24h-move warning, making it complete for a complex tool.

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

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

Although schema coverage is 100%, the description adds meaning beyond the schema. It explains how min_kelly interacts with partition opportunities, what slippage_pp assumes, and why min_partition_leg_kelly exists as a per-leg filter. These nuances directly help an agent set correct values.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly frames the use case ('what should I bet on today') and distinguishes this from sibling tools like polymarket_arbitrage or polymarket_fill_risk by emphasizing Pipeworx data disagreement and discovery without paging through markets.

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 states when to use it ('agents discover opportunities without paging hundreds of markets') and provides detailed knob guidance for filtering. However, it does not explicitly say when NOT to use this tool or name alternative sibling tools, so it falls short of the highest level.

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 behavior, but the description adds substantial detail: snapshot write-on-cache-miss behavior, 60-day TTL, decay from daily closes not intraday, expired opportunities meaning, lifespan median as 'competition clock', and signed edge_pp_net semantics (negative = SELL YES). 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 long but every sentence is dense and informative, with clear sections (Args, RESPONSE, LIMITS) and front-loaded purpose. No filler or redundancy; each detail earns its place.

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

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

There is no output schema, so the description fully shoulders the burden of explaining return values. It thoroughly describes tracked[], expired[], and snapshot_dates[] with semantics, plus limitations (TTL, snapshot start, daily-close basis). For a complex telemetry tool, this is complete.

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

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

Schema coverage is 100% — both `days` and `window` are fully described in the input schema with defaults and clamps. The description merely restates defaults ('default 14, max 30', 'default 1wk') and adds 'snapshot family' without new semantic value, so the baseline 3 applies.

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

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

The description opens with a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It explicitly frames the tool's core question ('how long has this edge existed and is it shrinking?') and contrasts fresh vs. 3-week-old edges, which clearly distinguishes it from the sibling `polymarket_edges` and other market 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 clear context for when to use the tool (historical edge persistence, distinguishing fresh vs. stale wide edges) but does not explicitly mention alternatives like `polymarket_edges` or state when not to use it. It has no exclusions, so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context: it details how the tool walks the order book, returns verdicts like 'clean|degraded|cannot_fill', and explicitly warns about 'thin_legs[]' and 'forced_directional_risk' exposing the danger of partial fills. This enriches the agent's understanding beyond the annotations.

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

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

The description is dense and uses clear structural markers (SINGLE-MARKET:, BASKET:) to organize content. Every sentence carries essential information, but the length is substantial (around 200 words) and could be tightened without losing value. Still, for a tool this complex, the detail is mostly 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?

Without an output schema, the description must explain return values, and it does: it lists all output fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and basket-specific fields). It also covers the parameter requirements and failure modes, making the description complete for a complex, dual-mode tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant meaning by explaining mode-specific semantics: market vs event as required alternatives, side defaults (including auto for basket), and size_usd interpreted as settlement notional in basket mode. While schema entries are adequate, the description clarifies usage constraints not in the schema.

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

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

The description begins with a specific verb phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk versus theoretical edge, and it explicitly names two distinct modes (single-market and basket). This makes 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 provides explicit usage instructions: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risk of partial basket fills and the dominant loss mode, effectively telling the agent when and why to use this tool over 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?

The description goes well beyond the readOnlyHint/idempotentHint annotations. It discloses detailed response behavior: leg-by-leg prices, spread array, and safety fields like compatibility_warning, temporal_alignment, and skipped_cross_type/subtype counters. It explains exactly when each warning fires and why, giving the agent complete insight into tool behavior and edge cases.

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

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

The description is long but highly information-dense, front-loading the core purpose and then systematically covering modes, response, and safety fields. While the single-paragraph format is dense, every sentence contributes critical caveats and technical detail that would otherwise be missing given the absence of an output schema. It could be split into sections, but the density is justified.

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

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

Given no output schema and a relatively complex tool, the description covers return values (leg prices, spreads), safety warnings with precise conditions, temporal alignment semantics, and skip counters. The agent is fully equipped to interpret results and understand when spreads are meaningful. No significant gaps remain.

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

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

The input schema already covers all three parameters with descriptions, so the baseline is 3. The description adds extra value by explaining the two operational modes, how the topic parameter maps to pre-mapped shortcuts, and how explicit overrides interact with the topic. This clarifies parameter selection beyond the schema's static definitions.

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

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

The description opens with a specific verb-resource pair: "Cross-venue spread between Kalshi and Polymarket for the same resolving question." It immediately distinguishes the tool from siblings by naming the two venues and the concept of spread. The two explicit modes and the response focus on matched spreads further clarify its unique 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 clearly explains when to use each mode: topic shortcuts for pre-mapped events, explicit ticker/slug for custom pairings. It also warns against assuming pre-mapped topics are tradeable, providing practical caution. It does not explicitly compare to sibling tools like polymarket_arbitrage, but the cross-venue focus is unambiguous, so the gap is minor.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining scoping (anonymous IP, BYO key hash, account ID) and the list-all-keys behavior when the key is omitted, 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?

Four sentences, each earning its place: main action, usage rationale, scoping, and tool pairing. Front-loaded with the primary purpose; slightly verbose but not wasteful.

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 tool with no output schema, the description covers purpose, usage, scoping, and related tools. An agent can confidently decide when and how to invoke it.

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

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

Schema coverage is 100%; the parameter description already covers omission to list all keys. The description adds illustrative examples (ticker, address, notes) but these are examples, not additional semantics, so baseline 3 is appropriate.

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

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

The description clearly states it retrieves a value saved via remember or lists all saved keys. It uses a specific verb ('Retrieve'), identifies the resource (memory/keys), and distinguishes from siblings by explicitly pairing with 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?

It provides clear context: use when you need previously saved context (ticker, address, research notes) without re-deriving it. It doesn't list exclusions or alternative tools, but the 'without re-deriving' implies when not to use and the pairing with remember/forget gives operational context.

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

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

The annotation readOnlyHint=true is directly contradicted by the description's disclosure that setting mark_read:true flags returned events as read, which mutates state. This is a clear contradiction between the description and annotations, so transparency must be scored 1.

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

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

The description is three sentences with no filler. The first sentence states the core purpose, the second covers return payload and filtering, the third discusses mark_read and an alternative endpoint. Every sentence carries useful 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?

The description covers return value, filtering, state behavior, and an alternative endpoint. It does not explain limit/unread_only, but those are adequately documented in the schema. The annotation contradiction is a concern, but the description itself is comprehensive for a read 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?

Although the schema documents all 5 parameters (100% coverage), the description adds contextual meaning by providing an example for type ('sec_8k'), explaining the since parameter as an ISO timestamp, and detailing the mark_read side-effect. This goes beyond the schema descriptions and enhances understanding.

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

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

The description starts with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on alerts written to the persisted feed, and it specifies the return payload (source, citation_uri, raw event payload).

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

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

The description states when to use the tool (reading alerts from the subscription feed) and provides an explicit alternative for scripts/dashboards (GET registry.pipeworx.io/alerts.json), implying agent/interactive use. It does not explicitly contrast with sibling tools, but the context is sufficiently clear about when the tool is appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds rich behavioral context: parallel fan-out to multiple sources, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail due to PatentsView sunset, and the return structure with citations. No contradiction with annotations.

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

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

Despite being longer than typical descriptions, every sentence adds value: example queries, source breakdown, `since` format, return shape, and alternative tool. The structure is logical and front-loaded with the core purpose, making it easy to scan.

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

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

For a tool with 3 params, no output schema, and multiple external data sources, the description is remarkably complete. It covers source fallbacks, failure modes, return structure, and usage caveats, leaving few ambiguities.

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 well-documented (type enum, since formats, value examples). The description adds minimal new parameter semantics beyond the schema, so the baseline of 3 is appropriate. It does not compensate for gaps because there are none.

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

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

The description clearly states the tool's function: it provides a change feed for a company over a recent time window, fanning out to SEC EDGAR, GDELT→GNews, and USPTO. It distinguishes itself from sibling tools by explicitly mentioning entity_profile for static profiles, and the core purpose is unambiguous.

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

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

The description gives explicit guidance on when to use this tool (recency-based changes) and when not to, saying 'Use entity_profile instead when you want the static profile.' It also provides context on the `since` parameter formats and fallback behaviors, helping the agent decide correctly.

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

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

The description adds behavioral context beyond the annotations, such as scoping by identifier and persistence details (authenticated vs 24-hour anonymous). It does not explicitly state overwrite behavior, but idempotentHint implies safe repetition, and no contradiction exists.

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

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

The description is concise and front-loaded with the primary purpose, then covers usage, storage, persistence, and companion tools in four sentences. Every sentence adds value with no redundancy.

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

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

For a simple key-value write tool with two parameters and no output schema, the description thoroughly covers purpose, usage, persistence, and relationships to sibling tools. No critical information is missing.

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

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

Schema coverage is 100%, so parameters are documented, but the description enriches semantics with practical examples for keys (e.g., 'subject_property', 'target_ticker') and values ('findings, addresses, preferences, notes'), going beyond the schema.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later'. It specifies the storage model (key-value pair) and distinguishes from sibling tools by naming recall 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 provides explicit when-to-use: 'Use when you discover something worth carrying forward' with concrete examples like resolved tickers and user preferences. It also instructs pairing with recall to retrieve and forget to delete, offering clear 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?

The description reveals internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, and the explicit handling of unresolved identifiers under `unresolved`. This goes well beyond the basic readOnly/idempotent annotations, providing critical behavioral context for an agent.

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

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

The description is longer than average but each sentence adds substantive information, starting with user-facing examples, then the core purpose, and then detailed per-type behavior. It is well-structured and front-loaded with immediate understanding.

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

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

Given the lack of an output schema, the description thoroughly enumerates the expected return elements (CIK/ticker, LEI with ownership, FIGI, RxCUI, etc.), failure modes, and source labeling. It also covers edge cases like unresolved identifiers and degradation, making it highly complete for a complex tool.

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

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

The input schema already fully documents both parameters, including the enum values and concrete examples for `value`. The description reinforces these semantics and adds context about output, but it does not introduce meaning beyond the schema's existing coverage.

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

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

The description explicitly states the tool resolves user-spoken names to canonical identifiers and provides a broad set of example queries ("What's the ticker for…", "find the CIK for…"). It also enumerates supported types (company and drug) and the specific identifiers returned, clearly distinguishing it from sibling tools focused on other tasks.

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 directly instructs "Use FIRST whenever you have a name but need an ID," establishing a clear trigger condition. It also clarifies the tool's efficiency by noting it replaces 2-3 manual lookups, but it does not explicitly mention when not to use it or name alternative tools, so it stops short of a perfect 5.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context by specifying the source (Datatracker) and the exact returned fields (title, status, authors, publication date, abstract), which goes beyond the annotations without contradicting them.

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

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

The description is a single, front-loaded sentence that includes the action, resource, example, and return fields. It is compact and free of 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?

The tool is simple (one parameter) and has an output schema, so the description does not need to explain return structure. It covers purpose, parameter meaning, and typical returns, making it complete for effective use.

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

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

Schema coverage is 0%, with only a 'number' property and no description. The description fully compensates by clarifying the parameter is an 'RFC number' and giving examples (9000, 2616), making the semantics immediately clear.

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 'Fetch IETF Datatracker metadata for an RFC by number' with a specific verb and resource, plus an example (9000). It distinguishes from siblings like 'wg' and 'wgs_search' by focusing specifically on RFC metadata rather than working groups.

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 implicitly indicates usage when you have an RFC number ('by number'), but it does not explicitly mention alternatives or when not to use it. This is clear context without exclusions, fitting the 'clear context, no exclusions' level.

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

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

The description discloses internal behavior: 'Probes each entity ... with ai_visibility_check, ranks by score, surfaces which is most/least recognized.' It also states the return format: 'ranked list with score, confidence, signal density per entity.' Annotations already cover readOnly/idempotent safety, so the description adds value beyond 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?

Four sentences, each adding distinct value: purpose (sentence 1), mechanism (sentence 2), use case (sentence 3), and output details (sentence 4). No fluff or repetition. The description is front-loaded with the core action.

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 no output schema, but the description explicitly states the return values: 'ranked list with score, confidence, signal density per entity.' It covers the key aspects (what, how, when) and relies on the schema for parameter constraints (e.g., 2-8 entities). It is complete for a tool of this complexity, though it could mention potential side effects like multiple API calls or rate limits.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema—it provides a real-world example of entities ('does Claude know about us as well as our competitors?') but does not explain models, _apiKey, or context in more detail than the schema already does.

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

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

The description begins with a clear, specific verb: 'Compare AI visibility across multiple entities side-by-side.' It then explains it probes each entity with ai_visibility_check and ranks by score, distinguishing it from the single-entity sibling tool ai_visibility_check. The example use case further clarifies its purpose for competitive audits.

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 for when to use it: 'Useful for competitive AI-marketing audits' with a concrete example question. It doesn't explicitly state 'use ai_visibility_check for single-entity checks,' but the contrast with the sibling tool is implied. Lacks explicit when-not-to-use guidance, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavior beyond that: it explains that partial failures degrade gracefully, that bundlephobia's first measurement can take 5-30s, and that sources_failed will list timeouts. It also reveals the fan-out architecture, which is not in annotations. This is useful context, though some latency expectations are already implied by the read-only nature.

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

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

The description is a single paragraph but well-structured, with the primary purpose front-loaded. It includes relevant details on usage, output, and failure modes. While it is longer than typical simple tools, the length is justified by the tool's complexity and every sentence carries useful information. A 5 would require even more brevity, so 4 is appropriate.

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 external services, multiple data points) and no output schema, the description is exceptionally complete. It enumerates the exact return fields (is_latest, license, published_at, advisory_count, bundle_kb_min, etc.), per-advisory details, links, alternative versions, and ecosystem limitations. It covers the 'what', 'when', and failure behavior comprehensively.

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

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

Schema coverage is 100%, so the schema already documents both parameters (package and version) with descriptions. The description adds minimal parameter-specific meaning beyond the schema, such as confirming version defaults to latest. It does not introduce new details about parameter formats or interactions, 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 uses a specific verb ('scan') and resource ('npm package dependency'), and clearly defines the purpose as a composite check for adding an npm package. It explicitly lists the data sources (deps.dev and bundlephobia) and the output summary fields, which fully distinguishes it from sibling tools like scan_competitor_ai_presence 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?

The description explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion/alternative for non-NPM ecosystems, noting that PyPI/Maven/Cargo/Go fall under deps.dev:version directly. This is clear, actionable guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds valuable behavioral detail beyond annotations: truncation at 200K chars with unflagging, the use of BGE-base-en embeddings, 500-char overlapping windows, and cosine similarity. It also explains the return payload (top-N passages with offsets and similarity scores), which is not in the schema. This fully discloses operational behavior.

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

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

The description is information-dense but every sentence earns its place: definition, use case, example, return fields, pairing with a sibling, and technical details. It is front-loaded with the core purpose and avoids redundancy with the annotations/schema. While longer than the two-sentence ideal, it packs substantial useful detail without being verbose.

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

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

The tool has no output schema, so the description must explain return values – it does ('top-N passages with character offsets and similarity scores'). It also covers the truncation behavior and embedding methodology, and it places the tool within the broader workflow (pairs with ask_pipeworx_grounded). Given the tool's moderate complexity, the description is complete enough for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context for the 'text' parameter by specifying it must be a previously fetched record (e.g., SEC 10-K body, article, long tool result). It also reiterates the character cap, reinforcing the schema's max limit. The query and limit parameters are well-defined in the schema, and the description adds examples for query. Overall, it adds value over 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 semantic search inside a fetched record, with a specific verb ('Search Within a Source') and resource. It distinguishes from siblings by emphasizing 'inside a fetched record' vs. other search tools, and it explicitly names a complementary tool (ask_pipeworx_grounded) for grounding over passages.

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 use case ('Use when the record is too big to cram into the prompt') and explains the pairing with ask_pipeworx_grounded. However, it does not explicitly mention when NOT to use it or name alternative search tools (like wgs_search) as substitutes, so it lacks a full when-not/alternatives matrix present in top-tier examples.

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 this is a non-read-only, idempotent, non-destructive operation. The description adds substantial behavioral context: OAuth requirement, phone verification for SMS, 10/day SMS cap, webhook signing secret returned only once, and auto-disable after 10 consecutive failures. No contradiction with annotations.

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

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

The description is dense but front-loaded with purpose and return value, then covers types and delivery channels. It is longer than ideal and the single-paragraph structure makes scanning harder, but every sentence carries necessary 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?

The description covers return value, authentication prerequisites, all supported types, delivery channels, limits, and webhook verification details. Even without an output schema, it provides sufficient context to invoke the tool and interpret the response. Missing enum variants are still present in the schema, so overall completeness is high.

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 enriches parameter meaning with concrete examples for sec_8k, polymarket_edge, and fred_series, plus detailed delivery channel semantics. However, it lists only three of the five enum types in prose, omitting patent_grant and clinical_trial, which slightly reduces clarity despite schema compensation.

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

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

The description begins with 'Create a proactive monitoring subscription to a live-data event stream' and states it returns the new subscription id. This clearly distinguishes the tool from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation of a persistent subscription.

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 the OAuth account requirement and that anonymous/BYO accounts cannot persist subscriptions, giving a clear when-not-to-use condition. It also points to recent_alerts or the registry feed as a pull-based alternative, providing direct usage guidance 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 establish read-only, open-world, idempotent, non-destructive behavior. The description adds behavioral context beyond annotations by noting the output is 'drawn from the live catalog of thousands of tools' (implying dynamic, current data) and that it teaches tool+argument shapes. It also advises using this as a first step, which is 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 front-loaded with example user queries, immediately making the tool's purpose relatable. Every sentence earns its place: the purpose, the output structure, the optional parameter, and the usage recommendation. At ~130 words it is dense but not bloated, and the use of em-dashes and lists aids readability.

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

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

With no output schema, the description explains what the tool returns: 'category-bucketed example questions... with the exact tool + argument shape.' It covers the full call pattern, including the optional topic parameter and the intended use as an onboarding aid. Given the tool's simple interface (one optional parameter), the description is complete and leaves no critical gaps.

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

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

The input schema already describes the `topic` parameter with its allowed focus areas and the omit behavior ('Omit for a cross-category spread'). The description only repeats examples ('finance', 'pharma', 'betting') and says 'to focus', adding no new semantic information. With 100% 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 identifies this as 'the onboarding entry point' that 'returns category-bucketed example questions... each with the exact tool + argument shape.' It distinguishes from siblings by positioning it as the FIRST tool to use when an agent doesn't know Pipeworx's capabilities, and explicitly names meta-tools (ask_pipeworx, entity_profile) as things this tool teaches how to call.

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 FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains call variants ('no arguments for the full spread, or pass topic to focus') and names alternatives via the meta-tool examples.

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 important behavioral details beyond the annotations: ownership enforcement and the deactivation (rather than deletion) behavior, which aligns with destructiveHint=false. It clarifies what happens to the data and where historical events remain available, providing richer context than the annotations alone.

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

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

The description is exceptionally concise: two sentences that front-load the core purpose and then add essential behavioral context. Every word earns its place, with no waste 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?

For a simple one-parameter tool with no output schema, the description covers all necessary context: what it does, who can use it, and the side effects on the data. The mention of recent_alerts provides a useful link to related functionality, making the description 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% and the single parameter 'id' is well-described as the subscription id returned by subscribe. The description simply says 'by id' without adding new semantic detail, so it does not exceed the baseline expected from the schema.

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

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

The description clearly states the action ('Cancel a subscription by id'), identifies the resource (subscription), and distinguishes itself from siblings like subscribe and list_subscriptions. The ownership enforcement detail further clarifies the exact scope of the operation.

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: it is for canceling subscriptions, with the important caveat that only your own subscriptions can be canceled. It also mentions that deactivation keeps historical events available via recent_alerts, implying a meaningful distinction from deletion. However, it does not explicitly name alternative tools or state when not to use it.

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

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

Beyond the readOnly/idempotent annotations, the description discloses critical behavioral nuances: the distinction between could_not_verify (check did not happen, carries verification_error, not evidence) and unsupported (no source found), the two-path execution, and the return structure (verdict, actual value with citation, reasoning). This is valuable context that annotations do not provide.

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

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

The description is lengthy but information-dense: it front-loads trigger phrases, states the core use case, explains the two routing paths, lists return values, and highlights the crucial caveats. Every sentence earns its place and the structure is logical, moving from what it does to how it behaves to important caller warnings.

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

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

Given the tool has no output schema, the description fully covers the return semantics (verdict set, actual value with citation, reasoning) and error handling (could_not_verify vs unsupported). It also explains the internal pipeline and the tool's value proposition, making it self-contained for an agent to invoke and interpret results 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 mentions 'exact percent-delta math' and tolerance behavior indirectly, but it does not add any parameter details beyond what the input schema already provides for 'claim' and 'tolerance_pct'. The description is not compensating for missing schema info.

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 claim verification tool with specific trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and a precise scope: natural-language claim verification against authoritative sources. It distinguishes itself by producing a verdict (confirmed/refuted/etc.) and being an aggregated pipeline that replaces 4–6 sequential calls, setting it apart from the broader ask_pipeworx family.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing logic (company-financial claims go to SEC EDGAR/XBRL, other claims fall through to the grounded pipeline). However, it does not explicitly name alternative tools or state when NOT to use this tool, so it lacks full 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 cover safety traits (readOnly, openWorld, idempotent, non-destructive), but the description adds no behavioral context. It doesn't state whether this is a lookup, whether it returns one or multiple entries, or any limitations. The description is purely topical and redundant with the title.

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

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

The description is extremely concise (4 words) but under-specified. It is a fragment that omits the core operation and any useful detail. Brevity without substance does not justify a higher score.

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 with an output schema present, the description is too sparse to provide adequate context. It doesn't explain what a working group is, how acronyms are resolved, or when to use this tool. The schema examples hint at IETF, but the description itself leaves the agent guessing.

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

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

With schema description coverage at 0%, the description needed to explain the 'acronym' parameter. However, it only says 'by acronym,' which is already evident from the parameter name. It does not clarify the domain (e.g., IETF working groups), expected format, or any constraints.

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 'Working group by acronym' is a noun phrase that indicates the tool concerns working groups and uses an acronym, but lacks an explicit verb (e.g., lookup, retrieve). It vaguely suggests a direct lookup but does not clearly distinguish from sibling tools like 'wgs_search'.

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?

There is no guidance on when to use this tool versus alternatives. The description does not mention any context, prerequisites, exclusions, or scenarios where another tool would be more appropriate.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds meaningful context by specifying the inclusive scope (active and concluded) and the exact data fields returned, and it mentions pagination. It does not detail default values or rate limits, but given the strong annotation coverage, the additional information is sufficient.

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

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

The description is a single, front-loaded sentence with no wasted words. Every phrase carries substantive information: scope, pagination, and return fields.

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

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

Given the low complexity (2 optional params, no nested objects), the existing output schema, and strong annotations, the description covers all necessary aspects: what is returned, the inclusivity of the list, and pagination. No significant gaps remain.

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

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

The schema has 0% description coverage, so the description must compensate. It mentions 'pagination', which implies that 'limit' and 'offset' are pagination controls, but it doesn't explain their meaning, defaults, or constraints beyond that. This is minimal compensation for two common parameters.

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

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

The description clearly states the tool lists all IETF working groups in Datatracker, specifying the scope (active and concluded) and the returned fields (acronyms, names, area, charter status). This is a specific verb+resource that distinguishes it from sibling tools like 'wg', which likely targets a single working group.

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

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

The description conveys a clear context: use for paginated listing of all working groups. However, it does not explicitly mention when not to use it or name alternative tools for specific lookups, so it stops short of full explicit exclusion guidance.

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