Seo Keywords Ads

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

Annotations (readOnlyHint, idempotentHint, destructiveHint=false) are consistent. Description adds critical behavioral details: default model, BYO key for Anthropic (direct payments), and return structure. No contradictions; the description enriches the annotation context.

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

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

Description is front-loaded with core purpose and score range. All three main sentences add distinct value (purpose, model choice, return format). Slightly verbose with example details, but each sentence earns its place.

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

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

No output schema, but description clearly states return fields per model and combined view. All parameters are explained with examples. Use cases are provided. Sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and description adds meaning: identifies default model, explains `_apiKey` necessity for Anthropic, and gives examples for `entity` and `context`. This goes beyond the bare 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?

Describes a specific action ('probe', 'score visibility') on a clear resource (LLMs' knowledge of entities). Differentiates from siblings like scan_competitor_ai_presence and bet_research by focusing on AI visibility scoring per model with a 0-100 score.

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 use cases (AI-marketing audits, pre-launch checks, competitive monitoring). Explains when to include Anthropic (using `_apiKey`) and when to omit for just the free model. Lacks explicit when-not-to-use guidance, but context signals and sibling names imply 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, and destructiveHint=false. The description adds valuable behavior beyond these: routes to one of 5,706 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is one fast call. It does not cover failure modes or rate limits, but the added context is meaningful.

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

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

The description is long but information-dense, with the core preference front-loaded and escalation guidance clearly separated. Some redundancy exists ('START HERE', 'default entry point', 'works on every tier', 'one fast call' all appear in one sentence), but the length is justified for a router tool that needs extensive 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?

For a complex router tool with no output schema, the description covers scope, examples, return format (structured answer with citation URIs), tier behavior, and alternative tools. It does not explain the exact structure of the response, but it provides enough for an agent to decide when to call and roughly what to expect.

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

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

Schema description coverage is 100%: the only required parameter, 'question', is fully documented and aliases are listed in the schema. The description adds no extra parameter-level details beyond the schema, but it does provide real-world example queries that help an agent formulate inputs. Baseline 3 is appropriate since the schema already carries the semantic load.

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

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

The description clearly states a specific verb ('PREFER OVER WEB SEARCH', 'routes the question', 'returns the structured answer') and a resource (5,706 tools across 1,493 verified sources). It differentiates itself from siblings, notably ask_pipeworx_grounded and deep_research, by positioning itself as the default entry point.

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

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

Explicitly provides when to use ('Use whenever the user asks...'), when not to ('Step up only when needed'), and alternatives ('ask_pipeworx_grounded', 'deep_research'). It also handles the edge case of breaking news by noting ask_pipeworx already routes to live news. This is exemplary 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals that candidate routing improvements may be enabled live, that none are active right now, and that this is a full working router rather than a fallback stub. It also explains the experimental comparison process, which is valuable behavioral context for an agent deciding whether to use this variant.

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

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

The description is four sentences long but densely packed: it establishes identity, parity, experimental state, and usage. Each sentence adds value, and there's no repetition of schema facts. It could be tightened slightly, but it's well-structured and front-loaded.

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

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

The description covers purpose, parity with ask_pipeworx, current experimental state, and usage. Since there is no output schema, it relies on 'same response shape' to reference the stable sibling, which is adequate given the sibling context. It doesn't spell out the full return format, but it is complete enough for confident 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 documents all six parameters with 100% coverage, including the question field and five aliases. The description only says 'same arguments' and adds no per-parameter meaning, so it sits at the baseline of 3 where the schema carries the load.

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

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

The description explicitly identifies the tool as a beta of ask_pipeworx, a universal router over 5,706 tools, and distinguishes it from the stable ask_pipeworx by its experimental routing edge. It clearly states the resource and function, making it easy for an agent to understand what it does and how it differs from siblings.

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

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

It directly instructs the agent to use it exactly like ask_pipeworx when the newest routing is desired, and notes that results are compared against the stable router. This is explicit when-to-use guidance with an obvious alternative, leaving no inference required.

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

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

The description discloses rich behavioral detail beyond the annotations: it names the exact success return shape, enumerates all refusal_reason values, states that only the tool result is used, and warns about the extra LLM call cost. This far exceeds what the annotations alone convey.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, return contract, refusal modes, usage criteria, and cost tradeoff. The key message is front-loaded in the first sentence, and the rest provides essential operational detail.

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

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

Although there is no output schema, the description fully specifies the success and error return shapes, including the refusal_reason enum. It also covers cost, when to use an alternative, and the grounding behavior, making it complete for an agent to invoke correctly.

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

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

The input schema fully documents the question parameter and all five aliases with 100% coverage, so the description does not need to add parameter details. The description focuses on behavior and usage rather than parameter semantics, which is acceptable given the schema completeness.

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

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

The description clearly identifies this as a hallucination-resistant, grounded answer mode that extracts answers only from tool results, and explicitly contrasts it with ask_pipeworx. This gives an agent a precise understanding of the tool's distinct role and differentiates it from its closest sibling.

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

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

The description explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when to avoid it ('prefer ask_pipeworx for casual lookups'). This is exactly the kind of decision guidance an agent needs.

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 details behavior beyond annotations: resolution process, classifier fan-out, response shapes (market_match_confidence, parent_event, news fields with fallback), safety mechanisms (low-confidence, closed markets, wide spreads), and resolution-rule risk. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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 comprehensive but verbose, containing many details. While front-loaded with purpose and examples, later sections are dense and could be more concise. The length is justified by complexity but could be tightened.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete. It covers input types, resolution behavior, response fields (market, analysis, evidence), safety checks, and edge cases. No critical gaps for agent usage.

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

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

Input schema covers all parameters with descriptions (100% coverage). The description adds value by explaining market can be slug, URL, or question; depth defaults to 'thorough'; include_raw default false with rationale. This enriches understanding beyond schema alone, earning a 4.

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

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

The description clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). Examples and classifier list further clarify purpose, distinguishing it from 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 provides explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives examples of when to use (e.g., 'BTC bet → coingecko + fred...'). However, it does not explicitly state when not to use or compare alternatives, though sibling tools imply 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. The description adds significant behavioral context: data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. No contradictions with annotations.

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

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

