Httpstatus

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that the default model is free, Anthropic calls require a BYO key with direct billing, and returns per-model metrics. This provides useful context beyond annotations.

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

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

Four sentences with zero waste. The first sentence defines the core action and output, followed by model details, return format, and use cases. Information is front-loaded and 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?

Given the tool has 4 parameters, no output schema, but annotations present, the description adequately describes the return structure (per-model fields + combined view) and pricing. Minor gaps: no mention of entity scaling or limitations, but overall sufficient for agent 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 100%, so baseline is 3. The description adds value by explaining default model behavior, the function of _apiKey ('passed straight through to api.anthropic.com'), and how 'context' disambiguates entities, which is not in schema descriptions.

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

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

The description clearly states the tool probes LLMs for entity knowledge and returns a visibility score (0-100) per model. It specifies the default model and optional Anthropic probe, distinguishing it from siblings like 'scan_competitor_ai_presence' by focusing on scoring visibility across models.

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

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

The description lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to pass an API key for Anthropic probing. However, it does not explicitly compare with siblings or state when not to use this tool.

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

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

Beyond the readOnly/openWorld/idempotent annotations, it discloses that the tool routes across 5,706 tools, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and is a single fast call. No contradiction with the annotations is present.

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: it opens with the core prefer-over-web-search decision, then lists supported domains, trigger phrases, examples, and escape-hatch alternatives. Every block earns its place for a complex routing 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?

Despite having no output schema, the description tells the agent what to expect ('structured answer with stable pipeworx:// citation URIs'), what kinds of questions fit, which aliases are accepted, and when to choose sibling tools. No essential selection or invocation information is missing.

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

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

The schema fully documents the aliases at 100% coverage, setting a baseline of 3. The description adds value with concrete example questions and the semantic scope 'any factual question about real-world entities, events, or numbers', though it doesn't add deeper constraints or formatting rules beyond natural-language input.

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

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

The description states a specific role: it routes factual questions to a set of verified sources and returns structured answers with citation URIs. It also clearly distinguishes itself from web search and from siblings like ask_pipeworx_grounded and 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?

It gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'Use whenever...', 'START HERE for most questions') and when-to-step-up guidance by naming ask_pipeworx_grounded for grounded single answers and deep_research for broad multi-part questions. It even addresses breaking-news cases explicitly.

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

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

The description goes beyond the read-only/idempotent annotations by explaining that candidate routing improvements may be live, that no candidate is currently active, and that it is a fully working router with no fallback. This clearly sets expectations for experimental behavior and current parity with the stable version.

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 and front-loaded, with each sentence serving a distinct purpose: defining the beta nature, clarifying current state, and correcting the fallback misconception. Minor redundancy exists, such as repeating that it matches ask_pipeworx, but overall it remains efficient for the complexity being conveyed.

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-and-route tool, the description explains the beta behavior, current parity, experimental purpose, and relation to ask_pipeworx. It also references the response shape indirectly through 'same response shape.' A concrete example of expected output or a pointer to ask_pipeworx's full documentation would round it out, but nothing essential is missing for correct invocation.

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

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

The input schema already fully documents the 'question' parameter and all five aliases with 100% coverage. The description adds no additional parameter-level detail but confirms that arguments are identical to ask_pipeworx, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,706 tools, arguments, and response shape. It distinguishes itself by its experimental routing status and explicitly contrasts it with the stable ask_pipeworx, making its purpose and scope 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 explicitly says to use it exactly like ask_pipeworx 'when you want the newest routing' and explains that results are compared against the stable router. It does not explicitly state when not to use it or name a preferred stable alternative in negative terms, but the experimental context strongly implies the boundary.

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

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

The description adds significant behavioral detail beyond the readOnly/idempotent annotations: it lists exact refusal reasons, success return fields including evidence and confidence, and the extra LLM call cost. It also warns about data truncation and no-tool-match cases, which is useful operational context. No contradiction with annotations exists.

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

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

The description is dense but front-loaded with the core mode and purpose. The long middle section detailing return and refusal shapes is justified because there is no output schema, and the final sentence provides actionable usage guidance. It is slightly long, but every sentence contributes meaningful 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?

There is no output schema, so the description compensates by fully specifying the success and refusal return shapes, including evidence, confidence, source, and refusal reason categories. It also covers selection context, cost, and invited usage cases, making it fully sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100%, and all six parameters are documented as aliases for the single "question" input. The description implies that question is in natural language and may be routed to other tools, but it adds no parameter-level detail beyond the schema. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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

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

