Hilma

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

The description discloses that the tool is read-only, probes multiple LLMs, requires a BYO key for Anthropic with direct payment, and returns structured data. It aligns with annotations (readOnlyHint, idempotentHint, openWorldHint) and adds context like the default model and cost implications.

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 return structure list, front-loading the core action. Every sentence provides essential information without redundancy, making it highly efficient.

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

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

Given the tool's complexity (4 parameters, no output schema, no enums), the description covers purpose, parameters, usage guidelines, and return format. It is self-contained and answers likely agent questions about 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 baseline is 3. The description adds value beyond the schema by explaining the default model, indicating that _apiKey is only needed for anthropic, and clarifying that context helps disambiguate. This justifies a 4.

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

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

The description uses a specific verb ('probe'), specifies the resource ('LLMs'), and defines the output ('score visibility 0-100 per model'). It clearly distinguishes from sibling tools like ask_pipeworx or deep_research by focusing on AI visibility scoring for businesses/brands.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional _apiKey. However, it does not explicitly state when not to use the tool or suggest alternatives, which would raise the score to 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe-read behavior is covered. The description adds genuinely useful behavioral context: it routes to thousands of tools, fills arguments automatically, returns pipeworx:// citation URIs, and is described as 'one fast call.' 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 front-loaded with the key directive ('PREFER OVER WEB SEARCH'), a domain list, and useful examples. A few phrases are slightly garbled ('default entry point, works on every tier, one fast call'), yet each section earns its place.

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

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

For an open-ended tool with no output schema, the description covers supported domains, trigger phrases, examples, routing behavior, citations, and when to use alternatives. The main gap is lack of guidance about failure behavior when a query falls outside the 5,798 tools, but this is minor given the breadth of coverage.

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

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

Schema coverage is 100% and every one of the six parameters is documented as an alias for the same free-text 'question' field. The description repeats that a natural-language question is the input but does not add meaning beyond the schema's alias 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?

The description clearly identifies a natural-language question router: 'Routes the question to the right one of 5,798 tools across 1517 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It also positions itself against web search and names sibling tools like ask_pipeworx_grounded and deep_research, so the agent can distinguish it without opening the schema.

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 'PREFER OVER WEB SEARCH' and 'Use whenever the user asks "what is", "look up", "find", "get the latest", "how much", "current"' with concrete domain examples. It also gives clear escalation criteria: use ask_pipeworx_grounded for hallucination-resistant single answers and 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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context beyond those: the beta behavior is dynamic (candidate routing improvements may be active), the current state (no active candidate as of 2026-07-26), the identical response shape guarantee, and the fact that it is fully functional rather than a degraded fallback. Minor missing disclosure would be any side effects for the evaluator, but the description is remarkably transparent.

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

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

Well-structured, front-loaded with the core identity (beta universal router), uses a parenthetical to efficiently convey the massive tool set, and every sentence adds information about state, usage, or comparison criteria. 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?

Given the open-world nature, absence of output schema, and high complexity, the description covers the tool's state, current equivalence to stable, intended use, and evaluation role. It could arguably mention that results might be compared or logged, but it already implies that with 'results are compared against the stable router.' Slightly more detail on when not to use it would push this to 5, but the description is largely complete.

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

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

Schema coverage is 100% and all non-question parameters are explicitly documented as aliases for question. The description reinforces that the same arguments as ask_pipeworx are accepted, which adds a usage invariant beyond the schema. It does not enumerate each alias in prose, but the schema itself handles that fully, so the description complements rather than repeats.

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 explicitly identifies a specific verb+resource (ask_pipeworx beta, a universal router matching the same 5,798 tools, arguments, and response shape) and differentiates it from its sibling ask_pipeworx: it is the experimental routing edge, not the stable router. It names the sibling it is not and explains the state (no active candidate, currently identical).

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

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

Explicitly instructs to use it exactly like ask_pipeworx when you want the newest routing, and describes the evaluation purpose (results are compared against the stable router to decide what merges). This clearly routes the agent between ask_pipeworx and ask_pipeworx_beta. It also explicitly says it falls back to nothing and is a full working router, preventing the agent from treating it as a stub.

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, openWorld, idempotent, and non-destructive behavior, and the description reinforces and expands on this with valuable context. It discloses the success return shape, the explicit refusal reasons, the verbatim evidence behavior, and the added cost of one extra LLM call, giving the agent a clear behavioral model.

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 is informative: mode, routing, grounded extraction, success/refusal shapes, usage guidance, and comparison to ask_pipeworx. It is somewhat longer than strictly necessary, but the length is justified by the tool's behavioral complexity and the lack of an output schema.

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

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

Given there is no output schema, the description fully accounts for return values and error/refusal behavior, including the possible refusal_reason values. It also covers when to use the tool, when not to, the main sibling alternative, and the cost tradeoff, making the description complete for safe and correct invocation.

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

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

The schema already documents the single real parameter 'question' and its aliases with 100% coverage, so the description does not need to add parameter-level detail. The description adds contextual framing about grounding and refusal behavior, but it does not explain parameter semantics beyond what the schema provides, which matches the baseline for full schema coverage.

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

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