The description is moderately concise at 4 sentences, but it packs extensive detail (data sources, sorting, return format) without redundancy. It could be tightened slightly, but the front-loaded examples and clear structure make it easy to parse.

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

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

Given the complexity (two entity types, multiple data sources) and absence of an output schema, the description adequately explains return values (paired data + citation URIs). It also justifies efficiency ('replaces 8–15 sequential lookups'), which helps the agent weigh tool selection.

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

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

Schema coverage is 100% (both parameters documented). The description enriches this by providing concrete examples (e.g., ['AAPL','MSFT'] for companies), constraints (min 2 max 5), and clarifying that for drugs, names (not tickers) are expected. This adds value 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 clearly defines the tool's purpose: side-by-side comparison of 2–5 companies or drugs. It uses specific verbs ('compare,' 'rank,' 'head to head') and explicitly distinguishes from sequential single-entity lookups. Examples of user queries (e.g., 'which is bigger,' 'X vs Y') further clarify the intent.

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 tool provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It states when to use (comparison queries) and what each type returns (company vs drug). No need for alternatives beyond this strong directive.

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

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

Beyond the annotations, the description discloses substantial behavioral traits: account sign-in required, paid plan for 'thorough', latency expectations (15-60s, up to ~90s), gap recovery and contradiction scanning per depth, the guarantee that gaps[] are never invented, and that citation_uri are always resolvable. It also clarifies semantic excerpting instead of head-truncation, which materially affects how results should be interpreted.

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

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

The description is long but every sentence contributes a distinct operational fact: account requirements, alternatives, decomposition behavior, return packet contents, depth semantics, citation reliability, and latency. It is logically organized from prerequisites to use cases to advanced behavior, though it could be tightened slightly by moving the account note to a dedicated line.

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, no output schema, and rich parameter semantics, the description is remarkably complete. It covers return value shape (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field), auth requirements, latency, and caveats like news topic gaps. An agent has enough information to select and invoke the tool correctly without further inference.

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

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