The description states a specific verb and resource: a "Hallucination-resistant answer mode" that "EXTRACTS the answer using ONLY what the tool result contains." It clearly identifies the tool as a grounded variant of ask_pipeworx, distinguishing it from its sibling by its extraction-only behavior.

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

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

It gives explicit use instructions: "Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts," and it names the alternative for casual cases: "prefer ask_pipeworx for casual lookups." It also explains the cost tradeoff of one extra LLM call, giving the agent clear selection criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds extensive behavioral details: market resolution, classification, fan-out, response shapes, resolver contract, edge cases (low confidence, closed markets, wide spreads), and resolution-rule risk. 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 lengthy but well-structured with clear sections and a front-loaded purpose. Every sentence adds necessary detail for correct tool invocation. Could be slightly more concise, but the density of information is justified by the tool's complexity.

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

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

The description covers all relevant aspects: input types, behavior, edge cases (low confidence, closed markets, wide spreads), parent events, news fields, and resolution rules. It is comprehensive for a research tool with no 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 covers all three parameters with descriptions. The description adds context for 'depth' (quick vs thorough, default) and 'include_raw' (when to set true). This adds value beyond the schema, but schema coverage is already 100%, so baseline is 3; the extra guidance justifies a 4.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies inputs (slug, URL, question text) and typical use cases ('should I bet on X'). However, it does not explicitly distinguish this tool from siblings like 'polymarket_edges' or 'polymarket_arbitrage', which could overlap.

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 examples and contexts (e.g., 'Use for...') and warns about low-confidence resolutions and closed markets. However, it does not provide when-not-to-use guidance or directly compare 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?

Annotations already indicate read-only, idempotent, non-destructive. Description adds specifics: for companies, it pulls latest 10-K metrics from SEC EDGAR/XBRL with correct fiscal-year handling; for drugs, it pulls FAERS and FDA trial counts. Also notes result sorting and citation URIs.

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?

Well-structured, starting with example queries then detailing functionality per type. Slightly lengthy but every sentence adds value; could be more concise but remains efficient.

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

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

No output schema, but description explains return format (paired data + citation URIs), covers both entity types thoroughly, addresses edge cases (off-calendar fiscal years), and explains sorting behavior.

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

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

Schema coverage is 100%, but description adds significant context: explains what each 'type' enum returns, gives examples for 'values' (tickers vs drug names), and notes max/min constraints beyond schema descriptions.

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

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

Clearly states side-by-side comparison of 2-5 companies or drugs in one parallel call. Provides specific user query examples ('compare X and Y', 'rank these companies') and contrasts with sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Includes example triggers and mentions sorting for 'largest/most/biggest' queries, providing clear when-to-use guidance.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive traits, lowering the burden. The description still adds substantial behavioral detail: parallel decomposition across 5,706 tools, findings packet structure, gaps[] for unanswered facets, contradictions[], hop field, citation_uri resolvability, excerpting behavior, expected latency, and account/tier constraints. 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?

Front-loaded with the critical account requirement, then the core purpose, then routing guidance, then behavioral details. It is long but most sentences carry actionable information. Some redundancy with the schema's depth parameter description slightly reduces conciseness.

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

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

Despite having no output schema, the description defines the return packet in detail: verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field, and citation_uri resolvability. It also covers auth requirements, latency expectations, and sibling-tool routing, making the tool fully usable by an agent.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description enriches the depth parameter with behavioral consequences (gap recovery, lead-chasing, contradiction scans), but this overlaps heavily with the schema text and adds little new semantic meaning beyond 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 states a specific verb and resource: grounded multi-source research across Pipeworx's 1493 structured data sources in one call. It explicitly differentiates from siblings by noting 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups.

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

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

Provides explicit when-to-use guidance: broad/multi-part structured-data questions. Gives concrete alternatives and exclusion cases: use ask_pipeworx for single lookups, for breaking/current-news topics, and when not signed in. This is unusually complete routing 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. The description adds valuable behavioral details: returns top-N tools with full schemas and curated examples, each result ready to call directly. It reinforces the non-destructive nature 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 appropriately sized and front-loaded with the purpose. It lists many domains, which adds length but is helpful for scope. Every sentence adds value, though the domain list could be slightly more concise.

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

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