The description clearly identifies this as a 'hallucination-resistant answer mode for high-stakes reads' and explains the exact behavior: routing, argument filling, fetching, and extraction only from tool results. It also distinguishes itself from the sibling ask_pipeworx by emphasizing grounded evidence and refusal behavior rather than generic lookup.

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

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

The guidance is explicit: use when an answer will be quoted, cited, or acted on and the agent must not invent facts, with concrete examples like financial verdicts and legal claims. 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?

The description provides extensive behavioral details beyond annotations. It covers response shapes (market, analysis, evidence), resolver contract (market_match_confidence, alternatives), parent event extraction, news fields with fallback info, safety mechanisms (low-confidence short-circuit, closed markets, wide spread), and resolution-rule risk (cancellation_rule). No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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

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

The description is very long (multiple paragraphs) and contains extensive detail. While comprehensive, it could be more concise. However, it is front-loaded with the core purpose and then proceeds to details, which helps scanning. For a complex tool, this length is somewhat justified but still not optimally concise.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is remarkably complete. It covers response structure, resolver contract, parent event extraction, news fields, error conditions (low-confidence, closed markets, wide spread), and resolution-rule risk. It compensates fully for the lack of output schema.

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

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

Schema coverage is 100% with each parameter described. The description adds value by providing examples for 'market', enum explanation for 'depth' (quick vs thorough), and context for 'include_raw' (when to use true/false). It clarifies usage beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the target (Polymarket bet), action (research), and data source (Pipeworx). The verb 'Research' and resource 'bet' are specific. It differentiates from sibling tools like polymarket_edges or polymarket_arbitrage which are more narrow.

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

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

The description explicitly lists use cases: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' It also describes classifiers and fan-out examples, helping agents decide when to use this tool. However, it does not explicitly state when not to use it or name alternatives, though siblings are available.

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, and destructiveHint=false. The description adds behavioral context: the tool makes a single parallel call, handles off-calendar fiscal years correctly, sorts results, and returns citation URIs. No contradiction with annotations, and the description enriches the behavioral profile.

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

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

The description is seven sentences long, front-loaded with example triggers. Every sentence contributes unique information (data sources, sorting, replacement of sequential lookups). While not extremely concise, it is efficient and well-structured.

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

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

With no output schema, the description carries the full burden of explaining return values. It mentions paired data, citation URIs, and sorting by primary metric. It doesn't detail the exact response structure, but for a comparison tool with known domains (company/drug), the provided context is sufficient for an agent to understand what to expect.

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

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

Schema coverage is 100% with descriptions for both parameters. The description goes beyond by explaining what data each 'type' pulls (company: financial metrics from SEC; drug: FAERS counts) and provides examples for 'values'. This adds meaningful context that helps the agent understand the parameter's impact.

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

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

The description uses specific verbs ('Compare', 'side-by-side comparison') and clearly identifies the tool's resource (companies or drugs) and scope (2-5 entities in one call). It distinguishes from siblings by explicitly stating it replaces sequential single-pack lookups and by listing sibling tools like 'entity_profile'.

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

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

The description provides explicit trigger phrases ('Compare X and Y', 'which is bigger') and a strong preference recommendation ('ALWAYS PREFER over sequential single-pack lookups'). It lacks explicit exclusions (e.g., when more than 5 entities are needed or when other metrics are required), but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered, but the description adds substantial behavior beyond that: account/permission requirements, timing expectations (15-60s, up to ~90s for thorough), the parallel decomposition-routing mechanism, the 'never invented' gaps[] guarantee, the contradiction-scan behavior for standard/thorough, the semantic excerpting behavior, and the citation_uri fetchability caveat. All of this is useful, non-obvious runtime context.

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

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

The description is long, but nearly every sentence carries a distinct piece of essential information: access gate, alternative routing, core function, mechanism, return format, use cases, depth semantics, timing, and caveats. It is front-loaded with the most critical gating information (account required, alternative tool) before the mechanics. Minor stylistic flourish in the pipe-related wordplay adds a little length but does not reduce 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?

With no output schema, the description carries the full burden of explaining return values — and it does: the findings packet (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), gaps[], contradictions[], the hop field, and citation_uri resolution behavior. It also covers prerequisites, tier restrictions, latency expectations, and error-like behavior (unanswerable facets are never invented). Nothing an agent needs to call this tool correctly and interpret its results is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains the real-world consequence of depth choices ('thorough needs a paid plan', timing per depth level), enriches the question parameter ('Broad/multi-part is fine — decomposition is the point'), and gives concrete example queries that show the intended input style. This goes beyond the schema-level enum 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 states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call.' It explicitly distinguishes itself from open-web search ('this is NOT open-web search') and from sibling tools by naming what it is not, so an agent can differentiate it from ask_pipeworx and entity_profile without opening their schemas.

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

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