Schema coverage is 100% and both parameters are documented in the schema. The description adds meaningful value by explaining what 'depth' values actually do (quick=3 single hop, standard=3 with gap recovery, thorough=6 paid with iterative hop and contradictions scan) and by clarifying that 'question' can be broad/multi-part because decomposition is the point. This exceeds the baseline of 3.

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: it 'decomposes your question into focused facets, routes each to the right one of 5,706 tools IN PARALLEL' and 'returns a findings packet' across structured data sources. It explicitly contrasts itself with ask_pipeworx and notes this is NOT open-web search, making sibling differentiation clear.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data,' and provides exclusions such as 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also warns of account requirements and which depth tier needs a paid plan, so an agent knows prerequisites and alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly,' which goes 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, clean paragraph with front-loaded purpose, followed by usage and output details. Every sentence is valuable, no redundancy.

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

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

For a meta-tool with 6 parameters and no output schema, the description is complete: it explains what it does, when to use it, examples, and what it returns (tools with schemas ready to call). 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% with descriptions for all 6 parameters. The description explains the main 'query' parameter, gives examples, and mentions alias parameters (task, q, description, search), adding meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many specific domains and distinguishes itself from sibling tools by positioning as a meta-discovery tool to be used first.

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 'Call this FIRST when you have many tools available.' It provides clear context but does not explicitly mention when not to use it or list alternatives, though sibling tools are implied as 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 read-only, open-world, idempotent, non-destructive behavior. The description adds value by disclosing the USPTO API sunset (soft-fail), parallel fan-out, and specific return fields. It also clarifies that only 'company' type is supported, with person/place coming soon.

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

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

The description is long but well-organized, starting with example queries and usage preference, then detailing data sources and return fields. It is front-loaded with key info, though some 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?

Given no output schema, the description effectively explains return structure (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It addresses the USPTO limitation and value format requirements. Minor gap: error handling beyond soft-fail not described.

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

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

With 100% schema coverage, baseline is 3. The description enhances by explaining the type parameter accepts only 'company', the value parameter expects ticker or zero-padded CIK (not names), and provides examples. This adds meaning beyond the schema descriptions.

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

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

The description clearly states it provides a full cross-source profile of a US public company, with specific example queries and a detailed list of data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF). It distinguishes itself from siblings like resolve_entity by noting when to use which tool.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view,' and advises using resolve_entity first if only a name is available. This gives clear when-to-use and when-to-avoid guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds 'Delete' which is consistent but does not elaborate on behavior like what happens if the key does not exist. Adds minimal 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?

Two concise sentences, no fluff. First sentence states purpose, second gives usage context and sibling reference. Every sentence earns its place.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage guidelines, and sibling relationships. Slightly lacks explicit handling of edge cases like missing key, but overall complete enough.

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

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

Schema coverage is 100% and the schema describes the parameter. The description does not add extra meaning beyond 'by key', which is already implied. Baseline score of 3 applies.

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

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

The description starts with a clear verb and resource: 'Delete a previously stored memory by key.' It distinguishes from siblings by mentioning 'remember' and 'recall'.

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

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

The description explicitly states when to use ('context is stale, task is done, or clear sensitive data') and how it pairs with other tools ('Pair with remember and recall'). No exclusions but clear enough.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by detailing internal behavior: fetches page, extracts title/description/links, and outputs standard llms.txt markdown. 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 two sentences: first defines purpose and output, second explains internal steps and use cases. Every sentence adds value, no fluff, well 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 high schema coverage, no output schema, and informative annotations, the description is complete. It explains what the tool does, how it works, output format, and real-world use cases. 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% with descriptions for both 'url' and 'max_links'. The description does not add significant detail beyond the schema, e.g., it mentions 'max_links' but not default/max values already in schema. Baseline 3 due to high coverage.

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

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

The description uses a specific verb 'Generate' and resource 'llms.txt file', clearly stating the tool's purpose. It distinguishes itself from sibling tools by focusing on generating llms.txt for AI crawlers, unlike similar tools like 'scan_competitor_ai_presence' or 'ai_visibility_check'.

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

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

The description lists explicit use cases: getting a client's site indexed, drafting own llms.txt, or auditing competitors. It does not explicitly state when not to use it or compare to alternatives, but the use cases are clear and 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, idempotent, and non-destructive. Description adds the return fields but no new behavioral traits beyond what annotations cover.

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

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

