Linkedin_ads

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

Annotations declare readOnlyHint, idempotentHint, etc. Description adds model-specific safety: default is free, Anthropic requires key with direct billing. Discloses return structure including score, confidence, signals.

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 paragraphs with no fluff. Front-loaded purpose and default model. Every sentence adds value.

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

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

Despite no output schema, description fully compensates by detailing return fields (score, confidence, signals, raw_response, combined view). Covers all parameters and their roles.

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 enriches by explaining _apiKey usage and context disambiguation. Provides baseline 3 plus extra value explaining defaults and behavior.

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 probing LLMs for visibility scoring (0-100) per model, with specific verb and resource. Distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on scoring and per-model results.

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

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

States use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Mentions default model and BYO key for Anthropic. Does not explicitly exclude alternatives but provides enough 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 the tool read-only, open-world, idempotent, and non-destructive. The description adds real behavioral detail: it auto-routes to the right tool, fills arguments, and returns stable pipeworx:// citation URIs. It does not fully clarify the undefined 'fast mode' path or grounding limitations, but adds substantial context beyond annotations.

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

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

The key 'prefer over web search' guidance is front-loaded and the examples are useful, but the description is long and contains redundant/confusing phrasing such as 'for a single quick factual query, best ask_pipeworx itself' and the unexplained 'use fast mode' instruction. It would benefit from tightening.

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 broad routing tool with no output schema, this is complete: it covers what the tool does, when to use it, what kinds of questions to pass, what comes back (structured answer with citation URIs), and when to pick a sibling tool. The examples span many domains and leave little ambiguity for an agent.

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

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

Schema coverage is 100%; all six parameters are documented as aliases for the natural-language question. The description's example queries illustrate valid input style, but they do not materially change or extend the schema-provided semantics, so the high-coverage baseline of 3 applies.

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

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

The description names a specific action ('routes the question', 'returns the structured answer') and a clear resource: factual current/historical data via 5,798 verified tools. The listed domains and example queries make its scope concrete and distinguish it from generic web search.

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

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

Very explicit trigger guidance: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions'. It names condition-specific alternatives (pipeworx_grounded for safest grounded answers, bet_research for speed, ask_pipeworx_beta for minimal latency, deep_research for broad/multi-part questions).

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: beta status, no active candidate, full working router, no fallback, and experimental routing changes. This is useful transparency without contradicting the annotations.

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

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

The description is moderately detailed but every sentence earns its place: identity, current routing state, usage guidance, and fallback clarification. It is front-loaded with the core purpose and avoid unnecessary boilerplate.

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 routing tool with no output schema, the description covers the key contextual needs: what it is, how it behaves, when to use it, and the current candidate status. It could be more self-contained by explaining what ask_pipeworx itself does, but it adequately points to the sibling for that reference.

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

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

Schema description coverage is 100%, with the required 'question' parameter and all five aliases clearly documented. The description adds only that it accepts 'same arguments' as ask_pipeworx, which provides no new parameter-level meaning beyond the schema.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable sibling by the 'candidate routing improvements enabled live' and labels itself 'the experimental edge.'

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

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

It explicitly says to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. This gives an agent a clear condition for selecting this tool over ask_pipeworx.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the refusal behavior with exact refusal_reason values, the success return shape, the constraint to use only tool-result content, and the added cost of one extra LLM call. This gives the agent a realistic model of failure modes and guarantees.

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-ordered: core behavior first, then return/refusal contract, then usage rules, then cost tradeoff. Every clause carries useful information and no filler is present.

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

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

Despite having no output schema, the description fully documents the success and refusal return shapes, the extraction guarantee, when to use it, and when to prefer the sibling tool. An agent has enough context to invoke it correctly and interpret its 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 description coverage is 100%, with the input schema already documenting the question parameter and all six aliases. The description adds no parameter-level detail, but none is needed because the schema fully explains the single meaningful input.

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

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

The description clearly identifies the tool as a hallucination-resistant grounded answer mode that extracts answers only from tool results, and explicitly contrasts it with ask_pipeworx by noting identical routing but stricter extraction. This makes its purpose and differentiation from siblings unmistakable.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' in high-stakes contexts, and lists concrete domains. It also names the alternative ask_pipeworx and tells the agent to prefer it for casual lookups due to the extra LLM call cost.

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 true, idempotent, etc.), the description details fan-out behavior, response shapes, resolver contract, safety measures, resolution-rule risk, and edge cases like wide spreads. All annotations are consistent; no contradiction.

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

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