The description gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data'), explicit when-not-to-use guidance ('For a single lookup use ask_pipeworx instead'), and a hard exclusion condition ('If you are not signed in, use ask_pipeworx instead'). It also names the paid-tier restriction for 'thorough', leaving no ambiguity about selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the key behavioral trait that the tool '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 and provides valuable context about the return format and readiness for use. 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 well-structured and front-loaded: it states the main action, then when to use, then examples, then return value. It is slightly verbose but every sentence adds value. Could be slightly shorter, but overall efficient for the complexity.

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

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

Given no output schema, the description fully explains the return value: '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.' It also mentions default limit (20) and max (50). The description provides all necessary context for a discovery 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 description does not add meaning beyond the schema: it mentions that query accepts natural language and aliases (task, q, description, search), but those are already documented in the schema. The description adds no new parameter semantics.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many example domains (SEC filings, financials, FDA drugs, etc.), making the scope explicit. It implicitly distinguishes from sibling tools because it is the only discovery tool in the list, and its name 'discover_tools' is self-explanatory.

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

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

The description explicitly states when to use this tool: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also says 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and lists many use cases. No exclusions or alternatives are needed because this is the only discovery 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?

Massively exceeds the readOnly/openWorld/idempotent annotations by disclosing failure modes and expected-empty semantics: 'an empty section is a real "no data", not a bug,' USPTO patents that 'soft-fail until reactivated,' and FDA behavior for small-molecule-only companies being 'expected, not a failure.' Also documents the private-company path ('resolved:false with an explicit notes line'), the GDELT→GNews fallback, and resolved_from/resolved_to name-mapping. No contradiction with annotations.

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

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

Front-loaded with trigger phrases and the core promise ('ONE parallel call') before a dense but organized catalog of sources, return fields, and edge cases. Given the tool's complexity, nearly every sentence earns its place; the deduction is for redundancy — the interchangeable-`type` note and input formats repeat schema content, and the single-paragraph wall-of-text structure could use section breaks.

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

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

With no output schema, the description carries the full burden of explaining return values — and it delivers: cik, resolved_from/resolved_to, recent_filings (up to 5, with pipeworx:// URIs), LATEST 10-K fundamentals, per-source sections, and the sources_used/sources_failed diagnostic. Input variants, private-company behavior, source fallbacks, and 'no data' semantics are all covered; nothing needed to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine value with concrete input examples ('AAPL', '0000320193', 'Moderna'), the resolved_from/resolved_to behavior for name inputs, and private-company resolution semantics. However, it partly restates the ticker/CIK/name formats already documented in the schema for both parameters, limiting the incremental gain.

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

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

States a specific verb+resource+scope: 'full cross-source profile of a US public company in ONE parallel call,' backed by concrete trigger phrases ('Tell me about X', 'brief me on Tesla'). The 8 named sources, the return-shape summary, and the explicit contrast with 'chaining single-pack SEC/XBRL/news lookups' cleanly separate it from siblings like resolve_entity or deep_research.

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

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

Provides explicit when-to-use signals via the example user queries and the directive 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' This is both a positive trigger and an explicit exclusion of the alternative approach; the only minor gap is not naming deep_research/compare_entities as competing 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 destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and states the action is deletion, but does not explain behavior when key does not exist or any side effects. The additional value is minimal.

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

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

The description is extremely concise (two sentences) with no wasted words. The first sentence states the core purpose, and the second provides usage guidance. Every sentence earns its place.

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

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

For a simple tool with one parameter, no output schema, and clear annotations, the description is complete. It covers purpose, usage scenarios, and sibling relationships, leaving no significant gaps.

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

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

Schema coverage is 100%, so baseline 3. The description mentions 'by key' which matches the schema's parameter. No additional semantics or format details are provided beyond the schema.

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

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

The description uses a specific verb and resource: 'Delete a previously stored memory by key'. It clearly distinguishes from sibling tools 'remember' and 'recall' by explicitly pairing with them, implying they serve different purposes.

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 on when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with 'remember' and 'recall' as alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description's added detail about fetching the page, extracting title/description/key links, and emitting standard markdown format enriches the behavioral model without contradiction. It could further mention rate-limiting or auth requirements, but the current detail is strong.

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 bulleted list of use cases. It is front-loaded with the primary action and output, every sentence adds value, and there is no extraneous text. Optimal length for an LLM to parse quickly.

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, no nested objects), the description fully covers input (URL, optional max_links), process (fetch, extract, format), and output (standard llms.txt markdown blob). No missing detail for an AI agent to correctly invoke this 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% (both url and max_links documented). The description does not add new parameter-specific meaning beyond the schema, but it provides context on what the output contains (title, description, key links). Baseline 3 is appropriate; no extra depth for params is needed since schema is clear.

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

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