Two succinct sentences with no unnecessary words. Purpose, usage, and return fields are presented in a compact, front-loaded manner.

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

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

For a simple list tool with one optional parameter and no output schema, the description provides all necessary information: what it returns, when to use it, and the parameter's effect.

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 single parameter is fully described in the input schema (100% coverage). Description does not add further information about the parameter's usage or format.

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

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

Clearly states it lists the caller's active subscriptions and enumerates returned fields (id, type, params, timestamps, fire_count). Differentiates from sibling tools like subscribe and unsubscribe.

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

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

Explicitly recommends using this tool to review subscriptions before adding more or to find an id to cancel. Provides clear context but stops short of stating 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 are all false (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), providing no safety context, so the description carries the full burden. It discloses the claim_token workflow (returns token, can be passed back later to read status), rate limiting (5 per identifier per day), that it's free and doesn't count against quota, and that the team reads digests daily. It also instructs to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, adding significant behavioral context.

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

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

The description is long but dense; every sentence serves a purpose. It is logically structured: what the tool does, when to use, exclusions, token mechanics, rate limits, and free/quota note. A slight deduction because it could be tightened (e.g., the opening is a bit repetitive with the later type list), but it remains efficient and front-loaded.

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

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

For a feedback tool with 4 parameters and no output schema, the description covers all necessary aspects: acceptable feedback types, what to include in messages, the claim_token retrieval flow, rate limits, and alternatives for non-Pipeworx tools. It gives the agent enough to use the tool correctly without requiring additional documentation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the claim_token flow: 'Filing without an account returns a `claim_token`; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed.' This contextualizes the parameter's purpose and usage pattern, which is not fully captured in the schema's short description.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and the action (sending feedback), and lists distinct feedback types (bug, feature, data_gap, praise). This distinguishes it from sibling tools, which are research/query tools, by focusing on reporting issues to the team.

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

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

Explicit when-to-use guidance is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives clear exclusions: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This tells the agent when not to use it and mentions an alternative (file with the other server).

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 as readOnly and idempotent; description adds caching duration, data source (CF analytics), and no PII — 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?

Two sentences plus bullet points, no waste. Front-loaded with purpose.

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 shape (top tools, packs, volume) sufficiently. 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 describes window enum 100%. Description adds semantic guidance: shorter windows for hot topics, longer for steady-state demand.

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 returns top tools, packs, and call volume, distinguishing from sibling tools like discover_tools or ask_pipeworx. Verb 'returns' + resource = specific scope.

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

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

Explicitly lists three use cases (discovery, confirmation, alignment). Does not mention when not to use, but the context is clear enough.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds extensive behavioral details: scanning logic, Jaccard similarity threshold (≥0.30), placeholders filter (>20% placeholder fraction null), fill check against live CLOB depth, and return fields. 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 detailed and well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). While slightly verbose, every sentence adds necessary operational context. The front-loading of core purpose is effective, making the tool's primary function immediately clear.

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

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

Given no output schema, the description fully compensates by specifying the return format: opportunities[] with fields like gap_pp, suggested_trade, reasoning. It also covers edge cases (placeholders, similarity threshold, thin legs) and provides actionable trading guidance. No missing critical information for invocation.

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

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

Schema coverage is 100% with descriptions for both 'event' and 'topic'. The description adds context beyond schemas, e.g., 'Full Polymarket URLs also accepted' for event, and explanation of cross-event search for topic. It clarifies the difference between the two parameters, which is valuable for correct invocation.

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 arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes this tool from siblings like polymarket_edges and polymarket_fill_risk by focusing specifically on arbitrage detection with detailed operational modes (trending_scan, event, topic).

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

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

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also references an alternative tool: 'For custom sizing use polymarket_fill_risk.' Provides cautionary advice on not trading when realizable_edge_pp ≤ 0.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses significant behavioral details: caching at KV level for 1h, response structure with diagnostic counters, model families and their calculations, and the unreliability of fed signals. 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 verbose but well-structured: front-loaded purpose, then segments, model families, knobs, response structure. Every sentence adds value, but it could be more concise. Given the complexity, it's acceptable.

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 response structure is thoroughly described: top-level segments, edge metadata, and diagnostics explaining why segments might be empty. The description covers caching, knob effects, and fed candidate exclusion, making it fully actionable for an agent.

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

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