The description is very long and dense, covering many details. While it is front-loaded with purpose and use cases, it would benefit from bullet points or sections for readability. It is not concise but every sentence adds value, so 'appropriately sized' despite verbosity.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is remarkably complete. It explains response shapes, resolver market_match, parent event extraction, news fields, safety mechanisms, and resolution-rule risk. An agent has all context needed to use it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the market parameter accepts slug, URL, or question text; depth and include_raw are explained with concrete use cases. This goes beyond the schema's brief 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 researches any Polymarket bet using Pipeworx data, specifying the verb 'research' and the resource. It distinguishes from sibling tools like polymarket_edges by focusing on comprehensive research rather than just edge detection.

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

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

The description gives explicit use cases ('should I bet on X', 'what does the data say', 'is there edge') but does not provide explicit when-not-to-use guidance or mention specific sibling alternatives. However, it does explain scenarios where the tool short-circuits (low confidence, closed markets).

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds key behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), sorting by primary metric, handling off-calendar fiscal years, and return of paired data with citation URIs.

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

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

The description is 6–7 sentences, front-loaded with example queries, and every sentence adds value. No redundant or vague phrasing.

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 mentions return of 'paired data + citation URIs per entity' but could elaborate on structure. However, it covers essential aspects for agent selection and 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?

Input schema has 100% description coverage. The description adds meaning by explaining enum values (company vs. drug) and input formats (tickers/CIKs for company, drug names). Slight deduction as schema already provides some detail.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs, with specific data sources and example queries. It distinguishes between type='company' and type='drug' and emphasizes it replaces sequential lookups.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides usage examples. It lacks an explicit 'when not to use' but is otherwise clear.

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

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

Annotations already declare readOnly, openWorld, and idempotent behavior, but the description adds substantial non-obvious context: account/paywall requirements, expected latency, the gaps[] and contradictions[] fields, guarantee that findings are never invented, fetchability semantics for citations, and semantic excerpting behavior. This goes well beyond annotation coverage and contains no contradictions.

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

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