Given no output schema, the description adequately explains the return format (top-N tools with schemas and examples). It covers the tool's role as a discovery gateway, though it omits details like pagination or rate limits, which are not critical for this type of 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 does not add significant meaning beyond the schema; it mentions aliases and provides example queries but largely restates what is already in the schema properties.

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: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and distinguishes from siblings by positioning itself as the first call for exploring available tools, not for answering a specific query.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available.' This provides clear context for when to use it, though it does not explicitly state when not to use it or name alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds details such as fanning out across multiple sources, soft-fail for patents after May 2025, and parallel execution. 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 somewhat long but well-structured, starting with examples and then detailing inclusions. Every sentence adds value, though minor tightening possible.

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

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

Despite no output schema, the description comprehensively lists all return fields (cik, company name, recent filings with URIs, fundamentals, patents, news, LEI). Also covers fallbacks and parameter restrictions.

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%, baseline 3. Description adds context: type only supports 'company' with more coming, value accepts ticker or zero-padded CIK. This enhances understanding beyond the schema.

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

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

The description clearly states it is a 'full cross-source profile of a US public company in ONE parallel call'. It lists the data sources and return fields, and distinguishes from sibling tools like 'resolve_entity' by specifying that names are not supported.

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 advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also provides negative guidance: 'names not supported (use resolve_entity first if you only have a name)'.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data and stale context, but doesn't conflict. No additional behavioral traits beyond annotations needed.

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

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

Two sentences, front-loaded with primary action, followed by usage guidance. 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?

Simple tool with one parameter, annotations, and no output schema. Description fully covers purpose, usage, and pairing with siblings. No further details 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?

Schema coverage 100% with one parameter 'key' described as 'Memory key to delete.' Description only says 'by key,' adding no additional semantics beyond 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?

Clearly states 'Delete a previously stored memory by key.' Verb 'delete' and resource 'memory' are specific. Distinguishes from siblings 'remember' and 'recall' by pairing statement.

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

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

Explicit usage conditions: 'when context is stale, the task is done, or you want to clear sensitive data.' Pairs with sibling tools for context.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. Description adds behavioral context: fetches the page, extracts title/description/links, emits markdown. 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?

Front-loaded with the core action, includes rational and examples in a single paragraph. No redundancy; could be slightly more terse but is well-organized.

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

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

Tool has no output schema, but description clearly states output is a text blob ready for placement. With 2 parameters and simple behavior, this covers all necessary context for an AI agent.

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

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

Schema coverage is 100%, both parameters are already well-described in the schema. Description provides slight extra context ('Full URL', 'maximum number') 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?

Description clearly states it generates a production-ready llms.txt file for any URL, listing actions (fetches, extracts, emits) and the standard output format. Differentiates from siblings as no other tool creates llms.txt.

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

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

Explicitly lists three use cases (client site indexing, own project draft, competitor audit). Lacks negative guidance (when not to use) but is otherwise clear and helpful.

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 openWorldHint, covering safety and idempotency. The description adds that it requires no authentication ('keyless') and works offline, providing useful behavioral context 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 single sentence that conveys the tool's purpose, output, and key constraints ('Keyless, offline'). Every word is necessary and efficient.

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

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

Given the tool's simplicity, no output schema, and full annotation coverage, the description completely explains what the tool does, what it returns, and its usage context. No gaps remain.

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

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

Schema coverage is 100% with a single parameter 'code' described as 'An HTTP status code, e.g. 404.' The description does not add further detail about the parameter's format or range, so the schema already provides sufficient 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 clearly states the tool looks up an HTTP status code (100-599) and returns its reason phrase, category, and meaning. It uses a specific verb ('Look up') and resource ('HTTP status code'), distinguishing it from the sibling list_http_statuses which lists all codes.

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 looking up a single status code, and notes it's keyless and offline. It indirectly differentiates from list_http_statuses, but does not explicitly state when to choose one over the other or provide exclusions.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds the filtering behavior but doesn't disclose pagination, ordering, or return format. With annotations covering safety, the contribution is adequate but minimal.

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?

Single sentence, front-loaded with the core action, and zero wasted words. It efficiently communicates the purpose and optional filtering.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is sufficient. It covers the core functionality and optional filter without requiring additional details.

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

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

Schema description coverage is 100% and includes examples and a clear description for the 'class' parameter. The tool description reiterates the filter option but adds no new semantic meaning beyond what the schema already provides.

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

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