The description states a specific verb ('Generate'), a clear resource ('production-ready llms.txt file'), and the scope ('for any URL'). It distinguishes from sibling tools by specifying the exact output format and use cases ('get a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). No sibling tool duplicates this functionality.

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

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

The description explicitly lists three concrete use cases (client indexing, own project drafting, competitor auditing), giving clear context for when to use. It does not explicitly state when not to use or name alternatives, but the sibling list contains no obvious alternative for this specific task, so the guidance is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description's burden is lower. It adds value by detailing the return fields (buyer, dates, CPV codes, flags). There is 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?

Two sentences, front-loaded with the core action, followed by return details. Every sentence earns its place; no fluff.

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

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

For a simple lookup tool with 3 optional params, the description covers the operation and return metadata adequately. No output schema exists, so the return description is helpful. Could mention idempotency or that it's a single result, but annotations cover safety.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond what the param descriptions provide; it merely reiterates that notice_number is an example and that id comes from a search. No extra guidance on format or usage.

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: 'Look up a single Finnish public procurement notice on Hilma' by either a notice number or index document id. It specifies the resource (Hilma notice), the action (look up), and distinguishes from siblings like hilma_search which is for multiple 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?

The description implies usage (single notice lookup) but does not explicitly state when to use this tool over siblings like hilma_search or hilma_recent. No exclusions or alternative recommendations are provided, leaving it to inference.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds behavioral context: defaults (7 days, 20 results), source (Hilma), and optional API key requirement. No contradictions. Could mention rate limits or pagination, but adequate.

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

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

Two sentences: first states purpose, second gives use case and features. No waste, front-loaded, easy to parse. Ideal conciseness.

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

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

Given no output schema, the description covers source, default behavior, supported views, and comparison to sibling. Could hint at return format (similar to hilma_search) but still quite complete for a list tool with rich annotations.

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

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

Schema has 5 params with 100% description coverage, so baseline is 3. Description goes beyond by explaining defaults (top=20, days=7) and mapping to views (national-only, plans-excluded). Adds value over plain schema.

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

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

The description uses specific verb 'List' and resource 'most recent Finnish public procurement notices from Hilma', and distinguishes from sibling 'hilma_search' by calling itself a convenience wrapper for time-bound queries. It also mentions supported views (national-only, plans-excluded) that are clear from the description.

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 'Convenience wrapper over hilma_search for what new Finnish tenders were published this week style questions', telling when to use this tool (time-bound recency) versus the alternative hilma_search for more complex queries. Also describes supported views.

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, openWorld, idempotent, non-destructive. Description adds context: returns newest-first index docs with specific fields, notes Finnish terms match best, and mentions optional API key signup. 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, well-structured paragraph of about 100 words. It front-loads the purpose and usage guidance, then lists filters concisely. No redundancy or unnecessary details.

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 13 parameters and no output schema, the description covers input summary and output fields (notice number, buyer, dates, CPV, flags). It also mentions pagination (newest-first) and language preferences. Adequate for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by summarizing key filters (buyer, CPV, date range, etc.) and providing a quick overview that complements the schema. The examples in the schema further aid understanding.

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

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

The description clearly states the tool searches Finnish government procurement notices on Hilma, specifying the resource and verb. It distinguishes itself from web search by explicitly saying 'PREFER OVER WEB SEARCH for Finnish public tenders'.

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 this tool over alternatives (prefer over web search) and lists specific use cases like Finnish public tenders, julkiset hankinnat, etc. No need for when-not-to-use as it's a specialized search tool.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds details on returned fields and default filtering, but annotations carry most burden.

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, front-loaded with 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?

Simple tool with one optional parameter, no output schema. Description fully covers what it 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?

Schema coverage is 100% and describes include_inactive. Description mentions 'active subscriptions' implying default filtering, but adds limited value beyond schema.

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

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

Description states 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', giving clear when-to-use 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?

Beyond the all-false annotations, the description discloses the claim-token return mechanism, the ability to later query resolution status, daily rate limiting, and that filing is free and does not count against quota. It also notes the team's triage cadence and roadmap influence, which is useful behavioral context without contradicting annotations.

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

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

The description is longer than average but every sentence earns its place: scope, exclusions, claim-token flow, rate limits, and quota impact. It is front-loaded with the core purpose and structured into a coherent, readable flow.

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

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

With no output schema, the description adequately covers return behavior via claim_token and later reads. It provides enough context for correct invocation despite the nested context object and zero required parameters, and clarifies relationship to the Pipeworx catalog and other MCP servers.

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 repeat parameter details. It adds valuable usage nuance for claim_token (how to pass it back, no other args) and message (be specific, don't paste end-user prompt), going beyond the bare 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from sibling research/query tools by framing it as a feedback channel for Pipeworx tools, not a data-access tool.

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

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

Provides explicit when-to-use guidance for bug, feature, data_gap, and praise, plus a critical exclusion: do not report issues for tools from other MCP servers. It also gives filing guidance and a fallback for uncertain cases, making alternatives and boundaries unmistakable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so safety is clear. Description adds valuable context: self-aggregating from CF analytics, no PII, and caching durations (5min-1h). These details go beyond annotations and help the agent understand 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?

Description is concise (4 sentences) with a clear structure: first sentence states purpose, then bullet-pointed use cases, then data provenance and caching. Every sentence adds value without redundancy.

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

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

No output schema is provided, and the description only vaguely says 'Returns the top tools, top packs, and total call volume' without specifying the response structure (e.g., JSON fields, ordering, or pagination). For a tool with no output schema, the description should compensate with format details to help the agent parse 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?

The sole parameter 'window' has 100% schema description coverage already explaining the enum options. The description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides extra semantic value 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 it returns 'top tools, top packs, and total call volume over a recent window'. The verb 'returns' combined with specific resources (tools, packs) and scope (call volume) makes the purpose unambiguous, and it distinguishes itself from sibling tools by focusing on trending data from Pipeworx calls.

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 three explicit use cases (discovering hot data sources, confirming canonical choice, aligning use case). Mentions caching behavior and window selection guidance. However, does not explicitly state when NOT to use this tool or contrast with alternatives, leaving some ambiguity.

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, idempotentHint, openWorldHint as true, indicating safe, non-mutating behavior. The description adds behavioral context: scan modes, fill check, partition filters, semantic anchor, and conditions for null 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 long but well-structured with clear sections for each mode. It front-loads key information, though some technical details (e.g., 'slip_low_similarity surfaces the rejected pair count') are slightly verbose.

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

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

Given the complexity of multiple modes and no output schema, the description is thorough. It explains the response structure, fill check behavior, and conditions to avoid trading. All relevant behavioral details are covered.

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 descriptions already cover both parameters (100% coverage). The description adds significant nuance: for event mode it details partition checks and date-axis/threshold-axis ordering; for topic mode it explains cross-event matching with Jaccard similarity and missed patterns.

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 via monotonicity violations and partition-sum checks. It distinguishes three distinct modes (trending_scan, event, topic) and explains their use cases, differentiating from siblings like polymarket_edges.

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

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

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Warns about fill check conditions and 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?

Annotations indicate safe, read-only, idempotent behavior. The description adds significant detail beyond annotations: caching policy (1h KV), response segmentation, model family logic, edge calculation, and diagnostics for empty segments. 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 comprehensive but somewhat verbose. It effectively front-loads the purpose and uses structured segments (model families, response fields). While every sentence adds value, the length could be reduced slightly for faster parsing.

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 return structure: by_segment segments, fed_candidates, and _diagnostics. It details per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, etc.) and caching. This is complete for a complex tool with 9 parameters.

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 substantial meaning for each parameter: explains default values, how filters affect behavior, and context like slippage assumptions. For example, 'min_kelly' is explained as 'half-Kelly fraction... filter out opportunities too small to bet sensibly'.

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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes itself from sibling tools like 'polymarket_arbitrage' by focusing on disagreement-based opportunities and providing a specific use case ('what should I bet on today').

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 frames the tool as for discovering opportunities without paging hundreds of markets. It explains tradeable-edge knobs and their usage. However, it does not explicitly state when to use alternatives or conditions where this tool is not appropriate.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: 60-day snapshot TTL, data gaps when scans don't run, decay computed from daily closes (not intraday), and response structure. This enriches transparency 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 dense and well-structured, front-loading purpose then detailing args and response. It is not overly verbose but every sentence adds value. Slightly long but appropriate for the 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?

With no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and limitations (TTL, enablement start). It compensates well for the lack of a formal output schema. Minor gap: no example values.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds minor context (days default 14 max 30, window snapshot family), but does not add substantial meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering specific questions about edge longevity. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series decay rather than just listing edges.

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

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

The description implies use for understanding edge history and decay by saying 'a fresh wide edge and a 3-week-old wide edge are different trades', but it does not explicitly state when to use this vs alternatives like polymarket_edges. No when-not scenarios are 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 indicate readOnlyHint, openWorldHint, idempotentHint are true, and destructiveHint false. The description reinforces these by detailing it 'walks the ladder' and returns verdicts like clean/degraded/cannot_fill, without contradicting annotations. It adds behavioral context about basket mode risks (forced_directional_risk, thin_legs) beyond what annotations express.

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

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

The description is lengthy but efficiently front-loads the core purpose and mode distinction. Every sentence is informative, covering inputs, outputs, and usage guidance. Minor redundancy could be trimmed, but overall structure is logical and dense.

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

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

Given the tool's complexity (two modes, multiple return fields, no output schema), the description is remarkably complete. It enumerates all return values (top_of_book, vwap_fill_price, slippage_pp, etc.), explains basket-specific outputs (thin_legs, forced_directional_risk), and justifies usage context with concrete risk scenarios.

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

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

Schema coverage is 100%, but the description adds value by explaining default behaviors (e.g., size_usd default 1000, interpretation for buys vs sells, basket mode auto side detection). It clarifies parameter interactions (market vs event exclusivity) and provides context not in schema fields.

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 realizable-vs-theoretical edge check against live CLOB order-book depth. It specifies two modes (single-market and basket) with distinct parameters and returns. This distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly advises using this tool before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. It explains why (theoretical overround not capturable on thin books, partial fills convert arb to unhedged directional position), providing clear when-to-use and when-not-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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses numerous behavioral traits: compatibility warnings and codes, temporal alignment caveats, the policy of never pairing 'unknown' legs, skipped comparison counters, and the gross-fee limitation. This richly supplements 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 densely packed with pertinent information, and the core purpose is front-loaded in the first sentence. It could be better structured with bullets, but every sentence contributes operational or safety-relevant detail rather than padding.

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

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

Even without an output schema, the description thoroughly explains the response structure: per-venue prices, matched spreads, top_spreads_pp, fee disclosures, compatibility codes, skipped counters, and temporal alignment fields. It also sets expectations about how often real spreads occur, making it fully self-sufficient for an agent deciding to call and interpret the tool.

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

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

The schema already covers all three parameters at 100%, but the description adds meaningful semantics: the topic list is repeated in context, explicit ticker/slug parameters are explained as overrides, and the description notes that both modes run the same token-overlap matcher with identical disclosures. This goes beyond simple schema restatement.

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, unambiguous statement: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It further differentiates this tool from the Polymarket-only siblings by emphasizing the two-venue comparison and the 2-25pp pricing gap driven by differing participant pools.

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

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

The description clearly explains both usage modes — pre-mapped topic shortcuts versus explicit custom pairing — and states when each applies. It also gives strong contextual guidance with the warning that pre-mapped topics are not automatically tradeable, though it does not explicitly name alternative tools or state when not to use this one.

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 readOnlyHint, idempotentHint, destructiveHint. The description adds detail about listing behavior when key is omitted and scoping to identifier, supplementing the annotations effectively.

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

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

Three concise sentences that pack essential information. The purpose is front-loaded, and every sentence adds value without redundancy.

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

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

No output schema, but the description covers primary behaviors (retrieve and list). Lacks details on return format or size limits, but given the tool's simplicity, it is adequately complete.

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

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

Schema coverage is 100%, with a clear description for the 'key' parameter. The description adds context by giving examples of typical keys (ticker, address, notes), enhancing understanding beyond the schema.

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

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

The description clearly states the tool retrieves a value by key or lists all keys when omitted. It specifies 'retrieve' and 'list' as verbs and the resource as saved memories. It distinguishes itself from 'remember' and 'forget' by naming them.

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

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

Explicitly states when to use ('look up context stored earlier') and provides examples (ticker, address, research notes). It mentions scoping to an identifier and pairs with 'remember' and 'forget' as alternatives.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details: each alert carries source, citation_uri, raw payload; mark_read flags events as read. 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?

Two sentences pack purpose, return contents, filtering, mark_read behavior, and alternative endpoint. Front-loaded with core function. No filler.

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

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

Covers return fields, filtering, mark_read, and alternative access method. With 5 parameters and no output schema, it provides adequate context for an AI agent. Minor gap: does not specify ordering (most recent presumably descending).

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 meaning: gives example filter type 'sec_8k', explains ISO timestamp usage, and clarifies mark_read effect. This goes 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?

Clearly states the verb 'Pull' and resource 'events from your subscription feed.' Distinguishes from sibling tools like list_subscriptions and subscribe by focusing on retrieving the actual alerts. Also notes alternative HTTP endpoint for scripts/dashboards.

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 mentions that polling works and provides an alternative endpoint for scripts/dashboards, giving context on when to use this tool vs. other methods. Also explains mark_read behavior for incremental reads. Lacks explicit when-not-to-use scenarios.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds: parallel call, fan-out to multiple sources, fallback logic, relative date parsing, and soft-fail for USPTO. 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?

Well-structured: starts with purpose via example queries, then details sources, accepted formats, return structure, and ends with alternative tool. Every sentence adds value, no fluff.

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

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

Given complexity (multi-source, fallback, multiple date formats), description covers all aspects: sources, error handling, input formats, output structure. No output schema, but description sufficiently states return type (changes[] grouped by source, total count, URIs).

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?

All three parameters have schema descriptions (100% coverage). Description adds: 'type' only supports 'company', 'since' examples and relative formats ('7d', '30d', '3m', '1y'), 'value' accepts ticker or CIK. Adds meaningful usage context.

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

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

The description clearly states the tool retrieves 'what's new' for a company, listing sources (SEC, GDELT/GNews, USPTO) and return format. It distinguishes from sibling entity_profile by contrasting change feed vs static profile.

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

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

Explicit guidance: 'Use entity_profile instead when you want the static profile'. Also explains fallback behavior (GDELT→GNews) and soft-fail for USPTO. Recommends typical 'since' values ('30d' or '1m').

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

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

Annotations indicate idempotentHint=true and destructiveHint=false, and the description adds essential context: key-value storage scoped by agent identifier, with explicit lifetime details (persistent for authenticated, 24 hours for anonymous). No contradictions.

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

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

The description is concise (~100 words), well-structured with a logical flow: purpose, usage, behavioral details, sibling pairing. Every sentence adds value with no redundancy.

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

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

For a simple write tool with no output schema, the description adequately covers purpose, usage, and behavioral constraints. It could optionally mention overwrite behavior, but the idempotent hint and 'save' wording make it clear. Slightly incomplete regarding return or error handling, but acceptable.

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 key and value descriptions already well-defined. The description enhances meaning by tying parameters to use-case examples (e.g., 'resolved ticker' for key, 'findings' for value), helping the agent choose appropriate content.

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

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

The description starts with a clear verb+resource: 'Save data the agent will need to reuse later.' It explicitly distinguishes from sibling tools 'recall' and 'forget' by stating they are paired for retrieval and 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 specifies when to use: 'Use when you discover something worth carrying forward...' and provides concrete examples (resolved ticker, target address, user preference, research subject). It also clarifies scoping and persistence differences for authenticated vs. anonymous sessions.

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

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

The description goes well beyond the readOnly/idempotent/destructive annotations by disclosing graceful degradation when GLEIF or OpenFIGI is unavailable, the internal cascading lookup behavior, the exact sources (EDGAR, GLEIF, OpenFIGI, RxNorm), and coverage limits such as non-US issuers. This gives an agent a realistic model of what will happen at runtime.

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

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

The description is information-dense and every sentence contributes, but the single-paragraph structure with deeply nested parentheticals makes it harder to parse. A bulleted or sectioned layout would preserve the detail while improving scannability. It is thorough, not concise.

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

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

For a tool with no output schema, the description does a strong job of specifying both inputs and outputs: which identifiers are returned per entity type, which sources back them, how ISINs map to legal entities, and what happens when enrichment sources fail. It covers edge cases such as non-ticker securities and non-US issuers, making it complete enough for reliable 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?

Although the schema already covers both parameters at 100%, the description adds substantial meaning: it explains the company/drug type distinction, enumerates accepted value formats (ticker, CIK, ISIN, name), gives concrete examples like 'CH0038863350', and warns against passing full noun phrases for instrument lookups. This is exactly the kind of clarification that prevents incorrect invocations.

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 resolving a spoken or typed name into canonical identifiers (ticker, CIK, LEI, RxCUI, etc.) required by other tools. It is specific about the verb 'resolve' and the resource 'entities,' but it does not explicitly differentiate itself from sibling tools like entity_profile or compare_entities, so it stops short of a 5.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that the tool replaces 2-3 manual lookups, reinforcing its role as an upstream resolution step. However, it does not state when not to use it or name alternative tools for related but different tasks.

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

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

The description adds behavioral context beyond the annotations, such as treating the first entity as the subject, probing with ai_visibility_check, ranking by score, and returning score, confidence, and signal density. The annotations already indicate read-only, idempotent, and non-destructive nature, and the description does not contradict them.

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

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

The description is concise with four sentences, front-loading the main action, then explaining the process, use case, and output. Every sentence adds value with no fluff.

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

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

Given no output schema, the description describes the return format (ranked list with score, confidence, signal density). It also explains the composite nature (calls ai_visibility_check), the first-entity-as-subject convention, and the optional models parameter with the API key. It is fairly complete, though the number of entities constraint is only in 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 baseline is 3. The description adds meaning by explaining the order significance of the entities array (first is subject), the default model and API key requirement for the models parameter, and the disambiguation role of the context parameter, going beyond the schema details.

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: comparing AI visibility of multiple entities side-by-side by probing each with ai_visibility_check and ranking results. It distinguishes itself from its sibling ai_visibility_check by being a batch comparison tool, and explicitly mentions the use case of competitive AI-marketing audits.

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

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

The description indicates when to use this tool: for competitive audits comparing multiple brands. It implies that for single-entity checks, one should use ai_visibility_check. However, it does not explicitly state when not to use it or provide complete alternatives, but the context is clear enough.

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

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

The description adds significant behavioral context beyond the annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. Annotations already indicate read-only, idempotent, non-destructive behavior, and the description harmonizes with them.

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

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

The description is lengthy but every sentence provides necessary information. It uses bold for key terms and is well-structured, though slightly dense. Could be more concise, but the complexity of the tool justifies the 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?

Without an output schema, the description fully explains the return structure (summary block, per-advisory detail, links, alternative versions) and handles edge cases (partial failures, timeout). It is complete for a composite API call tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that scoped packages are accepted and that version defaults to latest when omitted. It also restricts to NPM ecosystem, which is not in the schema but is crucial for correct usage.

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

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

The description clearly states the tool's purpose: a composite check for npm packages combining deps.dev and bundlephobia data. It uses specific verbs ('scan', 'check') and resources ('npm package', 'deps.dev', 'bundlephobia'), and distinguishes from sibling tools by specifying ecosystem scope and alternatives for other package managers.

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

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

The description explicitly states when to use the tool: when an agent asks about safety, popularity, or cost of an npm package. It also provides exclusions: for PyPI/Maven/Cargo/Go, use deps.dev:version directly. This gives clear guidance on alternatives.

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

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

Annotations already indicate readOnlyHint, etc., but the description adds significant behavioral details: truncation at 200K chars with flag, embedding model (BGE-base-en), cosine similarity over 500-char overlapping windows. 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 front-loaded with purpose and usage, but includes some technical details (embedding model, window size) that could be considered slightly verbose. Still, every sentence adds value.

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

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

Given no output schema, the description explains return type (top-N passages with character offsets and similarity scores), covers limitations (200K cap, truncation flag), and mentions pairing with sibling tool. It is complete for an agent to use 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 baseline is 3. The description adds meaning beyond schema: explains each parameter's purpose (e.g., 'text' is the document to search, 'query' is natural-language query with examples) and clarifies limits (max 200K chars, default limit).

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

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

The description states a specific verb ('search') and resource ('inside a fetched record'), and distinguishes from siblings by contrasting with fetching whole documents and pairing with ask_pipeworx_grounded. It clearly explains what the tool does.

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

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

Explicitly states when to use ('when the record is too big to cram into the prompt'), what it saves (context), and mentions an alternative or complementary tool (ask_pipeworx_grounded). Also describes the return value (passages with offsets).

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 SMS cap and webhook auto-disable, but contradicts the idempotentHint=true annotation: creating a subscription is not idempotent (multiple calls create multiple subscriptions). Description does not address idempotency or explain side effects beyond the return value.

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

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

Well-structured with bullet points for types and delivery channels; all sentences add value. Slightly lengthy but justified due to 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?

Covers usage, requirements, limitations (SMS cap, account requirement, webhook auto-disable), and return value (subscription id). No output schema, but description compensates sufficiently 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?

Adds significant value beyond the input schema by detailing type-specific parameters (e.g., sec_8k items codes, polymarket topics) and delivery channel constraints (phone verification, webhook signing). Schema coverage is 100% and description enriches every 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?

Description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, recent_alerts by specifying the creation action and supported types.

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

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

Provides prerequisites (Pipeworx OAuth account, phone verification for SMS) and explains when to use (to subscribe to alerts). Implicitly compares to siblings via context, but lacks explicit when-not-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?

Description adds value beyond annotations by explaining output structure (category-bucketed examples with tool+argument shapes) and behavior (call with no arguments for full spread or with topic to focus). No contradictions with readOnlyHint, openWorldHint, idempotentHint, or destructiveHint.

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

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

The description is comprehensive yet efficient, starting with example intents, then explaining output and usage. Every sentence serves a purpose, and the structure guides the agent from general purpose to specific usage details.

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 fully explains what the tool returns (categories and examples with tool+argument shapes) and when to use it (first time or learning meta-tools). It covers the tool's role in onboarding without missing critical details.

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

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

Schema coverage is 100% with a clear description of the optional topic parameter. The description adds context on how to use the parameter ('focus') and lists possible values, which complements the schema's enumeration. It also explains default behavior (cross-category spread).

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

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

The description clearly states the tool returns category-bucketed example questions for various topics, acting as an onboarding entry point. It specifies the verb (returns) and resource (example questions), and distinguishes from sibling tools by being the first tool to call when unsure about Pipeworx's capabilities.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides example user intents ('what can I ask?') and explains how to focus with the topic parameter.

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?

Description reveals that the row is 'deactivated (not deleted)' and historical events remain available via recent_alerts. This adds value beyond annotations (destructiveHint=false, readOnlyHint=false), fully disclosing the behavioral traits.

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

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

Three concise sentences, each adding essential information: action, constraint, and side effect. No redundant words.

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

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

For a single-parameter write operation with destructiveHint=false, the description fully covers purpose, ownership constraint, and behavioral outcome. No output schema needed as side effect is clear.

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

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

Schema coverage is 100%, and description repeats the schema's parameter description ('Subscription id (uuid) returned by subscribe.'). No additional meaning beyond schema is provided, meeting the baseline.

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

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

Description clearly states 'Cancel a subscription by id.' The verb 'cancel' and resource 'subscription' are specific. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement: 'you can only cancel your own subscriptions.' This implicitly tells when not to use it. Could be improved by naming an alternative for canceling others' subscriptions, but still 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 readOnlyHint, openWorldHint, and idempotentHint, but the description adds substantial behavioral detail: could_not_verify means the check did not happen (with verification_error) and must not be treated as evidence; unsupported means no source covers it; it returns verbatim evidence with a pipeworx:// citation. This is far beyond what annotations provide and gives critical operational safety.

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

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

The description is long but each sentence earns its place: trigger phrases, routing logic, verdict list, and an important caller caveat are all included. It is front-loaded with usage examples and structured into a coherent paragraph. It could be slightly trimmed, but the density is warranted 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?

With no output schema, the description fully covers return values: verdict kinds, grounded/structured actual value with citation, reasoning, and the distinction between could_not_verify and unsupported. It also explains the internal paths and how the tool replaces multiple sequential calls. This gives a complete mental model, sufficient for effective invocation and interpretation.

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 guidance on tolerance_pct: recommending 1–2% for hallucination detection and explaining the default (implied by wording, capped at 5). This extra context helps the agent choose and adjust parameters, so a 4 is justified.

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 natural-language claim verification and trigger phrases like 'fact check' and 'confirm or refute,' making the verb/resource explicit. It distinguishes this tool from generic search/research siblings by focusing on issuing a verdict with evidence, and it explains the two-tier pipeline (structured SEC fast path vs grounded pipeline) that is unique to this tool.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and clarifies when the structured path applies (company-financial claims) vs the grounded path (all other claims). However, it does not explicitly name alternative tools for non-claim tasks, nor does it provide exclusions, so it falls short of a 5.

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