The description is long but densely informative, with critical routing and account information front-loaded. Some redundancies exist — the paid-plan requirement for 'thorough' is stated twice, and the caveat-heavy prose could be tightened — but nearly every sentence contributes a distinct behavioral fact.

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 no output schema, the description is remarkably complete: it covers output structure (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[] behavior, contradictions[], latency expectations, authentication requirements, and the exact distinction from sibling tools. Nothing essential for correct invocation is missing.

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

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

Although schema coverage is 100%, the description adds meaningful depth semantics for the 'depth' enum — describing quick/standard/thorough in terms of facets, hops, gap recovery, contradiction scanning, and paywall status. It also clarifies that 'question' accepts broad natural-language questions and that decomposition is intentional.

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, distinctive function: grounded multi-source research across 1,517 structured data sources, with decomposition into facets and parallel routing. It explicitly contrasts itself with open-web search and names ask_pipeworx as the alternative for single lookups, making sibling differentiation immediate and unambiguous.

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

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

It gives clear when-to-use guidance: best for broad/multi-part questions over structured data, citing concrete example questions. It also states explicit exclusions and alternatives — use ask_pipeworx when not signed in or for single lookups — so an agent can route correctly without guessing.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations.

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

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

The description is concise yet comprehensive, starting with the core action, then specifying use cases and return behavior. Every sentence adds value, and it is well-structured without redundancy.

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

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

Given the tool's role as a discovery tool among many siblings, the description adequately covers purpose, usage, and output. It does not require an output schema because it explains what is returned. The description is complete for an agent to understand when and how to use it.

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

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

Schema description coverage is 100%, so baseline is 3. The description provides a high-level overview but does not add per-parameter detail beyond what the schema already offers. The aliases are noted in the schema, not the description.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and uses a specific verb ('discover'). It distinguishes itself from sibling tools by being the tool discovery/search tool, as indicated by 'Call this FIRST when you have many tools available.'

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 tells when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and prioritization, though it lacks explicit 'when not to use' statements.

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, and the description adds substantial behavioral context beyond those: parallel fan-out behavior, USPTO sunset soft-fail, sources_used/sources_failed semantics, empty sections meaning real no-data rather than bugs, and resolved:false behavior for private companies. No contradictions with annotations.

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

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

The description is long, but it front-loads the most important information: user-intent examples and the 'ALWAYS PREFER' directive. The dense listing of output sections and edge cases earns its place given the tool's multi-source complexity, though better paragraph or bullet structure would improve scannability.

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 burden of explaining return values, and it does so thoroughly: it enumerates cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and sources_used/sources_failed. Input forms, resolution behavior, and failure semantics are all covered, so an agent has enough to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful extra semantics: concrete examples for ticker, CIK, and company name, the zero-padded CIK requirement, name resolution via SEC EDGAR, and the interchangeability of type values beyond what the schema states.

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

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

The description states a specific action and resource: it builds a full cross-source profile of a US public company in one parallel call, and lists concrete sources and outputs. It also differentiates itself from narrower single-pack lookups by instructing agents to prefer it over chaining those lookups.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which gives clear when-to-use guidance. It also covers input formats and the private-company fallback, but it does not explicitly say when not to use it compared with siblings like compare_entities or deep_research.

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 context beyond annotations by specifying that it deletes sensitive data and pairs with other memory tools. No contradictions with annotations (destructiveHint=true, idempotentHint=true). It doesn't detail error handling (e.g., missing key), but the idempotent hint covers that.

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

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

Two sentences, front-loaded with the core action, and no wasted words. Every sentence provides value.

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

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

For a simple tool with one parameter, no output schema, and good annotations, the description covers purpose, usage, and relationships. Nothing essential is missing.

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

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

With 100% schema coverage, the description does not add significant meaning beyond the schema's 'Memory key to delete'. 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 states 'Delete a previously stored memory by key', which is a specific verb and resource. It distinguishes itself from siblings like 'remember' and 'recall' by focusing on deletion.

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

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

The description provides explicit scenarios for use: stale context, completed task, clearing sensitive data. It also suggests pairing with 'remember' and 'recall', giving clear guidance on when to use this tool.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds that it fetches external pages, extracts content, and emits markdown, aligning with annotations and providing necessary behavioral context without contradiction.

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

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

The description is two sentences plus a bullet list, front-loaded with the key action. It is concise and structured well, though the bullet list could be integrated for even tighter prose.

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

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

Given the tool's simplicity (2 params, no output schema, clear annotations), the description covers the output format, use cases, and external dependencies. It is complete and leaves no ambiguity about what the tool does.

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 context by explaining that max_links defaults to 25 and max 50, but this is already in the schema description. No new semantic value beyond what the schema provides.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a URL, explaining the process and output. It distinguishes itself from sibling tools, which are mostly unrelated, by focusing on AI crawler indexing and standard markdown output.

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 three specific use cases: indexing a client's site, drafting for own project, or auditing competitors. While it doesn't mention alternatives or when not to use it, the use cases are clear and sufficient for an agent to decide.

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, indicating a safe read operation. The description adds context about the returned metrics and date range format, but does not cover pagination, error handling, or empty result behavior.

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

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

The description is two sentences long, front-loaded with the action and resource, and every sentence is informative with no superfluous 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?

Given the presence of an output schema and rich annotations, the description does not need to detail output format. However, it omits mention of the optional time_granularity parameter and that campaign_ids is an array, relying on examples in the schema. Somewhat incomplete for a full understanding without inspecting the schema.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description mentions 'date range' and 'by campaign' but does not add significant meaning beyond the schema, such as explaining the optional 'time_granularity' parameter or its default value.

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

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

The description clearly states the verb 'analyze' and the resource 'campaign performance' over a date range, listing specific metrics returned (impressions, clicks, conversions, spend, CTR). It distinguishes from sibling tools like 'li_list_campaigns' which list campaigns rather than analyze performance.

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

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

The description implies usage for analyzing campaign performance over a date range, but does not explicitly state when to use this tool versus alternatives like li_get_campaign or li_list_campaigns. No prerequisites or exclusions are mentioned.

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 that the tool returns specific fields like budget and performance metrics, which provides context beyond annotations but does not disclose behavioral nuances like rate limits or auth requirements. With strong annotations, a score of 3 is appropriate.

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

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

The description is a single, concise sentence that front-loads the purpose and includes an example. Every word adds value, with no redundant or filler content.

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

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

Given the tool's simplicity (one parameter), the presence of an output schema, and thorough annotations, the description is nearly complete. It lists key return fields, but could optionally mention pagination or error handling for edge cases.

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

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

The only parameter, campaign_id, has full schema coverage (100%). The description adds an example of the format ('501234567'), which clarifies what a campaign ID looks like beyond the schema's generic 'Campaign ID' 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 retrieves full details for a specific LinkedIn campaign, listing example fields (name, budget, spend, status, targeting, performance metrics). It uses a specific verb ('Get') and resource ('LinkedIn campaign'), and distinguishes from sibling tools like 'li_list_campaigns'.

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 specifies when to use the tool (to get full details of a specific campaign) and provides an example campaign ID. It implicitly differentiates from listing tools, but lacks explicit when-not-to-use guidance or alternative tool references.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that it returns account IDs, names, and status, and its purpose for campaign identification. There is no contradiction, and the description adds useful behavioral context beyond the annotations.

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

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

Two sentences with no wasted words. The purpose and return values are front-loaded, making it efficient and easy to parse.

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

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

Given the output schema exists, the description adequately covers the purpose, returned fields, and use case. Combined with annotations, it provides complete context for a listing 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?

Input schema coverage is 100% with clear descriptions for count and start. The description does not add any new parameter-specific meaning beyond the schema. Baseline 3 is appropriate as the schema already documents the parameters well.

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

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

The description clearly states the verb 'Check' and specifies the resource 'LinkedIn ad accounts you can access.' It lists the returned fields (IDs, names, status) and the use case (identify which account to use for campaigns), distinguishing it from sibling tools like li_get_campaign and li_list_campaigns.

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

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

The description implies usage when you need to know accessible ad accounts before campaign work. However, it does not explicitly state when not to use it or mention alternatives, though sibling tools are campaign-specific and less likely to overlap.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds return field details (IDs, names, budgets, etc.) but does not disclose additional behavioral traits beyond what annotations provide. No contradiction found.

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

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

Two concise sentences with the purpose upfront. No unnecessary words. Every sentence adds value: first states action, second lists outputs.

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

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

The tool has an output schema, so return values need no further explanation. Parameters are fully described in schema with 100% coverage. The description mentions pagination via count and start implicitly, and the output fields. Complete for a listing tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds an example account ID ('501234567') but does not provide additional semantic meaning for parameters beyond the schema. The mention of return fields is about output, not input parameters.

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

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

The description clearly states 'Get all campaigns in a LinkedIn ad account' with specific verb and resource. It also lists the return fields (IDs, names, budgets, status, date ranges). Distinguishes from siblings like li_get_campaign (single campaign) and li_campaign_analytics (analytics).

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

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

The description implies usage for listing campaigns but provides no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives or exclusions, relying on siblings to 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 declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, covering the safety profile. The description adds value by listing return fields (IDs, titles, content, status, dates) but does not disclose additional behavioral traits 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?

Two sentences: the first states purpose with an example, the second lists return fields. No filler, every word adds value.

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

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

With an output schema present, the description does not need to explain return values. It covers the essential information for a list tool, including example usage and expected output fields, and the annotations are comprehensive.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description provides an example campaign ID but adds no extra semantic detail beyond the schema.

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

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

The description clearly states the tool's function: 'View all ads in a LinkedIn campaign' with a concrete example. It is specific to creatives within campaigns, distinguishing it from sibling tools like `li_list_campaigns` or `li_campaign_analytics`.

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

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

The description provides a clear use case (viewing creatives for comparison) and an example campaign ID. However, it does not explicitly state when not to use it or mention alternatives, though sibling differentiation is implicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds context about the return fields and the default filtering to active subscriptions, which is useful beyond the annotations.

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

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

The description is three sentences: first states the purpose and return fields, second gives usage guidance. No wasted words, well-structured.

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

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

Given a simple optional parameter, no output schema, and safety annotations, the description is complete enough for an agent to understand what the tool returns and when to use it.

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

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

The schema covers the single parameter fully (100% coverage) with a description, and the description does not add additional meaning beyond what the schema provides. Baseline is 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 clearly states the verb 'List' and the resource 'the caller's active subscriptions', and it distinguishes itself from sibling tools like subscribe and unsubscribe by specifying the action and return fields.

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

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

Explicit usage guidance is provided: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when this tool is appropriate.

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

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

Annotations are all false, so the description carries the transparency burden. It discloses rate limiting (5 per identifier per day), quota exemption (free, no tool-call count), and the claim_token workflow for account-less submissions. It also gives realistic expectations (team reads digests daily, affects roadmap). 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 longer than average, but it is front-loaded with the core purpose in the first sentence and every subsequent sentence carries actionable information (scope, claim_token workflow, rate limits, quota). There is no filler or repetition, so the length is justified.

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

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

Given no output schema, 4 optional parameters, and a nested context object, the description covers selection, input formatting, follow-up via claim_token, rate limits, and scope boundaries. It fully equips the agent to decide when to file and how to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful value: it explains the claim_token lifecycle (pass it back with no other arguments to read resolution status) and gives message-content guidance ('don't paste the end-user's prompt'). The type enum is already well described in the schema, so this is a solid but not maximal increment.

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

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

The description opens with a specific action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates the exact feedback categories (bug, feature/data_gap, praise). This clearly distinguishes it from sibling tools like ask_pipeworx or discover_tools, which are for queries or discovery, not feedback.

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

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

It explicitly states when to use the tool per feedback type, and provides a sharp when-not: only for tools served by this Pipeworx connection, with instruction to file elsewhere for other MCP servers. It also tells the agent to describe issues in terms of Pipeworx tools/packs and not to paste end-user prompts.

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

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

The description adds significant behavioral context beyond annotations: data source (CF analytics-engine), no PII, and caching behavior (5min-1h). No contradictions with read-only, idempotent hints.

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

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

Concise at under 100 words, front-loaded with key output, then use cases, then technical details. Every sentence contributes 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 trending tool with one parameter and no output schema, the description completely covers what is returned, how to use it, and caching behavior. No additional information is needed.

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

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

Schema already fully describes the window parameter with enum and description. Description adds semantic value by explaining how window length affects results ('hot right now' vs 'steady-state demand'), providing useful nuance.

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 returns top tools, packs, and call volume over a window, distinguishing it from sibling tools like ask_pipeworx or discover_tools by focusing on aggregated usage trends.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical choice, seeing alignment), though no explicit 'when not to use' with alternatives is given.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds detailed internal logic: Jaccard similarity threshold, placeholder filter, partition check, fill check against CLOB depth, and conditions for false signals. 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 detailed and well-structured, with clear separation of modes and internal checks. While slightly long, every sentence adds value. Could be broken into sections, but front-loads purpose effectively.

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 explains the response structure (opportunities[] with fields). Covers all edge cases: empty call, modes, similarity filter, placeholder filter, fill check, and when not to trade. Provides cross-reference to related 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 provides good descriptions, but description adds significant meaning: explains that event accepts slugs or full URLs, topic is a seed question; describes each mode's behavior and cross-event scanning logic.

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 finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes from sibling tools like polymarket_edges by specifying the unique analysis approach.

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 (no args for trending scan, event for specific market, topic for cross-event scan). Recommends 'event' mode and warns when signals are not tradeable. Directs to polymarket_fill_risk for custom sizing.

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 is extremely detailed, covering model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), edge calculation (edge_pp_net, Kelly fractions), tradeable-edge filters (min_liquidity, max_spread_pp), and response structure (by_segment, diagnostics). It also mentions caching at KV level. Annotations only declare readOnlyHint, openWorldHint, idempotentHint, but the description adds immense value beyond them.

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

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