The description clearly states the tool lists HTTP status codes and specifies an optional filter by class (1-5). This verb+resource description is specific and distinguishes it from siblings like 'http_status'.

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 explicit guidance on when to use this tool versus alternatives like 'http_status'. The description implies it's for browsing codes with optional filtering, but there is no mention of exclusions or when not to use it.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds context that it returns caller's subscriptions (not all) and the specific fields, enhancing beyond annotations.

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

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

Three concise sentences with no redundancy. First sentence covers purpose and output, second gives usage guidance.

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

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

No output schema, but description lists all return fields. Covers usage context. Minor omission of 'params' structure is acceptable for a list 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 a clear description for include_inactive. Description does not add extra parameter info, but 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?

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes from siblings like subscribe/unsubscribe and other list tools.

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

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

Explicitly advises using this to review monitoring before adding more subscriptions or to find an id to cancel. Could mention when not to use, but context is clear.

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

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

Despite annotations being all false, the description discloses the write behavior (filing returns a claim_token), the retrieval workflow via claim_token, rate limiting (5/day), and that it's free/doesn't count against quota. This goes well beyond the structured annotations and explains the full lifecycle of a feedback submission.

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 ideal but front-loaded and information-dense. Every sentence adds a distinct piece of guidance (when, what, how, limits). The roadmap and quota details, while useful, could be tightened, but the structure is logical and not bloated.

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

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

For a tool with no output schema and no required params, the description fully explains the workflow, return token mechanics, rate limits, and scope limitations. An agent can invoke it correctly and interpret the claim_token response without additional context.

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

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

The schema already covers all parameters at 100% with descriptions. The tool description adds value by explaining the claim_token lifecycle (filing generates it; later call reads status) and tying the `type` enum to real-world scenarios (bug/feature/data_gap/praise). This enhances parameter understanding beyond the schema alone.

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

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

The description opens with a clear imperative ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates concrete categories (bug, feature, data_gap, praise). This specific verb+resource framing clearly distinguishes the tool from sibling tools like ask_pipeworx or deep_research.

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

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

Explicitly states when to use ('Use when a tool returns wrong/stale data...') and provides a clear exclusion ('ONLY for tools served by this Pipeworx connection') with an alternative action ('file it with that server instead'). Also gives a disambiguation rule for identifying Pipeworx tools, making the decision boundary precise.

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

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

The description adds significant behavioral context beyond the annotations: it explains the data source ('CF analytics-engine'), guarantees no PII, describes the output structure ('pack, tool, count'), and states caching behavior ('5min-1h depending on window'). The annotations already indicate read-only and idempotent behavior, and the description fully aligns with 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 concise (three sentences) and well-structured: it leads with the core function, then lists use cases, and finally adds technical attribution and caching. Every sentence adds essential information 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?

Given the tool's simplicity (one optional parameter, no output schema), the description is fully complete. It explains the return content, derived data source, privacy guarantees, caching, and purpose in the overall agent ecosystem. No additional context is 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?

Although the schema covers 100% of the parameter with a clear description, the tool description adds value by explaining the semantic difference between window lengths: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose intelligently.

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

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

The description states precisely what the tool does: returns top tools, top packs, and total call volume over a recent window. The verb 'returns' and the specific resource list make the purpose unambiguous. It also distinguishes itself from sibling tools by focusing on aggregate usage trends of other AI agents, which is unique among the listed 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?

The description explicitly lists three concrete use cases: discovering hot data sources, confirming canonical tools before asking questions, and checking alignment with typical agent needs. This provides clear guidance on when to use this tool and why it's valuable, effectively differentiating it from alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds substantial behavioral context: scan scope (top ~200 markets), partition filter (placeholder drop), fill check against live CLOB depth, semantic anchor for cross-event pairs (Jaccard ≥0.30), and the >3pp threshold for signals. 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 very detailed but somewhat verbose, containing multiple paragraphs and technical specifics. While well-structured with inline headings and bullet points, it could be more concise to reduce cognitive load. For example, some internal processing details could be summarized.

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 thoroughly detailing the response structure and edge cases. It covers all main features: monotonicity checks, partition checks, fill check, filtering, and signals. Given the tool's complexity and lack of output schema, the description is remarkably complete.

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

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