Schema coverage is 100%, and the description adds deep context for each parameter: e.g., min_kelly explains half-Kelly fraction with example, slippage_pp discusses typical slippage and adjustments, and min_partition_leg_kelly clarifies its behavior for partition arbs. This far exceeds the schema descriptions.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the resource (Polymarket markets) and action (scan and return opportunities), distinguishing it from siblings like polymarket_arbitrage through detailed model family descriptions.

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

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

The description is built for 'what should I bet on today' and provides guidance on tradeable-edge knobs and conditions for empty segments. However, it lacks explicit when-not-to-use or alternative tool comparisons, relying on implied usage context.

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

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

Annotations declare read-only, idempotent, safe. Description adds substantial behavioral context: daily snapshots, not intraday, decay from closes, snapshot gaps, history bounds, response structure. 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?

Relatively long (~150 words) covering purpose, response, and limits. Front-loaded but could be trimmed; adequate but not excellent.

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?

Explains return values (tracked, expired, snapshot_dates) and limits despite no output schema. Missing error handling or edge cases, but sufficient for a read-only telemetry tool.

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

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

Schema covers both parameters with defaults and constraints. Description briefly repeats but adds no significant new meaning; baseline 3 is appropriate for 100% schema coverage.

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

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

States it provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge aging. Implicitly distinguishes from sibling tools like polymarket_edges by focusing on time-series analysis.

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?

Implies usage for historical edge analysis but does not explicitly state when to avoid or provide alternatives. No comparison to sibling tools like polymarket_edges for current edges.

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 declare readOnlyHint=true, idempotentHint=true, etc. The description adds behavioral details: walks order book ladder, returns specific metrics (slippage, fillability, verdict), and warns of risks like forced directional risk. 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?

Description is long but well-structured using capitalization and line breaks to separate modes. Every sentence adds value given the complexity. Could be slightly more concise, but appropriate for the depth of 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?

No output schema, but description thoroughly enumerates all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, etc.). Complete for an AI agent to understand 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 description coverage is 100%, baseline 3. The description adds significant context: explains side defaults (auto in basket), size_usd interpretation (max spend vs target proceeds, settlement notional), and clamps. This 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?

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, lists outputs, and specifies when to use it (before acting on arbitrage signals or trades above $500). This is highly specific and differentiates from siblings.

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

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

Explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable, partial fills convert arb into unhedged positions). This is exemplary.

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 only declare the tool read-only, open-world, idempotent, and non-destructive. The description goes far beyond that by explaining compatibility_warning and compatibility_codes[] semantics, the never-pair rule for unknown metric types, skipped_unclassified and low_confidence_pairs, temporal_alignment, and per-pair flags—all critical behaviors an agent needs.

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 and well-organized: purpose, modes, response shape, safety fields, codes, and caveats are presented in order. Every section earns its place given the tool's complexity and the absence of an output schema, though it is close to the upper limit of acceptable length.

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

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

With no output schema, the description carries the full burden of explaining return semantics. It covers matched_pairs, top_spreads_pp, compatibility fields, skipped counts, low_confidence_pairs, and temporal alignment, and it warns about the reliability gap in pre-mapped topics. An agent has enough context to invoke the tool and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real operational meaning: topic mode auto-fetches matching events via pre-mapped shortcuts, explicit ticker/slug mode enables custom pairings, and topic-mode results are always premapped_pairing_unverified. This goes beyond the schema's parameter 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 first sentence states an exact verb and resource: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. This clearly separates it from same-venue tools like polymarket_arbitrage and from generic entity comparison tools like compare_entities.

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

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

The description explains two concrete modes—topic shortcuts with an explicit list, and explicit ticker/slug pairings—and gives strong context about when results are not tradeable. It does not explicitly name sibling alternatives or state 'use X instead', but the venue-specific framing and mode guidance are enough for an agent to decide correctly.

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

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

Annotations already indicate read-only and idempotent; description adds scoping detail (by identifier) and pairing with remember/forget, 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?