The description is long but well-organized: starts with purpose, then details model segments, knobs, and response structure. It front-loads the key usage. Some redundancy exists (e.g., repeating segment names) but it's efficiently informative for a complex tool.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (by_segment with three segments, fed_candidates, diagnostics) and caching behavior. All necessary context for an agent to use the tool correctly is provided.

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 good descriptions in the schema itself. The tool description adds extra behavioral context for parameters, such as explaining slippage (Polymarket fees, bid/ask depth) and min_kelly (filtering small opportunities). This additional insight justifies a score above baseline 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 clearly states the tool scans Polymarket markets and returns edges where Pipeworx data disagrees with market price. It specifies it's for 'what should I bet on today' and differentiates from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement rather than general arbitrage.

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: built for discovering betting opportunities without paging hundreds of markets. It explains the three response segments and the tradeable-edge knobs. It could explicitly contrast with siblings but the context is sufficient for an agent to decide when to use it.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description goes beyond by detailing output structure (tracked[], expired[], snapshot_dates[]), limitations (60-day TTL, no intraday), and data semantics. 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 detailed but efficient, front-loading purpose and then output structure. Every sentence adds value, though it is slightly verbose in explaining the decay concept. Still earns its 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?

No output schema exists, so the description must fully explain return values. It thoroughly describes tracked[], expired[], snapshot_dates[] with field details and edge cases (gaps, TTL). Complete for a telemetry tool with moderate complexity.

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

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