Schema description coverage is 100% with both parameters described. The description adds extra meaning: explains acceptable event slug formats, distinguishes behavior modes, and describes response fields (gap_pp, suggested_trade, etc.) and special cases (skipped_low_similarity, placeholders_filtered). This goes beyond the schema's concise descriptions.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three modes: no args for trending scan, event for specific event slug, topic for cross-event scan. This distinguishes it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly instructs when to use each parameter mode, including recommendations (e.g., 'event recommended for a specific market'). It also advises against trading when realizable_edge_pp ≤ 0. However, it does not directly compare with sibling tools to guide choice between them.

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 extensively discloses behavioral traits beyond annotations: three model families with specific mathematical details, response structure (by_segment, diagnostics), caching policy (1h at KV level), and tradeable-edge filters. It aligns with annotations (readOnlyHint true, idempotent true) and adds significant context about what the tool computes.

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 well-structured: purpose first, then model families, response layout, knobs. Every sentence adds value, though some redundancy exists (e.g., repeating 'edge_pp_net' components). For a complex tool, the detail is justified and 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?

Given 9 parameters, no output schema, and complex logic, the description is remarkably complete. It explains the response top-level fields, diagnostics, caching, and all filter behavior. The only minor gap is lack of explicit JSON example, but field descriptions compensate adequately.

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

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

Schema coverage is 100% with each parameter documented. The description adds extra context for several knobs (e.g., min_kelly, slippage_pp, tradeable-edge filters) explaining their purpose and typical values, going beyond the schema alone. For example, it clarifies that min_partition_leg_kelly applies to per-leg Kelly inside partitions.

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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on discovery of mispricings without paging hundreds of 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?

The description gives a clear use case for daily betting opportunities and mentions agents can discover opportunities without manual paging. However, it does not explicitly state when not to use this tool or directly reference sibling alternatives for different tasks (e.g., pure arbitrage vs. edge tracking).

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?

Adds significant behavioral context beyond annotations: history bounded by 60-day TTL, decay from daily closes not intraday, gaps mean no scan. 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?

Front-loaded with purpose and response structure. Every sentence adds value, though slightly verbose on response format. Well-organized.

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

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

Thoroughly explains return fields (tracked[], expired[], snapshot_dates[]) and caveats (history limits, gaps). No output schema, so description carries full burden and does so excellently.

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

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

Schema covers 100% of parameters with descriptions. Description restates parameter info without adding new meaning; 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?

Description starts with precise verb ('edge persistence and decay telemetry') and resource ('daily polymarket_edges snapshots'). Answers a specific question ('how long has this edge existed and is it shrinking?'), clearly distinguishing from sibling tools like polymarket_edges which provide current edges.

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

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

Provides clear context ('a fresh wide edge and a 3-week-old wide edge are different trades') but does not explicitly state when not to use or name alternatives. Sibling tool polymarket_edges is implied as 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, idempotentHint, and no destructiveness. The description adds specifics: walks the order-book ladder, returns fields like top_of_book, vwap_fill_price, slippage_pp, and warns about forced directional risk. This expands on the annotation safety profile.

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 verbose but well-organized with clear section headers for SINGLE-MARKET and BASKET modes. Every sentence adds value, but some redundancy (e.g., parameter defaults repeated) could be trimmed. Still effective.

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

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

Despite no output schema, the description thoroughly documents return values for both modes, including edge cases (thin_legs, forced_directional_risk, max_clean_notional_usd). It covers the full complexity of the tool's two operational modes.

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 description adds crucial context: explains the meaning of side defaults (auto for basket), different interpretation of size_usd per mode (spend vs target proceeds vs settlement notional), and parameter interplay (market vs event exclusive). This goes well beyond schema descriptions.

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

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

The description specifies the tool's purpose as a realizable-vs-theoretical edge check against live CLOB depth. It clearly distinguishes single-market and basket modes, and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description states exactly when to use the tool: before acting on polymarket_arbitrage signals or polymarket_edges trades above $500. It explains the risks (uncapturable overround, unnhedged positions) and provides mode selection guidance via REQUIRES one of market or event.

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

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

Annotations already mark the tool read-only, open-world, idempotent, and non-destructive, and the description does not contradict any of them. It goes far beyond the annotations by detailing compatibility_warning, compatibility_codes, skipped_unclassified, low_confidence_pairs, temporal_alignment, and the counters for dropped cross-type/cross-subtype comparisons.

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

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