Three sentences efficiently convey purpose, usage, scoping, and relationships without extraneous 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 simple input and annotations, the description fully covers behavior, scoping, and integration with sibling tools.

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%; description adds clarity on omitting key to list all keys, which aids 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 the tool retrieves a saved value or lists all keys, matching the verb 'recall' and distinguishing from siblings like 'remember' and 'forget'.

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

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

Provides context for when to use (look up stored context) and mentions omitting key for listing, but does not explicitly mention when not to use 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?

Adds key behavioral detail: mark_read:true affects subsequent calls by flagging events as read. Discloses idempotent read-only nature consistent with annotations (readOnlyHint, idempotentHint, destructiveHint=false). 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?

Relatively concise at ~80 words, front-loaded with purpose and key actions. The note about the REST endpoint adds value but slightly lengthens the description.

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 essential aspects (purpose, parameters, behavior, alternative access). With no output schema, it describes return fields adequately. Parameters are well-explained.

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 context: mark_read affects next call, since expects ISO timestamp, and implies filtering use. This 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 it 'Pull fired events from your subscription feed' and lists returned fields (source, citation_uri, payload), distinguishing it from sibling tools like list_subscriptions or subscribe.

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 usage context: filtering by type and since, mark_read behavior, and notes that polling works and the same feed is available via a REST endpoint. However, it does not explicitly state when not to use this tool versus siblings.

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

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

Beyond annotations (readOnlyHint, etc.), the description discloses multi-source fan-out, fallback logic, USPTO soft-fail due to API sunset, parameter format details (ISO date vs. relative shorthand), and return structure (changes grouped by source, total_changes, pipeworx URIs). No contradictions with annotations.

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

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

The description is dense but well-structured, starting with example queries and then technical details. Every sentence adds value, though slightly verbose for a tool with extensive annotations.

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

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

Given the tool's complexity (multiple sources, fallback, no output schema), the description covers all essential behavioral aspects, return format, and edge cases like USPTO soft-fail, making it complete.

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

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

Schema coverage is 100%, but the description adds meaning: 'type' limited to company, 'since' explains ISO vs. relative with typical values ('30d', '1m'), 'value' example of ticker or CIK. This goes 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 explicitly states the tool provides a change feed for a company in a date window, listing multiple data sources (SEC, GDELT/GNews, USPTO) and example queries. It distinguishes from the sibling 'entity_profile' tool, making purpose very clear.

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

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