Schema covers both parameters (100% coverage). The description adds meaning by clarifying defaults, max for days (30), and possible window values. It explains 'snapshot family' context, adding value beyond 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: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes from sibling polymarket_edges which likely shows current edges only.

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

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

The description explains when to use this tool (to assess edge persistence and decay, differentiating fresh vs old edges). It provides context for decision-making but does not explicitly list when not to use or alternatives.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds crucial behavioral context: partial basket fills can leave unhedged positions, and thin books may yield 'cannot_fill' verdict. This goes beyond annotations by explaining risk of the check itself, though the core safety signals are covered by annotations.

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

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

The description is a single dense paragraph (~150 words) that efficiently conveys many details. It front-loads the core purpose. However, breaking the two modes into separate paragraphs or bullet points would improve readability. No wasted sentences.

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

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

Given the tool's complexity (two modes, four parameters, no output schema), the description covers all essential aspects: inputs, behavior for each mode, return fields (top_of_book, vwap, verdict, profit_usd, thin_legs, etc.), and the rationale for its existence. It is fully adequate for correct invocation.

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

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

Schema description coverage is 100%, but the description adds significant meaning: what single-market vs basket modes mean, how size_usd is interpreted for each (max spend vs target proceeds vs settlement notional), and auto-detection of side for basket. It also explains default values and clamps, surpassing 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 states the tool checks realizable-vs-theoretical edge against live CLOB depth, distinguishing single-market and basket modes. It uses specific verbs ('check', 'walks the ladder') and resources ('market slug', 'event slug'), making the purpose unambiguous and distinct from sibling tools like polymarket_arbitrage.

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 tells when to use: before acting on polymarket_arbitrage signals or polymarket_edges trades above $500. Provides rationale: theoretical overround on thin books is not capturable, and partial basket fills cause unhedged positions. This excludes alternatives and gives clear when-to-use guidance.

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

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