The description is long, but it is densely organized with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and almost every sentence carries operational value. The ending warning is slightly repetitive of the earlier compatibility_warning note, but it reinforces an important behavioral caveat.

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 present, the description carries the full burden of documenting the response, and it does so thoroughly: per-venue leg prices, top_spreads_pp, compatibility fields, temporal alignment, and skipped-comparison counters are all explained. Given the tool's complexity, nothing an agent needs to invoke it correctly or interpret its result 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 the baseline is 3, but the description adds real meaning: it explains that topic auto-fetches the matching event on each venue, and that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side for custom pairings. It stops short of giving full syntax for the explicit parameters, though the schema examples cover those.

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

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

The opening sentence names the exact deliverable — the cross-venue spread between Kalshi and Polymarket for the same resolving question — and the rest of the description defines the two modes it runs in. This is specific enough to distinguish it from Polymarket-only siblings such as polymarket_arbitrage and polymarket_edges, even without naming them.

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

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

The description clearly explains two modes — pre-mapped topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug — and tells the agent how to choose between them. It also warns that most pre-mapped topics return compatibility warnings and that pre-mapped does not mean tradeable, but it does not name alternative sibling tools or state when NOT to use this tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds scoping detail ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and explains listing behavior. 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?

Three sentences, each serving a distinct purpose: function, usage context, and scope/pairing. Front-loaded and no wasted words.

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

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

Completely describes behavior for a simple read tool. Explains both retrieval and listing modes, scoping, and pairing with sibling tools. No output schema needed as return values are clear.

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

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

Schema covers 100% of parameters with description 'Memory key to retrieve (omit to list all keys)'. Description repeats this but adds no new semantic detail 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?

Clearly states the tool 'retrieve a value previously saved via remember, or list all saved keys (omit the key argument)'. Distinguishes from sibling tools 'remember' and 'forget' by explicitly pairing with them.

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

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

Provides explicit context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' Also explains when to omit the key for listing and mentions scoping. Pairs with 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?

Annotation contradiction: tool is marked readOnlyHint=true yet the description details a side effect (mark_read:true flags events as read, modifying state). This contradicts the read-only hint.

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 cover purpose, return fields, filtering, side effect, and alternative access, with no unnecessary detail. Information is front-loaded.

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

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

Given no output schema and optional params, the description covers key return fields, filtering, and side effect. Lacks explicit mention of default ordering or edge cases, but overall adequate.

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 description adds meaningful value beyond the schema by explaining the mark_read effect and the feed context, enhancing parameter understanding.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed', distinguishing it from sibling tools that may involve searching or other actions.

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 mentions that polling works and provides an alternative endpoint for scripts/dashboards, but does not explicitly compare to siblings like 'search_within' or state 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?

Discloses fan-out behavior across multiple APIs, fallback logic (GDELT to GNews on rate limits), and soft-fail for USPTO. Describes return structure (grouped changes with counts and URIs). Adds context beyond annotations.

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

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

The description is information-dense and front-loads with intuitive examples. While relatively long, every sentence contributes essential detail. Minor redundancy could be trimmed.

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?

Covers all key aspects: data sources, parameter meaning, return structure, fallback behavior, and relationship to sibling tool. No output schema exists, but the description adequately explains return format.

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 existing descriptions. The description adds value by explaining relative shorthand for 'since', acceptable formats for 'value' (ticker or CIK), and that 'type' is currently limited to 'company'.

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: providing a change feed for a company in a specified time window. It gives example queries and explicitly distinguishes from the sibling tool 'entity_profile' for static profiles.

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

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

Provides explicit when-to-use guidance with example queries, explains data sources, and advises when to use the sibling 'entity_profile' instead. No ambiguity about context.

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

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

Annotations show idempotentHint=true and non-destructive. Description adds beyond annotations: scoped by identifier, persistence details (persistent for authenticated, 24h for anonymous). 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?

Concise 4 sentences. Each sentence adds value: purpose, usage, storage details, pairing. Front-loaded with core action. No unnecessary words.

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

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

For a write tool with no output schema, description covers purpose, usage, storage mechanics, pairing with siblings. Complete for 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?

Schema coverage 100% with clear param descriptions. Description adds context: 'any text' for value, example key patterns like 'subject_property'. Enhances understanding of what to store.

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?