The description gives explicit guidance on when to use this tool vs. 'entity_profile' for static profiles. It also provides typical usage examples for the 'since' parameter and clarifies the fallback behavior between GDELT and GNews.

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 provide idempotentHint=true and destructiveHint=false. Description adds scope (by agent identifier) and persistence details (authenticated vs 24-hour 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?

Front-loaded with purpose. Four sentences, each informative and efficient. 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?

Tool is simple with 2 required string params and no output schema. Description covers purpose, usage, persistence, and companion tools, making it complete.

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

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

Schema coverage is 100% with clear descriptions. Description does not add additional meaning beyond the schema, so 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?

Clearly states the tool saves data for reuse across conversations/sessions. Provides specific examples (resolved ticker, target address, user preference). Distinguishes from siblings like recall and forget.

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

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

Explicitly describes when to use (discovering something worth carrying forward) and mentions companion tools (recall, forget). Lacks explicit when-not to use scenarios, but context is strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context beyond annotations, including source labeling, explicit `unresolved` reporting, graceful degradation when GLEIF/OpenFIGI are unavailable, and the internal cascade across lookup endpoints. 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 information-dense and front-loaded with natural language examples, making it easy to parse. However, it is somewhat long (about 200 words) and includes multiple parenthetical clarifications that could be trimmed without losing meaning. Still, every sentence contributes 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?

With no output schema, the description must explain return values, and it does thoroughly: canonical identifiers for each type, source labeling, explicit `unresolved` elements, and fallback behavior. It is complete for both supported entity types and covers edge cases like non-US issuers and degraded enrichment.

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

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

Schema coverage is 100%, but the description adds significant parameter semantics beyond the schema. It explains accepted input formats for company (ticker, CIK, ISIN, or name), details the ISIN-to-LEI mapping for non-US issuers, and for drug specifies RxCUI plus ingredient/brand from RxNorm. This enriches the schema's basic property definitions.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers. It uses specific verbs like 'resolve', 'find', and 'look up', and distinguishes itself from sibling tools by explicitly saying to 'Use FIRST whenever you have a name but need an ID.'

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

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

The description provides clear usage context: 'Use FIRST whenever you have a name but need an ID.' It also notes that each call replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly mention when not to use this tool or name specific alternatives for exclusion, only stating the primary use case.

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 indicate the tool is read-only, idempotent, and not destructive. The description adds behavioral details: it probes each entity, ranks results, and returns a list with score, confidence, and signal density. This goes beyond annotations but does not mention potential rate limits or authorization needs.

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

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

The description is four sentences, front-loaded with the core action, and every sentence adds value. 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?

The description explains the tool's purpose, inputs, and output structure (ranked list with score, confidence, signal density). Given no output schema, it provides sufficient context for understanding what the tool returns, though it could be slightly more explicit about the 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 descriptions for all parameters. The description adds minor context (e.g., first entity as subject) but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces rankings. It also provides a use-case example, differentiating it from sibling tools like ai_visibility_check and compare_entities.

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

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

The description explains when to use the tool (competitive AI-marketing audits) and implies that for single-entity checks, ai_visibility_check is more appropriate. However, it does not explicitly state alternatives or 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 declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral context: partial failures, bundlephobia's first measurement taking 5-30s, sources_failed listing timeouts, and details of return structure.

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 yet comprehensive. It front-loads the purpose, then efficiently details behavior, limitations, and return format without wasted words.

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

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

Despite no output schema, the description is highly complete: explains composite nature, sources, return summary fields, partial failure handling, and ecosystem limitations. No gaps remain for the agent's decision-making.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds useful context like scoped packages being accepted and the version defaulting to latest, which slightly enhances understanding.

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

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

The description clearly states the tool's purpose: a composite check for npm packages combining deps.dev and bundlephobia. It specifies the use case ('should I add this npm package to my project') and distinguishes from sibling tools by focusing on npm dependency scanning.

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

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

Explicit guidance on when to use: when an agent asks about safety/popularity/size of an npm package. It also provides limits ('NPM ecosystem only in v1') and points to alternatives for other ecosystems ('PyPI / Maven / Cargo / Go fall under 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 readOnly, idempotent, non-destructive. Description adds concrete details: character offsets, similarity scores, embedding model (BGE-base-en), windowing (500-char overlapping), character cap (200K), and truncation with flagging. These go well 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?

Front-loaded with purpose, then usage, then technical details. Every sentence adds value; no fluff. Appropriately sized for the tool's complexity.

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

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

Given no output schema, the description explains return format (passages with offsets and scores) and cap. It covers all necessary behavioral aspects, making it complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add new information about individual parameters beyond what the schema provides, but contextually explains how parameters are used in the search process.

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

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

The description states the tool does semantic search inside a fetched record, returning top-N passages with character offsets and similarity scores. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded, making the purpose clear and specific.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and advises pairing with ask_pipeworx_grounded. This provides clear guidance on when to use and how to combine with other tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. Description adds context: data source (Ads API), limit of 10 keywords, and return fields (volume, competition, CPC). 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, includes a concrete example call, front-loaded with the return value. Every sentence adds essential information without redundancy.

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

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

Despite no output schema, description adequately explains return values (volume, competition, CPC). Differentiates from sibling tool, covers limits, and provides example. Annotations and schema are rich, making the description complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the _apiKey format (base64 of login:password), clarifying the max 10 keywords, and providing example usage with defaults.

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 it returns 'Exact Google Ads search volume' with competition and CPC from the Ads API, clearly distinguishing it from the sibling tool seo_keyword_overview.

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 this tool ('when you specifically need Google Ads figures') and when to prefer an alternative (seo_keyword_overview for general SEO volume), including a cost hint.

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 (readOnlyHint=false, idempotentHint=true) indicate mutation but safe repetition. The description adds behavioral context: it creates a subscription, requires authentication, details delivery constraints (SMS cap, webhook auto-disable after 10 failures), and mentions verification steps. 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 thorough and well-structured, grouping information by subscription type and delivery channel. While slightly dense, every sentence adds value and the main purpose 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 moderate annotations, the description covers essential aspects: subscription types, parameter formats, delivery options, and limitations. It lacks a detailed return value description but is otherwise complete for a create operation.

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

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

Schema coverage is 100%, but the description goes beyond by providing concrete examples for each subscription type (e.g., sec_8k items codes, polymarket_edge topics). This adds semantic clarity beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the return value ('Returns the new subscription id') and distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description provides contextual examples for each subscription type and delivery channel, along with prerequisites (Pipeworx OAuth account) and constraints (phone verification, SMS cap). While it doesn't explicitly state when not to use the tool, the guidelines are clear and actionable.

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

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

Annotations already declare safe read-only behavior, but the description adds rich context: it returns live catalog examples, bucket categories, and exact tool calls. 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 somewhat lengthy but every sentence is informative. It front-loads example queries and clearly structures the purpose and options. Could be slightly more concise, but 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?

Given the simple schema (1 optional param, no output schema), the description fully covers behavior, usage, and outcomes. It even mentions meta-tools and when to use this tool first, leaving 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%, baseline 3. The description adds value by listing allowed topic values (finance, pharma, etc.) and explaining that omission yields cross-category results, which is beyond the schema's description.

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

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

The description clearly states that the tool returns category-bucketed example questions with tool/argument shapes, serving as an onboarding entry point. It distinguishes itself from siblings by specifying it should be used first when the agent doesn't know what Pipeworx can do.

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 instructions are given: use when unsure of Pipeworx's capabilities, call with no arguments for full spread, or pass a 'topic' to focus. It also mentions learning to call meta-tools, providing clear alternatives.

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

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

The description adds value beyond annotations by explaining that the row is deactivated (not deleted) and that historical events remain accessible via 'recent_alerts'. Annotations declare destructiveHint=false and idempotentHint=true, and the description aligns with and elaborates on these traits.

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

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

The description is two sentences, 30 words, front-loading the action and constraints. Every sentence adds value without redundancy.

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

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

For a simple mutation tool with one parameter and no output schema, the description covers purpose, ownership constraint, and behavioral nuance (deactivation). It is complete for agent understanding.

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 'id' described as 'Subscription id (uuid) returned by subscribe.' The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id.') with a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by being the inverse operation.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear context on when to use the tool. It does not list alternatives but effectively implies not to use for others' subscriptions.

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

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

The annotations already establish safety (read-only, idempotent, non-destructive), but the description adds crucial behavioral details beyond that: the distinction between could_not_verify (pipeline failure) and unsupported (no source coverage), the requirement not to present could_not_verify as evidence, and the tolerance override behavior. This is exactly the kind of context an agent needs to interpret results correctly.

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

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

The description is dense but well-organized. It front-loads example natural-language queries, then explains the two routing paths, return values, and caveats. Each sentence earns its place, though it could be slightly trimmed without losing 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?

For a complex tool with two routing paths, multiple verdicts, and important failure modes, the description covers all necessary operational aspects. It explains what each verdict means, especially the subtle could_not_verify vs. unsupported distinction, which is essential for correct agent behavior. Without an output schema, this description carries full responsibility and handles it well.

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?

Since schema coverage is 100%, both parameters are already documented in the schema. The description adds meaningful extra semantics for tolerance_pct by explaining how it overrides the claim's implied tolerance and recommending 1–2 for hallucination detection. This adds value beyond the schema's plain description.

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

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

The description clearly states the tool verifies natural-language claims and returns a verdict, distinguishing it from generic ask/search tools. It provides concrete example user phrasings and explicitly mentions the two pipeline paths (SEC EDGAR fast path vs. grounded fallback), which differentiates it from siblings like ask_pipeworx_grounded or resolve_entity.

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 'when to use' directive: whenever the agent needs to check factual correctness. It also explains that it replaces 4–6 sequential calls, implying efficiency benefits over manual pipelines. However, it does not explicitly name alternative tools or state when NOT to use it, so it falls short of a full 5.

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