Even with readOnlyHint and idempotentHint annotations carrying the safety profile, the description adds extensive behavioral disclosures: compatibility_warning and codes, pairing_unverified status, fee-structure limitations, skipped leg counts, and the exact meaning of temporal_alignment null. It tells the agent that returned pairs can still be unsafe and that the spread is gross, not a net tradeable edge. This goes far beyond the annotations without contradicting them.

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

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

The description is long but well-structured with clear labels: TWO MODES, RESPONSE, SAFETY FIELDS, and closing caveats. Almost every sentence carries safety-relevant information for a nuanced tool with no output schema. There is some redundancy around temporal alignment warnings and compatibility codes, but the length is largely justified by the complexity and the high cost of misinterpreting the spread.

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 the absence of an output schema, the description covers all key behavioral aspects: both modes, response structure, safety codes, per-spread flags, gross vs. net fees, skipped comparisons, and temporal alignment semantics. An agent has enough context to invoke the tool correctly and interpret returned warnings appropriately without additional documentation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it explains the interaction between topic and explicit parameters, states that both modes run the same token-overlap matcher, clarifies that explicit values override topic mappings, and warns that pre-mapped does not imply tradeability. This makes the parameter model substantially clearer than the schema alone.

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

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

The description opens with a specific and unambiguous statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly names the tool's resource (cross-venue price spreads) and its unique function, distinguishing it from same-venue tools like polymarket_arbitrage. It also precisely describes the two operating modes right away.

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

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

The description gives clear, actionable guidance on when to use each mode: topic shortcuts for pre-mapped macros and explicit ticker/slug pairs for custom pairings. It also sets expectations by stating that most pre-mapped topics return compatibility warnings and are not necessarily tradeable. However, it never explicitly names sibling alternatives such as polymarket_arbitrage or polymarket_edges, so the choice vs. alternatives is left somewhat implicit.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds scoping (anonymous IP, BYO key hash, or account ID) and the listing behavior when key is omitted. No contradictions, but lacks details on rate limits or auth beyond scoping.

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 succinct sentences, each adding value: action, usage examples, and scoping/pairing. 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?

Covers purpose, usage, scoping, and relationship to siblings. Lacks output schema and details on return values, but adequate for a simple read tool.

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

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

Schema coverage is 100% with description for the single 'key' parameter. Description repeats schema info (omit to list all keys) but adds no new semantics 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?

Clearly states verb (retrieve/list) and resource (values saved via remember, keys), 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?

Explicitly describes when to use: to look up previously stored context without re-deriving. Mentions scoping and pairing with remember/forget, giving clear usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds details: mark_read side effect, return fields structure, and polling suitability. No contradictions.

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

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

Concise, front-loaded with main action, each sentence adds value: what it returns, filtering, mark_read, polling note. 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?

No output schema, but description lists return fields (source, citation_uri, raw payload) and mentions polling and alternative endpoint. Covers usage patterns well, though could mention default limit behavior.

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

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

Schema coverage is 100% with parameter descriptions. Description reinforces filtering and mark_read behavior and adds context (ISO timestamp for since) but does not significantly extend beyond schema explanations.

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

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

Description clearly states it pulls fired events from subscription feed, returns most recent alerts with source, citation_uri, and raw payload. Distinguishes from siblings like list_subscriptions by focusing on alert content.

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

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

Provides explicit guidance: 'Polls work fine' and mentions alternative access via REST endpoint for scripts/dashboards. Filtering options are described, though no explicit when-not-to-use or alternatives among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context: fan-out to multiple sources, GDELT→GNews fallback, soft-fail for patents, output format with changes[] and pipeworx:// URIs. No contradiction with annotations.

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

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

The description is a single coherent paragraph, front-loaded with query examples, then explains sources, parameters, and distinguishes from sibling. Every sentence serves a purpose; no wasted words.

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

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