Explicitly states the tool saves data for reuse, with verb 'save' and resource 'data'. Clearly distinguishes from sibling tools like 'recall' and 'forget' by focusing on storing key-value pairs.

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: 'when you discover something worth carrying forward'. Suggests pairing with recall and forget, and mentions persistence rules for different session types.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it explains that unresolved identifiers are explicitly listed under 'unresolved' rather than omitted, that LEI/FIGI enrichment degrades gracefully, and that each call internally cascades through multiple endpoints. This gives the agent insight into edge cases and performance expectations.

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

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

The description is long and dense, yet every sentence contributes unique information. The opening list of example queries is somewhat redundant but serves to illustrate varied phrasings. The structure clearly separates core purpose, usage directive, and detailed type-specific behavior, making it easy to parse despite its length. It earns a high score, but not a perfect one due to slight over-elaboration.

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, multiple data sources, fallback behavior, and return formats), the description is remarkably complete. It explains what identifiers are returned, how sources are labeled, what happens when enrichment fails, and even provides a sample citation URI for drugs. No output schema exists, so the description fully carries the explanatory burden, and it succeeds.

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 code schema already covers both parameters with 100% description coverage, but the tool description significantly enriches this by detailing accepted input formats for 'value' (ticker, CIK, ISIN, or name for company; brand/generic for drug) and explaining special cases like ISIN resolving to legal entity via GLEIF. This goes far beyond the schema's basic descriptions.

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

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

The description opens with concrete example queries and states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes from siblings like entity_profile by focusing on name-to-ID resolution, not profile lookup. The supported types and their outputs are explicit, leaving no ambiguity.

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

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

The description gives a strong usage directive: 'Use FIRST whenever you have a name but need an ID.' It also implies when not to use (when you already have the ID), but it does not explicitly name alternative tools or provide when-not scenarios. The many query examples help an agent recognize when to invoke this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context: probes each entity with ai_visibility_check, ranks, and returns a ranked list with score, confidence, signal density. 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?

Two sentences, no waste. Front-loaded with the core purpose. Every phrase adds value.

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

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

No output schema, but description explicitly states return format: ranked list with score, confidence, signal density per entity. Parameters fully covered by schema. Complete for a comparative analysis tool.

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

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

Schema description coverage is 100%, so parameters are already well-documented. Description adds only minor context (first entity treated as subject). 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?

Clearly states it compares AI visibility across multiple entities side-by-side, ranks by score, and surfaces most/least recognized. Distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (more general) by specifying the AI-presence focus.

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

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

Explicitly says 'Useful for competitive AI-marketing audits' and gives an example question. Clearly indicates when to use. Could mention when not to use (e.g., single entity would use ai_visibility_check), but current guidance is sufficient.

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

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

Annotations already declare read-only, open-world, idempotent. The description adds critical behavioral details: partial failures, bundlephobia timeout (5-30s), and the sources_failed field. 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?

Single paragraph but well-organized, front-loaded with key purpose and usage. Could be slightly more concise, but each sentence adds necessary context.

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?

Output schema is absent, but the description thoroughly lists all return fields (summary block, per-advisory details, links, recent versions). Covers partial failure behavior, making the tool's output fully predictable.

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. The description adds value by noting scoped packages are accepted and default version behavior, which goes beyond 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?

Clearly defines the tool as a composite check for npm packages, covering license, security, and size. Distinguishes from siblings by specifying NPM-only in v1 and referencing deps.dev:version for other ecosystems.

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

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

Explicitly states when to use: when an agent asks about safety, popularity, or size of an npm package. Also provides constraints and alternatives (non-NPM packages should use deps.dev:version directly).

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds significant technical context: uses BGE-base-en embeddings with cosine similarity, 500-character overlapping windows, a 200K character cap with truncation, and that results include offsets and similarity scores. No contradiction with annotations; these details help the agent understand behavior beyond safety.

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 of about six sentences, each serving a distinct purpose: purpose, usage scenario, technical details, pairing, and algorithm specifics. No fluff or repetition. Front-loads key information.

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

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

Given the moderate complexity and rich annotations/schema, the description covers input, output (passages with offsets and scores), limitations (200K cap, truncation), and pairing with a sibling. No output schema exists, but return structure is described adequately. Could mention handling of no matches, but overall complete enough for effective invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing natural-language example queries for the 'query' parameter and stating the text character cap. The 'limit' parameter's default and range are not repeated but the schema already handles that. Overall, it augments the schema meaningfully.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes itself from the sibling tool 'ask_pipeworx_grounded' by explaining that this tool retrieves passages while the other grounds over them. The purpose is explicit and 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 explicitly says 'Use when the record is too big to cram into the prompt', providing clear guidance. It also recommends pairing with 'ask_pipeworx_grounded' for grounding. While it doesn't explicitly say when NOT to use, the guidance is strong and actionable.

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

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

Adds details beyond annotations: OAuth requirement, one-time webhook signing secret, SMS phone verification, auto-disable after 10 failures. Annotations already indicate idempotent, not read-only, not destructive; description fills in operational specifics.

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?

Well-structured with front-loaded purpose, prerequisites, then type and delivery details. Somewhat lengthy but justified by the complexity of the 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?

Covers inputs, return value, and key behaviors. No output schema, but description gives enough for an agent to invoke correctly. Missing error or duplicate-handling info, but idempotentHint partially addresses that.

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 has 100% coverage, but description adds meaningful context for each parameter, especially concrete examples for all subscription types and operational notes for delivery (e.g., webhook HMAC, SMS cap).

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. Distinguishes from sibling tools like 'unsubscribe', 'list_subscriptions', and 'recent_alerts' by focusing on creation.

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

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

Provides prerequisites (Pipeworx OAuth account), supported types with examples, and delivery channel options. Doesn't explicitly contrast with siblings but gives clear context for when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns category-bucketed example questions with tool+argument shapes, and that it's safe to call with no arguments. This adds useful behavioral context without contradiction.

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

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

The description is front-loaded with user-style questions and well-structured. While slightly wordy, every sentence contributes value. It could be trimmed slightly but remains effective.

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 low-complexity discovery tool with one optional parameter and no output schema, the description fully covers when to use it, what it returns, and how to customize. No gaps.

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

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

Schema coverage is 100% (one optional parameter). The description adds meaning by specifying possible topic values ('finance, pharma, economics, ...') and the behavior when omitted (full spread).

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

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

The description clearly states the tool is an onboarding entry point for discovering what Pipeworx can do, returning categorized example questions. It distinguishes from siblings like ask_pipeworx by specifying it's for initial orientation.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also mentions optional topic filtering and provides examples of topics.

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

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

Discloses ownership enforcement and soft-delete behavior (deactivated, not deleted), adding value beyond annotations that show non-destructive and idempotent.

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

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

Two sentences, no fluff, front-loaded with action and constraint.

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?

Simple tool with one required param and no output schema; description covers purpose, constraint, and behavior sufficiently.

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?

Only one parameter with full schema coverage; description merely says 'by id' without adding extra meaning beyond 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?

Clear verb 'cancel' with resource 'subscription'. Distinct from siblings like subscribe and list_subscriptions.

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

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

States ownership constraint and that the row is deactivated not deleted, but does not explicitly mention when to use vs alternatives.

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

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

Despite annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds substantial behavioral context: the two execution paths (SEC EDGAR vs. grounded pipeline), the list of possible verdicts, the special meaning of 'could_not_verify' (error, not evidence) and 'unsupported' (no source coverage), and the presence of verification_error{stage,detail}. This goes well beyond the annotation baseline.

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

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

The description is long but dense, with all sentences contributing behavioral guidance or scope. It opens with user-phrase examples, then gives the primary use case, routing details, return value structure, and critical caveats. It is structured and front-loaded, though slightly verbose—but the length is justified by the tool's complexity.

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

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

Given the lack of an output schema, the description thoroughly covers the return format (verdict list, actual value with citation, reasoning) and the critical semantics of failure states. It also explains the internal pipeline and why the tool replaces multiple sequential calls. No major gaps remain for an agent to use it correctly.

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

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

Schema description coverage is 100% with good parameter descriptions, so the baseline is 3. The tool description adds extra value by explaining how tolerance_pct overrides the default and recommending values for hallucination detection, and by providing example claims that clarify the expected format. This exceeds the schema baseline.

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

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

The description clearly identifies the tool as a natural-language claim verification function with specific trigger phrases ('fact check', 'verify the claim that…'), and states it returns a verdict against authoritative sources. It distinguishes itself from sibling tools by focusing on factual claim checking rather than general research or entity lookup.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing logic: company-financial claims use the SEC EDGAR fast path, while other claims fall through to the grounded pipeline. It also notes the tool replaces 4–6 sequential calls, providing clear context. However, it does not name a specific alternative tool for 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.