Despite no output schema, the description specifies the return structure (changes[] grouped by source, total_changes, pipeworx:// URIs). It covers all three parameters with usage guidance, source behaviors, and fallbacks. For a tool with three required params and no nested objects, this is thorough and complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds useful context beyond schema: examples of relative shorthand for since (e.g., '30d'), typical monitoring window ('Use 30d or 1m'), and clarification that value accepts ticker or zero-padded CIK. This elevates it to 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 starts with concrete query examples ('What's new with X', 'latest on Y'), then states the tool returns a change feed for a company in a window, listing specific sources (SEC, GDELT/GNews, USPTO). It explicitly distinguishes itself from sibling entity_profile, making purpose crystal clear.

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

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

The description provides explicit examples of when to use this tool ('What's new with X') and directly tells when to use the alternative entity_profile instead ('Use entity_profile instead when you want the static profile'). It also explains 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 and non-destructive hint. Description adds key context: scoped by identifier, persistence differences for authenticated vs anonymous sessions (24-hour retention). No contradiction with annotations.

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

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

Four sentences, well-structured: first sentence states core purpose, second gives usage context, third and fourth detail behavior. No wasted words, information dense yet 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?

For a simple key-value store with no output schema, description fully explains purpose, usage, persistence behavior, and relationship with siblings. Complete and self-contained.

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

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

Schema coverage is 100%, but description adds value by giving example key formats and clarifying that value can hold any text. Provides needed context 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 saves data for reuse, specifies verb 'save' and resource 'data, key-value pair', and distinguishes from sibling tools '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 says 'Use when you discover something worth carrying forward' and provides concrete examples (resolved ticker, target address, user preference). Also mentions pairing with 'recall' and 'forget', giving 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 greatly exceeds the annotations' safety profile by disclosing detailed behaviors: returns unresolved identifiers explicitly, returns figi_candidates on ambiguity, degrades gracefully when GLEIF/OpenFIGI are down, cascades through multiple lookup endpoints, and maps ISINs to legal entities. No contradiction with readOnly/openWorld/idempotent/destructive annotations exists.

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

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

The description is long but densely packed with decision-relevant information, and it is front-loaded with example queries and the primary use instruction. Every clause either clarifies scope, documents a behavioral edge case, or specifies input formats; there is no filler or redundancy.

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

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

With no output schema present, the description fully covers return semantics: which identifiers come back for each type, source labeling, the unresolved field, ambiguity handling, and graceful degradation. It also explains internal cascading behavior so the agent understands why one call replaces multiple manual lookups.

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

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

Although the schema covers both parameters at 100%, the description adds crucial semantic nuance: pass only the entity name, never the full noun phrase; trailing security-class words break matching; ticker vs. name search behavior differs; and the value parameter accepts ticker, CIK, ISIN, or name. This materially improves the agent's ability to supply correct input.

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

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

The description states a specific purpose: resolving user-spoken names into canonical/official identifiers (CIK, ticker, LEI, FIGI, RxCUI) that other tools require as input. It opens with concrete example queries and explicitly distinguishes its role from downstream tools, making its function unmistakable.

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

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

The description gives clear and strong guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains the supported entity types and the kinds of inputs accepted. It does not explicitly name sibling tools as alternatives or state when not to use it, so it stops short of a full exclusion-based usage guide.

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 as true, and destructiveHint false, indicating safe, idempotent, non-destructive behavior. The description adds value by explaining the tool probes entities via ai_visibility_check, ranks them, and returns a structured output (score, confidence, signal density). It does not contradict annotations.

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

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

Two sentences that front-load the purpose and immediately convey the tool's mechanism and value. No redundant or extraneous information. 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?

Given the tool is composite (calls ai_visibility_check), the description explains the probe mechanism, ranking, output fields, and typical use case. No output schema exists, but the description specifies the return format clearly. It is sufficiently complete for an agent to decide when and how to use the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description does not add significant new meaning beyond the schema; it mentions entities and context but the schema already includes detailed descriptions (e.g., 'First entry treated as the subject'). No additional parameter behavior or constraints are provided in the description.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from the sibling ai_visibility_check tool (single entity) and other comparison tools by specifying the domain (AI visibility) and output (ranked list).

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question. However, it does not explicitly state when NOT to use this tool (e.g., for single entity checks, use ai_visibility_check instead). The context is good but lacks explicit exclusions or alternative references.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds significant behavioral context: composite call to two external sources, partial failure handling, bundlephobia's first-measurement delay (5-30s), and that sources_failed lists timeouts.

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 thorough and front-loaded with purpose, but slightly verbose due to completeness. Every sentence adds value, but could be trimmed slightly without losing clarity.

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

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

Despite lacking an output schema, the description fully explains the return structure (summary block, per-advisory, links, alternative versions) and handles edge cases like partial failures. Complete for a composite tool with external dependencies.

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 meaning by clarifying package names accept scoped packages and version defaults to latest when omitted, 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 the tool performs a composite check for npm packages, covering license, advisories, version history, and bundle size. It distinguishes itself by being a single-call aggregator, contrasting with sibling tools like deps.dev:version.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also notes NPM-only scope and directs users to deps.dev:version for other ecosystems.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and not destructive. Description adds significant behavioral detail: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag, output includes offsets and scores. No contradiction with annotations.

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

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

Three sentences are concise and front-loaded with the core purpose. Every sentence adds value: purpose, usage guidance, and technical details. No redundancy or 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 thoroughly explains output structure (passages with offsets and scores), embedding model, window size, character cap, and truncation behavior. Complete for an agent to understand and use the tool effectively.

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 description need not add much beyond what schema provides. It adds example queries for the 'query' parameter but does not significantly enhance meaning beyond the schema descriptions. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool does semantic search inside a fetched record, using specific verb 'search' and resource 'inside a record'. It distinguishes from siblings by mentioning it pairs with 'ask_pipeworx_grounded' and saves context.

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

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

Provides explicit guidance: 'Use when the record is too big to cram into the prompt' and explains that it returns only relevant passages. It also pairs with a sibling tool, implying when to use this tool vs alternatives. No explicit when-not-to-use, but context is clear.

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

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

Disclosures beyond annotations: requires OAuth, webhook secret returned once, auto-disable after 10 failures, delivery caps. 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?

Long but efficient: every sentence adds value. Front-loaded with main purpose. Slightly verbose but justified by 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, description covers return value (subscription ID, webhook secret). Parameter details are thorough, covering all types and delivery channels. No missing information needed to use the tool.

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

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

Schema coverage is 100%, but description adds significant value with examples, constraints (e.g., phone verification, 10/day cap), and webhook signing details for each parameter.

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. Distinguishes from siblings like list_subscriptions and unsubscribe by emphasizing creation and proactive monitoring.

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

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

Provides clear context: requirement for Pipeworx OAuth account, supported types, and parameters. Lack of explicit when-not-to-use or alternatives is minor given sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond annotations: it returns category-bucketed examples, includes exact tool + argument shapes, and is drawn from a live catalog. 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 front-loaded with common user queries and structured effectively, but it is somewhat lengthy. However, every sentence earns its place, and the content is essential. Minor reduction could improve conciseness without losing value.

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

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

For an onboarding tool with one optional parameter and no output schema, the description covers all necessary context: purpose, output contents (category-bucketed questions with tool shapes), parameter behavior, and when to use. It fully compensates for the lack of output schema and aligns with the tool's simplicity.

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 one parameter 'topic'. The description adds meaning by listing valid values (e.g., finance, pharma) and explaining that omitting it gives a cross-category spread. This enhances 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 the tool's role as an onboarding entry point, listing common user queries and explicitly positioning it as the first tool to use when unsure of Pipeworx's capabilities. It distinguishes from siblings by contrasting with meta-tools like ask_pipeworx, entity_profile, etc. The verb 'suggest' and resource 'questions' are specific and concrete.

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 guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to use the optional 'topic' parameter versus omitting it for a full spread, giving clear context for usage decisions.

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

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

Discloses key behaviors: ownership enforcement, soft deactivation (row deactivated not deleted), and preservation of historical events. Annotations already provide destructiveHint=false and readOnlyHint=false; description adds valuable 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 with no waste. Front-loaded with the core action, followed by critical constraints. Every sentence adds value.

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

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

For a single-parameter tool with no output schema and informative annotations, the description covers ownership and deactivation. Could optionally mention success or error handling, but is adequate for agent 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% with a description for the 'id' parameter. The tool description does not add meaning beyond the schema's existing description ('Subscription id (uuid) returned by subscribe.'). Baseline 3 applies.

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

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

Description clearly states the action 'Cancel a subscription by id', identifies the resource, and distinguishes from siblings (subscribe, list_subscriptions) by specifying ownership enforcement and soft-deactivation behavior.

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

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

Provides clear context: ownership enforcement (only cancel own subscriptions) and effect on historical events (available via recent_alerts). However, lacks explicit when-not-to-use or alternatives beyond implicit sibling distinction.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context beyond that: it enumerates all possible verdicts, explains that could_not_verify means the check did not happen and carries verification_error, and clarifies that unsupported means no source exists. It also discloses the fast-path vs grounded pipeline behavior. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: examples, when-to-use, internal routing, return types, and a caller-critical warning about could_not_verify. It is appropriately sized for a fact-checking tool with multiple paths, and information is front-loaded with natural-language triggers.

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

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

With no output schema, the description fully explains return semantics: verdict values, actual value with pipeworx:// citation, reasoning, and the meaning of error/inconclusive states. It also covers the two distinct claim categories and what happens for unsupported claims. This is complete enough 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 description coverage is 100%, so the schema already fully documents both claim and tolerance_pct with examples and default behavior. The tool description adds little parameter-specific meaning beyond reinforcing that claim is natural-language and mentions the tolerance override indirectly via verdict grading. Baseline 3 is appropriate because 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 clearly identifies a specific verb+resource: natural-language claim verification against authoritative sources. It distinguishes itself from siblings by explicitly covering both structured SEC/XBRL fast-path claims and a grounded fallback pipeline, and notes it replaces 4–6 sequential calls. This is unique among the sibling tools listed.

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

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

The description gives an explicit when-to-use instruction: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains internal routing for company-financial vs any other claim. It does not explicitly name alternative tools to avoid or state when not to use this tool, but the positive guidance is clear and specific.

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