Brreg No

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context about cost implications (BYO Anthropic key, direct payment) and the default free model, which goes beyond the structured metadata.

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

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

Four sentences, each conveying essential information: core function, model defaults and key requirements, return structure, and use cases. No redundancy or filler.

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

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

Despite no output schema, the description specifies the return format (per-model {score, confidence, signals, raw_response} + combined view), making the tool's behavior fully understandable for an agent. Annotations cover safety, and schema covers inputs; no critical gaps remain.

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

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

Schema covers all 4 parameters with detailed descriptions. The description adds nuance by explaining the default model behavior and emphasizing the BYO-key cost implication for _apiKey, enhancing the semantic meaning beyond the schema.

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

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

The description uses specific verbs ('Probe', 'score') and clearly identifies the resource ('LLMs', 'business/brand/product/topic'). It distinguishes itself from sibling tools by focusing on AI visibility scoring with per-model output.

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

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

Provides clear usage contexts ('AI-marketing audits, pre-launch brand checks, competitive monitoring') that imply when to use. Does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to differentiate from siblings like scan_competitor_ai_presence.

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 meaningful context: it's the default entry point, works on every tier, one fast call, routes to 5,347 tools across 1,393 sources, fills arguments, and returns stable pipeworx:// citation URIs. It also explains its live-news routing behavior explicitly. This adds substantial value beyond the safety 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 front-loaded with the most critical instruction ('PREFER OVER WEB SEARCH') and the core purpose, then expands into domains, usage signals, examples, and escalation path. It's longer than the calibration examples but every sentence earns its place — the domain list, trigger phrases, examples, and sibling differentiation are all actionable. Slightly long but appropriately 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 this is a routing/orchestration tool with 6 parameters (mostly aliases), no output schema, and rich annotations, the description is remarkably complete. It covers when to use, when not to use (when to step up), what it returns (structured answer with citation URIs), and handles edge cases (breaking news, free-tier deep_research). The only minor gap is no explicit mention of rate limits or quota considerations beyond 'one fast call', but this is a minor omission for a read-only routing 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% since the single 'question' parameter plus its aliases (q, text, input, query, prompt) are all documented in the schema. The description adds meaningful usage context by explaining the tool 'fills arguments' automatically — implying the user need not enumerate parameters, just ask a natural-language question. The heavy lifting is done by the schema, but the description clarifies the user-facing contract (natural language in, structured answer out).

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 routes factual questions to verified data sources and returns structured answers with citations. It names specific domains (SEC, FDA, FRED/BLS, patents, real estate, weather, clinical trials, news, stocks, crypto, sports, academic papers) and provides concrete examples like 'current US unemployment rate' and 'Apple's latest 10-K'. This distinguishes it sharply from the intended web search alternative and sibling tools.

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

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

The description gives explicit 'PREFER OVER WEB SEARCH' instruction with a clear boundary, lists the exact trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), and names two alternative tools (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part fan-out) with explicit 'step up only when needed' guidance. It even addresses the breaking-news edge case explaining how ask_pipeworx handles it.

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

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

Despite rich annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true), the description adds substantial context: it's a full working router with no fallback, and routing improvements are conditionally active/retired on outcome evidence. This explains the experimental nature beyond what annotations convey, including the current inactive state detail. No contradiction with annotations.

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

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

Three sentences, each earning its place: identifies the beta nature, explains current state, and gives usage direction with fallback clarification. Slightly longer than minimal but every clause serves a purpose — the detail about retired candidates and merge-compare logic is genuinely useful, not filler.

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

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

For a question-routing tool with rich annotations covering safety (read-only, idempotent) and 100% schema coverage on parameters, the description fully addresses the experimental-vs-stable distinction, current router state, and usage equivalence. No output schema exists, but as a router the response shape is clarified as identical to ask_pipeworx. Complete for the tool's complexity.

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

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

Schema coverage is 100% — all 6 parameters are documented with descriptions (question plus 5 aliases). The description adds no parameter-specific detail beyond what the schema provides, which matches the baseline of 3 when the schema carries the full load.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes from the sibling ask_pipeworx as the experimental edge while explicitly noting it currently matches the stable version. Specific verb+resource with strong scoping.

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 it exactly like ask_pipeworx when you want the newest routing.' It explains the purpose (results compared against stable router for merge decisions) and notes there's no active candidate currently. Clear when-to-use framing with context on the fallback behavior.

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 non-destructive, so the safety profile is covered. The description adds substantial behavioral context BEYOND annotations: exact return value shape ({answer, evidence, confidence, source, fetched_at}), the explicit refusal format with all possible refusal_reason enum values, and the mechanism (extracts ONLY from tool result). This is rich, actionable behavioral disclosure.

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 each sentence earns its place—purpose, mechanism, return format, refusal format, usage guidance, and cost tradeoff all in one paragraph. It's somewhat long but every clause adds distinct value. Slightly front-loads the core purpose before diving into return shapes and refusal reasons.

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 carries the full burden of explaining return values, and it does so thoroughly: success shape, refusal shape, all refusal reasons, evidence style (verbatim quote). For a high-stakes grounded-answer tool with six alias parameters and no output schema, this description is complete and leaves no critical ambiguity.

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

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

Schema coverage is 100%, so the schema fully documents all 6 parameters. However, the description adds value by framing the question as 'natural language' and explicitly noting the alias relationships, which helps the agent know all six params are interchangeable aliases for the same semantic input. This exceeds the bare schema baseline, though it doesn't need to do much beyond what 100% coverage already provides.

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

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

The description is highly specific: it identifies the verb ('EXTRACTS'), the resource (Pipeworx tool routing across 5,347 tools / 1393 sources), the distinguishing mechanism (grounded/hallucination-resistant extraction using only tool output). It clearly differentiates from sibling ask_pipeworx by specifying the exact behavioral difference (grounded extraction vs casual lookup).

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

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

The description explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and explicitly tells when NOT to use it, pointing to the cheaper alternative ('prefer ask_pipeworx for casual lookups'). It also names the specific cost tradeoff ('Costs one extra LLM call'). This is exemplary 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?

Despite annotations already declaring readOnly, idempotent, and non-destructive behavior, the description goes far beyond with critical behavioral context: low-confidence short-circuiting, closed-market status handling, wide-spread illiquidity flags, resolution-rule risk (flat 50¢ void settlements), fan-out patterns, and news fallback behavior. No contradiction with annotations.

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

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

The description is long but well-structured with clear header labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and is front-loaded with purpose in the first sentence. Minor redundancy (explaining the low_confidence_match path in both SAFETY and the resolver contract) prevents a perfect score.

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

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

With no output schema present, the description fully discloses response shapes (result.market, result.analysis, result.evidence), the resolver contract, parent event extractor, news fields, safety guards, and resolution-rule risk. It provides enough detail for an agent to know what to expect and how to interpret results, making it exceptionally complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description's first sentpence restates the market parameter format (slug, URL, or question text) which the schema already documents. It adds no syntax or semantic details beyond the schema, though the fan-out examples provide some context on how the market input influences classification.

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 ('Research'), identifies the resource ('Polymarket bet'), and explains the mechanism ('pulling relevant Pipeworx data... in one call'). It explicitly lists common use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), clearly distinguishing this tool from sibling research tools like ask_pipeworx or polymarket_edges.

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

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

The description provides explicit use cases ('Use for...') and internal guidance (always inspect match confidence before trusting analysis, check cancellation rule before sizing). However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of full when/when-not coverage.

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?

Goes well beyond annotations by disclosing data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and the return of paired data with pipeworx:// citation URIs. No contradiction with annotations.

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

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

The description is packed with valuable information, each sentence contributing something (triggers, scope, data sources, sorting, output, efficiency). It is well-structured with clear sections, making it easy to parse despite its length.

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

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

Given no output schema, the description still explains what the response will include (paired data + citation URIs). It covers input format, data sources, sorting behavior, and why to prefer this tool, making it complete for an agent to judge 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 schema coverage is 100%, the description enhances both parameters: type is expanded with specific data pulled per entity type, and values is enriched with formatting examples (tickers/CIKs for company, names for drug).

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: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It also provides trigger phrases and distinguishes itself from sequential single-pack lookups, making it unambiguous versus sibling tools.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and gives concrete example queries. It also clarifies type-specific usage (company vs drug), leaving no doubt about when to apply this tool.

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

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

Although annotations already declare readOnlyHint=true and idempotentHint=true, the description adds substantial behavioral context: requires an account (free sign-in, paid plan for thorough), is NOT open-web search (only 1393 structured sources), never invents data (gaps[]), expects 15-90s latency, and details second-hop iteration behavior (gap recovery, contradictions scan, hop fields). This goes well beyond the annotations.

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

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

The description is dense and information-rich but long — roughly 200 words in a single paragraph without structural breaks. While every sentence earns its place (account requirements, when-not-to-use, second-hop behavior, latency, citation format), the wall-of-text format reduces scannability. Front-loads the critical account requirement first, which is good. Could benefit from segmenting into bullet-like clarity without necessarily cutting content.

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

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

For a tool with no output schema and no nested objects, the description carries the full burden of explaining return structure and behavior, and it does: findings packet (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), gaps[], contradictions[], hop field, and citation_uri behavior. With only 2 parameters and 100% schema coverage, the description fully compensates and exceeds expectations for such a complex research tool.

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

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

Schema coverage is 100% and the depth parameter has rich enum descriptions in the schema. The description adds further nuance: depth:'standard' re-angles unanswered gaps, depth:'thorough' additionally chases leads, and clarifies the 'thorough' paid requirement. The question parameter is described as 'Broad/multi-part is fine — decomposition is the point' which enriches the schema's 'natural language' note. Marginal value beyond already-thorough schema, hence 4 not 5.

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

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

The description clearly states what the tool does: 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources... in ONE call'. It uses specific verbs (decomposes, routes, returns) and explicitly distinguishes itself from open-web search and from sibling ask_pipeworx. The scope (broad/multi-part questions over structured data) is precisely defined.

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?

Exceptionally explicit about when to use vs not use: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. Names the alternative tools and gives the exact conditions for each.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral details beyond these: it returns top-N tools with names, descriptions, and full input schemas, and results are 'ready to call directly, no second schema lookup needed.' This clarifies return formatting and usability 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 compact and front-loaded with the core purpose. It efficiently expands with domain examples, return details, and usage guidance in three sentences. 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?

Given the tool's meta-purpose and no output schema, the description sufficiently conveys return value (top-N tools with schemas), usage context (discovery), and relationship to the large sibling set. It is complete for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing a concrete list of example domains (SEC filings, FDA drugs, etc.) that help the agent formulate effective natural-language queries. It also clarifies the return limitation (top-N) and aliases mention in schema, though the schema already covers field 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 purpose: 'Find tools by describing the data or task.' It distinguishes itself from siblings by explicitly listing covered domains and emphasizing the discovery/option-set use case ('Call this FIRST...'). This is a specific verb+resource with clear differentiation.

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

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

It provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This implies a when-not (when you need a specific answer, use another tool) and gives context for choosing it over siblings.

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

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

Beyond the readOnly/idempotent annotations, the description discloses concrete behaviors: fans out across SEC, XBRL, USPTO, news, GLEIF; includes specific return fields and URI patterns; notes USPTO PatentsView API sunset May 2025 with soft-fail; describes GDELT→GNews fallback; and requires ticker or zero-padded CIK. No contradiction with annotations.

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

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

The description is long but densely informative. It is front-loaded with example user intents, then states the core value, lists data sources and return fields, and ends with input constraints. Every sentence earns its place, though it could be slightly trimmed without losing value.

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

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

Given there is no output schema, the description fully compensates by detailing exact return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), behavioral nuances (soft-fail, fallback), and input constraints. It is complete enough 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 already covers both params with descriptions (100% coverage). The description adds extra meaning: zero-padded CIK format, examples (AAPL, 0000320193), and reiterates the name limitation with a pointer to resolve_entity. This goes beyond the schema's basic description.

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

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

The description clearly states the tool creates a full cross-source profile of a US public company in one parallel call, with multiple example prompts ('Tell me about X', 'research Acme', etc.). It differentiates from siblings by explicitly naming the alternative (resolve_entity) and the single-pack lookups it replaces.

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

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

Provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives an exclusion: 'names not supported (use resolve_entity first if you only have a name).' This clearly defines when to use this tool vs alternatives.

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

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

Annotations already disclose destructiveHint=true and idempotentHint=true. The description adds little behavioral context beyond stating deletion, and does not mention irreversibility or behavior for missing keys. It does add the use case of clearing sensitive data, which is useful but not a major behavioral trait. With annotations covering the safety profile, a score of 3 is appropriate.

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

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

Three concise sentences: the first states the action, the second gives usage conditions, the third links to related tools. No fluff, front-loaded purpose, 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 1-parameter destructive operation with annotations covering safety and idempotency, the description fully covers what is needed: what it deletes, when to use it, and related tools. No output schema is required, and the description is complete.

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

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

Schema description coverage is 100% (the key parameter is described as 'Memory key to delete'). The description reinforces this by mentioning 'by key' but does not add substantive meaning beyond the schema. Baseline of 3 is correct.

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: 'Delete a previously stored memory by key.' This is a specific verb (Delete) + resource (previously stored memory) + method (by key). It also distinguishes from siblings by mentioning 'remember' and 'recall' as counterparts, making the purpose clear.

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

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

The description provides explicit when-to-use scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also names alternatives/related tools ('Pair with remember and recall'). However, it lacks explicit when-not-to-use guidance, so a perfect 5 is not warranted.

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 readOnly, openWorld, idempotent, non-destructive hints. The description adds valuable context: it fetches the page, extracts title/description/links, and outputs a text blob. This clarifies the network fetch behavior and output format beyond what annotations convey.

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

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

The description is three sentences, front-loaded with the core purpose, followed by the process and use cases. Every sentence earns its place with no redundancy or fluff, 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?

For a simple tool with 2 well-described parameters, strong annotations, and no output schema, the description covers everything needed: purpose, process, output format, and use cases. An agent can confidently select and invoke this tool without further clarification.

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

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

The input schema has 100% description coverage, documenting both 'url' and 'max_links' with clear descriptions. The tool description does not add any parameter-specific semantics, so the baseline of 3 applies.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with the specific verb 'generate' and resource 'llms.txt'. It uniquely distinguishes this tool from all siblings, none of which target llms.txt generation.

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

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

The description lists concrete use cases (getting a client's site indexed, drafting llms.txt, auditing competitor AI crawling) which guide when to use the tool. However, it does not explicitly mention exclusions or alternatives, so it misses the 'when-not' component for a perfect score.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context about return shape (array, one element per filed year) and the specific financial fields included, helping the agent set expectations. No additional edge-case behavior is disclosed, but annotations cover safety profile.

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

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

Two well-structured sentences with a concrete example. The main purpose is front-loaded, and every sentence contributes useful information without redundancy.

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

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

For a simple single-parameter tool with no output schema, the description covers the key aspects: source, input example, and return structure. It does not specify behavior for missing or invalid org numbers or empty results, but these are minor gaps given the tool's simplicity.

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

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

Schema coverage is 100% with a clear description for orgnr, so the parameter is fully documented. The description repeats the example without adding significant new meaning beyond the schema. Baseline of 3 is appropriate for high 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?

Clearly states the tool retrieves annual financial statements for an entity by 9-digit org number, specifying the resource and scope precisely. This distinguishes it from sibling get_* tools like get_entity, which would return general entity information.

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

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

The description implicitly conveys when to use the tool: whenever financial statements are needed for a given org number. It does not explicitly contrast with alternatives or mention exclusions, but the specificity makes the use case obvious. Lacks explicit when-not-to-use guidance, preventing a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering the safety profile. The description adds value by listing the returned fields (navn, organisasjonsform, etc.) and providing an example, which is not present in the input schema. This clarifies what the agent can expect in the response.

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, front-loaded with the core purpose, and uses a compact example. No filler or redundant phrasing.

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

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

For a simple one-parameter read-only lookup, the description covers the purpose, parameter format, and sample output fields. Without an output schema, it lists key return fields, which is sufficient for agent invocation. A minor gap is lack of explicit mention of error cases or prerequisites, but these are not critical for such a straightforward 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 single parameter orgnr is fully described in the schema (100% coverage) with the same 9-digit format and example. The description's repetition adds no new syntactic details, though the Equinor ASA example gives a concrete real-world instance.

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 the full record for one entity identified by a 9-digit org number, with a concrete example (Equinor ASA). This distinguishes it from sibling tools like search_entities or compare_entities.

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

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

The description implies the intended use case (lookup by org number) but does not explicitly contrast with alternatives such as search_entities or get_sub_entity. There is no when-to-use vs when-not-to-use guidance beyond the narrow focus on a single org number.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the description doesn't need to restate safety. It adds domain context (types of roles) but no additional behavioral traits such as return format, pagination, or error handling. Given the annotations, this is adequate but not rich.

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

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

The description is one concise sentence with an inline example. It is front-loaded with the core purpose, and every word adds value. No fluff or repetition.

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

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

The tool is simple (one parameter) and has no output schema. The description explains what roles are returned but not the exact response structure (e.g., list of strings, objects with names) or behavior on invalid org numbers. Given the absence of an output schema, the description could be more complete but is sufficient for a basic read operation.

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

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

The input schema already provides full coverage (100%) for the single parameter 'orgnr' with description and example. The tool description reinforces this with an example and the '9-digit org number' context, but adds little beyond what the schema states. 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 that the tool returns roles for an entity (board members, CEO, chair, auditor, etc.) identified by a 9-digit org number. The verb 'get' is in the title, and the resource 'roles' is specific. It doesn't explicitly differentiate from sibling tools like get_entity or get_accounts, but the focus on roles is distinctive enough.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention scenarios where it should be preferred, nor does it reference sibling tools like entity_profile or get_entity for related but different information. The agent is left to infer usage from the name and description alone.

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, which covers the safety profile. The description adds the 'full record' scope but does not disclose additional behavioral traits such as response structure, potential errors, or rate limits. It neither contradicts nor significantly extends the annotations, so a score of 3 is appropriate.

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

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

The description is a single, front-loaded sentence with a practical example, containing no redundant information. Every element (purpose, input format, example) earns its place, making it highly efficient and easy to parse.

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

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

With one parameter, rich annotations, and no output schema, the description is mostly complete. It specifies the input and the goal ('full record') but does not detail what the full record contains or handle edge cases. Given the tool's simplicity, this is a minor gap, so a score of 4 is justified.

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 describes the 'orgnr' parameter with 100% coverage, including the 9-digit format and an example. The description adds an additional example but no new meaning beyond what the schema provides. Given the high schema coverage, the baseline of 3 is retained.

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: retrieving the full record for a single sub-entity/branch by its 9-digit org number. It includes a concrete example (Equinor ASA AVD CCB SOTRA) that reinforces the specific resource type, distinguishing it from sibling tools like get_entity (which targets main entities) and search_sub_entities (which searches rather than retrieves a single record).

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

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

The description provides clear context: use this when you have a specific 9-digit sub-entity org number and need the full record. It implies the tool is for exact lookups rather than searches, though it does not explicitly mention alternatives or exclusions. The example further clarifies the expected input format and usage scenario.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context by listing the return fields (id, type, params, etc.) and clarifying that only active subscriptions are listed by default, which complements the annotations without contradiction.

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

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

The description is two concise sentences, with the primary purpose front-loaded and no unnecessary filler. Every sentence adds value: the first explains what it does and returns, the second explains when to use it.

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 read tool with no output schema, the description provides all essential context: it lists return fields, specifies the default behavior (active only), and gives usage examples. This is complete enough for an agent to select and invoke the tool correctly.

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

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

The schema fully describes the single parameter include_inactive with a clear description ('Include cancelled subscriptions in the response (default false).'). The description doesn't add further parameter info, but given the 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'List the caller's active subscriptions' with a specific verb and resource. It also distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing rather than modifying.

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to employ the tool, though it doesn't explicitly exclude alternatives or mention when not to use it.

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

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

Annotations provide no safety hints (all false), so the description must carry the behavioral disclosure. It does so thoroughly: 'Rate-limited to 5 per identifier per day,' 'Free; doesn't count against your tool-call quota,' 'The team reads digests daily and signal directly affects roadmap.' These are substantive behavioral traits beyond the annotations. No contradiction exists.

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

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

The description is concise at six short sentences, each contributing distinct value: purpose, usage conditions, content guidance, team impact, rate limit, and quota. It is front-loaded with the core purpose and avoids redundancy. No filler or repetition of schema 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 having no output schema, the description is fully sufficient for a feedback tool. It explains what the tool does, when to use it, how to format input, and key behavioral constraints (rate limit, quota). The optional context object is not explicitly mentioned, but the schema covers it. The description is complete for an agent to correctly select and 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%, so the baseline is 3. The description adds extra value by mapping feedback types to conditions (bug→wrong/stale data, etc.) and by instructing message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This goes beyond the schema's field descriptions, meriting a 4.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific feedback types (bug, feature/data_gap, praise), which distinguishes it from sibling query/research tools. The verb 'Tell' and resource 'Pipeworx team' make the action and target explicit.

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

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

The description provides explicit when-to-use conditions: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives guidance on what to avoid ('don't paste the end-user's prompt') and how to frame feedback ('in terms of Pipeworx tools/packs'). This fully substitutes for any alternative tool 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?

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds valuable context beyond these: it states the data is 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count).' It also discloses caching behavior ('Cached 5min-1h depending on window'). This gives the agent a clear understanding of data freshness, privacy, and output shape, which is not present in 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 efficiently structured: a one-sentence core purpose, a concise list of use cases, and a brief technical note on data source and caching. Every sentence adds information, and there is zero redundant fluff. It is front-loaded with the most important information.

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

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

For a simple tool with one optional parameter, the description covers all necessary context: what it returns (top tools, top packs, call volume), the window options, use cases, data provenance, privacy (no PII), and caching. Although there is no output schema, the description explicitly states the output shape ('just (pack, tool, count)'). The annotations handle safety semantics. This is fully complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%: the window parameter is described with its enum values and the semantic difference between short and long windows ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description merely repeats the window options without adding new meaning. Per the rubric, baseline 3 is appropriate when schema handles 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 opens with a clear, specific statement: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' The verb 'Returns' plus the resource (top tools/packs/call volume) makes the function's behavior unambiguous. It also distinguishes itself from siblings like ask_pipeworx or discover_tools by focusing on aggregate call statistics from other agents, which is a unique niche.

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 three explicit use cases: discovering hot data sources, confirming a canonical tool before asking, and checking alignment with most agents' needs. These are concrete and actionable. However, it does not explicitly mention alternatives or when not to use the tool, so it falls short of a perfect 5 which requires explicit when/when-not/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 read-only/idempotent/non-destructive, but the description adds substantial behavioral detail: exact thresholds (3pp deviation, ≥0.30 Jaccard, >20% placeholder fraction), the fill_check behavior (realizable_edge_pp ≤ 0 means do not trade), and the partition_filter's null-arb return. No contradiction with annotations.

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

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

The description is long and dense, but it is front-loaded with the core purpose and modes, and uses clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Some content repeats schema examples, but every section earns its place for a complex tool with three modes and multiple edge cases.

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 defines the response structure (opportunities[], partition_check fields), explains critical failure modes (placeholder filter returns null, fill check rejects unrealizable edges), and cross-references polymarket_fill_risk for custom sizing. This is comprehensive for a tool with this complexity.

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

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

Schema descriptions already define both parameters with examples and guidance. The description adds the no-args mode semantics and elaborates on how event and topic modes differ (e.g., walks child markets vs. flattens related events), but most parameter meaning is already in the schema, so the increment is moderate.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (no-arg trending scan, event, topic) and names polymarket_fill_risk as the alternative for custom sizing, making it distinct from siblings.

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

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

Provides explicit when-to-use instructions: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'pass topic for a themed cross-event scan.' It also recommends event for specific markets, explains what cross-event mode catches that single-event misses, and points to polymarket_fill_risk for custom sizing.

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

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

The description goes far beyond the readOnly/idempotent annotations, detailing model families, output segments, diagnostics, caching ('Cached 1h at the KV level'), edge warnings ('your edge may already be in the price'), and why Fed bets are excluded. This is rich behavioral disclosure.

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 long and dense, using uppercase headers to structure but still overloading with technical details, model parameters, and examples. While organized, it is not concise and could be trimmed to improve quick comprehension.

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

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

Given the tool's complexity, no output schema, and multiple model families, the description fully covers the response structure (by_segment, fed_candidates, diagnostics), caveats, and edge cases like empty segments. It leaves little ambiguity for an agent to understand what the tool returns.

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 detailed descriptions, but the tool description adds crucial behavioral nuance beyond the schema, such as why min_kelly never filters partition arbs ('partition arbs always return kelly_fraction_half=0 at the parent level by design') and the rationale for slippage defaults.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly differentiates the tool from sibling Polymarket tools like polymarket_arbitrage or polymarket_edge_tracker, focusing on data-driven disagreement discovery.

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

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

Provides clear usage context: 'Built for "what should I bet on today"' and explains parameter knobs like slippage and tradeable-edge filters ('Bump for very thin partitions; drop to 0 if you have a smarter fill model'). However, it does not explicitly discuss when not to use this tool or alternatives to prefer.

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

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

Annotations already mark readOnlyHint and idempotentHint, so the description builds on that by detailing the response structure (tracked, expired, snapshot_dates) and key limitations: the 60-day TTL, dependence on snapshotting enablement, and that decay is based on daily closes, not intraday. It also explains cache-miss behavior for gaps.

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

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

Despite being relatively long, the description is well-structured with explicit 'Args:', 'RESPONSE:', and 'LIMITS:' sections. Every sentence contributes unique information about purpose, parameters, response format, or limitations, and it is front-loaded with the core value proposition.

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 return payload (tracked, expired, snapshot_dates), including field semantics and edge cases (negative values for SELL YES, median lifespan as competition clock). It also covers data availability caveats and TTL, making the tool's behavior fully comprehensible.

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

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

Schema coverage is 100%, and both parameters have descriptions with defaults. The tool description essentially restates the schema information ('days (lookback, default 14, max 30)', 'window (snapshot family, default "1wk")') without adding new meaning or clarification, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers the tool's core question ('how long has this edge existed and is it shrinking?') and distinguishes it from siblings like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

The description provides clear context on when to use the tool: when you need to know edge persistence/decay ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly name alternatives or exclusions, but the purpose statement and the contrast with fresh edges imply when this tool is relevant.

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

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

Annotations already establish read-only/idempotent safety, and the description adds rich behavioral context: it walks the order-book ladder, returns specific fields like slippage_pp and max_fillable_usd, and warns that partial basket fills convert an arb into unhedged directional risk. This goes far beyond the annotation hints and discloses the dominant loss mode.

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

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

The description is long but every sentence carries essential information for a complex two-mode tool. It is front-loaded with the core purpose, then clearly sections SINGLE-MARKET and BASKET, followed by explicit usage directives. No filler; each clause 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?

Despite having no output schema, the description enumerates the return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers parameter modes, defaults, clamps, and the critical failure mode, making the tool fully self-explanatory.

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 extra meaning by explaining that basket sell_yes captures overround and buy_yes captures underround, and clarifies size_usd defaults in each mode. While some of this duplicates the schema, the overround/underround interpretation adds value beyond the schema descriptions.

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

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

The description opens with a specific verb and resource: "Realizable-vs-theoretical edge check against live CLOB order-book depth." It clearly distinguishes between single-market and basket modes, and frames the tool as a pre-trade risk check. This differentiates it from siblings like polymarket_arbitrage and polymarket_edges by stating it checks fill risk rather than finding 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 when-to-use guidance is provided: "USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500." It also explains the risk of not using it (theoretical overround on thin books is not capturable, partial fills create unhedged positions), giving clear context for alternatives.

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

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

Despite annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description goes far beyond by disclosing response structure, compatibility_warning conditions, temporal_alignment implications, and skipped_cross_type/subtype counters. This adds substantial behavioral context not available in 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?

Although long, the description is meticulously structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. Every sentence conveys a distinct operational detail, and the final caution about pre-mapped vs tradeable adds value. No filler text.

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

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

With no output schema, the description fully explains the response format (leg-by-leg prices, spread[].top_spreads_pp), the compatibility_warning logic, temporal alignment checks, and skipped counters. It is self-sufficient for an agent to invoke the tool and interpret results correctly, even for edge cases.

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

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

The input schema already covers 100% of parameters with meaningful descriptions (e.g., topic lists all values, explicit tickers note override behavior). The description repeats this information but does not add new parameter-level semantics beyond the schema. Baseline 3 is appropriate given high 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 opens with a specific, differentiated statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly scopes the tool's function (spread computation) and distinguishes it from sibling tools like polymarket_arbitrage by emphasizing cross-venue comparison and safety filters.

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?

Clear context is provided for when to use the tool: comparing same-resolution events across venues, with two modes (topic shortcuts vs explicit tickers). It also warns that most pre-mapped topics return compatibility warnings and are not tradeable. However, it does not explicitly name alternative tools or state when-not-to-use in favor of siblings, so it lacks full exclusion guidance.

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

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

Annotations already declare the tool as read-only and idempotent. The description adds the scoping detail ('anonymous IP, BYO key hash, or account ID'), providing useful behavioral context beyond annotations. No contradictions or hidden behaviors.

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

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

Three sentences, front-loaded with the primary action, then context, then related tools. No wasted words; every sentence serves a purpose.

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

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

The description fully covers the tool's use cases, scope, and relationship to siblings for a simple retrieve/list operation. No output schema means return values don't need detailing, and 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?

The schema already documents the single `key` parameter with 100% coverage. The description supplements this by explaining the optionality: omitting the key lists all saved keys, adding behavioral semantics to the parameter.

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

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

The description uses specific verbs 'Retrieve' and 'list' with a clear resource: saved memory values. It explicitly differentiates from sibling tools by naming 'remember' and 'forget' and describing the pairing.

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 to look up context the agent stored earlier' and provides concrete examples (ticker, address, research notes). It names alternative tools for related actions (remember/forget), giving clear context and alternatives.

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

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

Annotations declare readOnlyHint=true, but the description explicitly states that setting mark_read:true flags events read and affects subsequent calls, which is a write/modification behavior. This directly contradicts the read-only annotation, creating a serious inconsistency. No compensatory behavioral detail is provided.

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

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

The description is three sentences long, front-loaded with the core action, and each sentence adds meaningful details (return contents, filtering, mark_read, alternative URL). No redundant or verbose text.

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 read/list tool with no output schema, the description covers the return payload contents, filtering options, mark_read side effects, polling suitability, and an alternative endpoint. It is thorough and standalone, aside from the annotation contradiction.

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

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

Schema already covers all 100% of parameters. The description adds value by providing a concrete example ('sec_8k'), clarifying the ISO timestamp format for 'since', and explaining the semantic effect of mark_read on future calls. This enriches 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?

Description uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), clearly identifying the tool's function. It also distinguishes it from sibling tools by focusing on alert retrieval rather than subscription management.

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

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

Provides clear context for use: retrieving recent alerts, filtering by type/since, and marking read. It also mentions an alternative HTTP endpoint for scripts/dashboards, which is an exclusion of sorts. However, it does not explicitly contrast with any sibling tools or state when not to use it.

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

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

The description discloses rich behavioral details beyond the annotations: fan-out to SEC EDGAR, GDELT→GNews fallback with specific failure conditions, and USPTO soft-fail due to PatentsView API sunset. It also describes return structure (changes[], total_changes, citation URIs). No contradiction with readOnly/idempotent/non-destructive 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 section contributes: query intents, source behavior, fallback logic, parameter formats, return shape, and alternative tool. It is front-loaded with examples and dense, though slightly compressible.

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 multi-source tool with no output schema, the description fully explains return values (changes[] grouped by source, total_changes, pipeworx:// URIs) and caveats like the PatentsView sunset. It also provides an alternative usage path and parameter guidance, making it self-sufficient.

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, but the description adds meaningful semantics for the `since` parameter: ISO date vs relative shorthand with concrete examples ('7d', '30d', '3m', '1y') and a recommendation. Type and value are already well-documented in the schema, so no extra needed there.

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

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

The description clearly defines a change-feed tool for a company over a configurable time window, with explicit query examples like 'What's new with X' and 'latest on Y'. It distinguishes itself from entity_profile by specifying that the latter is for static profiles regardless of window.

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 entity_profile instead (when static profile is needed regardless of window), providing a clear alternative. It also gives usage context such as typical monitoring windows ('30d' or '1m') and explains the parallel fan-out behavior.

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 convey readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond annotations: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This explains persistence and scoping without contradicting the annotations.

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

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

The description is three sentences, front-loaded with the primary purpose, and every sentence adds value: purpose, usage guidance, storage/persistence details, and sibling tool pairing. No unnecessary words or repetition.

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?

This is a simple tool with 2 parameters and no output schema. The description covers purpose, when to use, persistence details, and relationship with recall/forget. It does not mention return values, but for a save operation this is not a significant gap given the tool's simplicity.

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

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

Schema description coverage is 100% for both parameters (key and value), each with examples. The description's mention of 'key-value pair' reinforces the schema but adds no new parameter-level details beyond what the schema already 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's purpose: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It uses a specific verb (save) and resource (data to reuse), and distinguishes itself from sibling tools by saying 'Pair with recall to retrieve later, forget to delete.'

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 context: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject).' It also mentions alternatives (recall and forget) but does not explicitly state when not to use this tool, so it lacks full exclusion criteria.

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

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

Beyond annotations (read-only, idempotent), the description reveals internal cascading through endpoints, auto-disambiguation, data sources (SEC EDGAR, RxNorm), and citation URIs. This adds meaningful behavioral context, though it doesn't cover error cases or rate limits.

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

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

The description is moderately long but well-organized with query examples, SUPPORTED TYPES, and a closing efficiency note. Every sentence contributes value; 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?

With no output schema, the description compensates by listing return fields for each type (ticker, CIK, company_name; RxCUI, ingredient, brand) plus citation URIs. Covers input handling and internal behavior, but could more explicitly describe the output object structure.

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 enriches parameter meaning by detailing what each 'type' returns and accepted input formats (ticker, CIK, name for company; brand/generic for drug). Adds auto-disambiguation detail beyond schema.

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

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

The description clearly states the tool resolves names to canonical identifiers, with a specific verb 'resolve' and resource (entity). It distinguishes from siblings by explicitly saying 'Use FIRST whenever you have a name but need an ID' and listing supported types (company, drug) with concrete output fields.

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

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

Provides explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID' and illustrates with natural language queries. Does not explicitly name alternative tools or exclusions, but the priority statement effectively frames usage context.

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

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

Annotations already cover readOnly/idempotent/openWorld, and the description adds meaningful behavioral context: it 'probes each entity ... with ai_visibility_check', ranks by score, and returns 'a ranked list with score, confidence, signal density per entity'. This goes beyond the structured annotations and clarifies the internal operation and output shape.

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 dense sentences with no filler. The main purpose is front-loaded, and each sentence adds value: operation, use case, output. This is exemplary 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?

No output schema exists, but the description compensates by explicitly listing the return fields ('ranked list with score, confidence, signal density per entity'). It covers purpose, method, and output sufficiently. Minor gap: doesn't mention optional parameters like models or _apiKey, but those are fully documented 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 description coverage is 100%, with each parameter already documented (including 'First entry treated as the subject'). The description's phrase 'your brand + N competitors' restates the schema's entities semantics but adds no new parameter 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 opens with a specific verb-resource pairing ('Compare AI visibility across multiple entities side-by-side') and identifies the underlying probe (ai_visibility_check) and the ranking output. It clearly differentiates from the single-entity sibling tool ai_visibility_check by emphasizing 'multiple entities' and 'side-by-side' comparison.

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 a concrete use case ('competitive AI-marketing audits') with an example question ('does Claude know about us as well as our competitors?'), implying this is for multi-entity comparisons vs. single-entity checks. Does not explicitly mention alternatives like compare_entities or when not to use, but the context is clear.

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

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

The description adds valuable behavioral context beyond the annotations: it discloses graceful degradation under partial failures, the 5-30s timeout for bundlephobia's first measurement, and the presence of a 'sources_failed' field. Even with readOnlyHint/idempotentHint annotations, this timeout/failure behavior is not inferable from annotations alone, so the description carries its weight.

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 a one-sentence purpose, then usage, then return fields, then caveats. It is dense but every sentence earns its place—no filler, no repetition of annotations or schema. The length is justified by the tool's composite nature and the numerous return fields and failure modes it discloses.

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

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

Despite having no output schema, the description explicitly enumerates the summary block fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory details, links, and alternative versions. It also covers ecosystem scope and partial-failure behavior. For a tool this complex, the description is remarkably complete.

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

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

Schema coverage is 100%: both 'package' and 'version' are fully described in the schema, including the default behavior for version. The description adds little beyond that—the mention of 'version' is tied to the measurement timeout, not to parameter format or constraints. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description opens with a clear, specific verb+resource: "Composite 'should I add this npm package to my project' check in ONE call — fans out across deps.dev ... and bundlephobia." It states exactly what the tool does and its inputs (npm package), and the composite nature distinguishes it from sibling tools that focus on entity research or search, none of which handle dependency checks.

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 whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'." It also provides an explicit exclusion: "NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly," telling agents when NOT to use this tool and pointing to an alternative. This is a model of usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: result location ('Results under _embedded.enheter') and field mapping (navn=name, organisasjonsform=org form). It does not contradict annotations. The mention of parameters not present in the schema (naeringskode, forretningsadresse) slightly muddies behavioral transparency, but the core disclosures are solid.

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, information-dense sentence with two inline examples. It front-loads the core purpose and then lists field mappings. While it packs a lot into one sentence, it remains readable and avoids fluff. The extra parameters (naeringskode, forretningsadresse) add noise but overall conciseness is strong.

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

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

The tool has 5 parameters and no output schema. The description covers the search scope, result location, and field semantics, which is substantial. It could mention pagination behavior or clarify that only the parameters in the schema are accepted. Given the annotations cover safety, this is fairly complete but not perfect.

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 meaning by translating Norwegian field names (navn, organisasjonsform, kommunenummer) and providing examples. However, it also references naeringskode and forretningsadresse, which are not in the input schema, potentially misleading the agent about valid parameters. This detracts from clarity.

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: 'Search Norwegian companies/organisations (Enhetsregisteret) by name + filters.' It identifies a specific resource (Enhetsregisteret) and verb (search), with concrete examples. This distinguishes it from siblings like get_entity (look-up) and search_sub_entities (search within sub-entities).

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

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

The description clearly implies when to use this tool: when searching by name or filters. It provides example queries and filter combinations. However, it does not explicitly state when not to use it or mention alternatives like get_entity for exact ID lookups. The guidance is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral context by specifying where results are located (_embedded.underenheter) and providing a concrete example. 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 concise and front-loaded with purpose, followed by key usage details and an example. Every sentence earns its place with no redundant information.

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

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

With no output schema, the description compensates by disclosing the result location (_embedded.underenheter) and giving an illustrative example. It covers the essential behavioral aspects for correct invocation, though it could explicitly mention pagination 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 description coverage is 100%, so the baseline is 3. The description reinforces the meaning of overordnetEnhet and navn but does not add substantial new semantic meaning beyond what the schema already provides.

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

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

The description clearly states the tool searches sub-entities/branches (underenheter), with a specific verb and resource. It distinguishes from sibling tools like search_entities by specifying the sub-entity scope and giving a concrete example.

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

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

The description provides clear context on when to use the tool, such as finding local establishments of a parent company and filtering by parent org number or name. It does not explicitly exclude alternatives like search_entities, but the example and scope make intended usage 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?

The description discloses important behavioral details beyond annotations: it returns passages with character offsets and similarity scores, uses BGE-base-en embeddings over 500-char windows, and truncates inputs over 200K chars with a flag. This goes well beyond the readOnlyHint/idempotentHint annotations and gives the agent trustworthy expectations.

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

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

The description is four sentences, front-loaded with the core purpose, and every sentence contributes useful information (use case, returns, pairing, technical details, limits). No fluff or repetition; it is appropriately sized for a tool with these capabilities.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (passages with offsets and similarity scores) and covers edge cases like character limits and truncation. The tool's complexity is high, but the description addresses all key aspects, making it complete for an agent to use correctly.

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

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

The schema covers all parameters with 100% description coverage, so the baseline is 3. The description adds value by explaining the 'text' parameter as pre-fetched content (e.g., SEC 10-K body) and the 'query' as a natural-language question, plus the notion of top-N passages. This enriches 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 performs 'Semantic search INSIDE a fetched record' with a specific verb and resource, and distinguishes itself from sibling tools like ask_pipeworx_grounded by focusing on searching within already-fetched text rather than whole documents. It is specific and unambiguous.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and provides a workflow pairing with ask_pipeworx_grounded, showing when to use this tool versus alternatives. This is clear, actionable guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds valuable behavior: OAuth requirement, return of subscription id, always-on feed, phone verification, and 10/day SMS cap. It doesn't mention webhook behavior, but that's covered in the schema. 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 the primary action, then returns info, requirements, types, and channels. Every sentence provides necessary detail without fluff, making it dense yet efficient. It's longer than average but all content is operational.

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?

While the description covers return value, prerequisites, and two delivery channels, it omits webhook as an available channel—only email and SMS are listed after 'optionally.' Given the schema includes webhook in detail, an agent relying solely on the description might incorrectly think webhook is unsupported. This is a notable gap in completeness.

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 concrete examples for each type ('items:["5.02"] = officer change', 'topic:"fed"') and clarifies delivery semantics (email/SMS formatting, phone verification, cap). This goes beyond the schema's generic property descriptions.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and proactive monitoring.

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

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

Provides clear context including the requirement for a Pipeworx OAuth account and explicit 'cannot persist' for anonymous/BYO. It lists supported types and delivery channels, but doesn't explicitly state when not to use or name alternatives; 'feed (always on — pull via recent_alerts or GET...)' implies recent_alerts is for retrieval, but no direct comparison.

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, so the safety profile is clear. The description adds behavioral context beyond annotations: it returns category-bucketed examples drawn from the live catalog, and it can be called with or without a topic to focus the results. This gives a good sense of what the tool does without contradicting the annotations.

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

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

The description is moderately long but every sentence earns its place. It starts with example user queries, explains the output (category-bucketed examples with tool+argument shapes), describes calling patterns, and concludes with when to use it. The structure is front-loaded with the core purpose and flows logically.

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 one optional parameter, no output schema, and rich annotations, the description fully covers what the tool does, what it returns, how to call it, and when to use it. It mentions the categories and the meta-tools, making it sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The input schema describes the single optional 'topic' parameter with categories and a note that omitting gives a cross-category spread. The description adds further semantics by giving examples ('finance', 'pharma', 'betting') and clarifying that passing a topic focuses results, while omitting gives the full spread. Since schema coverage is 100%, the baseline is 3, but the description enriches understanding of parameter behavior.

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

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

The description clearly states the tool's purpose: it is an onboarding entry point that returns category-bucketed example questions, each with the exact tool and argument shape that answers it. It differentiates from siblings by explicitly saying 'Use this FIRST when you do not yet know what Pipeworx can do for you' and by focusing on generating ideas rather than direct answers.

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

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

The description gives explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It describes the two calling patterns (no args for full spread, pass topic to focus) and names the meta-tools (ask_pipeworx, entity_profile, compare_entities) that the user can learn about. This clearly indicates when to use the tool and what it can complement.

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 mutation (readOnlyHint=false), non-destructive (destructiveHint=false), and idempotent. The description adds valuable context that the row is deactivated, not deleted, and that historical events remain accessible via recent_alerts. This goes beyond annotations without contradicting them.

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

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

Two clear, front-loaded sentences with no filler. Every clause earns its place: action, ownership, deactivation, and historical data preservation.

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

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

For a single-parameter tool with no output schema, this description is well-rounded. It covers the operation, important behavioral details (ownership, deactivation), and points to sibling tool recent_alerts for historical data. Slight gap: no mention of return value or confirmation behavior, but that is not required given the output schema absence and simplicity.

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

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

The schema covers the sole parameter fully, including its format (uuid) and origin (returned by subscribe). The description repeats 'by id' but adds no extra semantic detail, so the baseline 3 applies given 100% schema coverage.

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

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

The description states 'Cancel a subscription by id' with a specific verb and resource, clearly distinguishing from siblings like 'subscribe' and 'list_subscriptions'. The title reinforces the action.

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

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

The description provides clear usage context: cancel a subscription by ID, with ownership enforcement. It implies this is the tool to use when you want to stop alerts, but it does not explicitly contrast with alternatives like 'subscribe' or 'list_subscriptions', so it misses the 'when-not' guidance for an exceptional 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 read-only, idempotent, and open-world behavior. The description adds internal routing logic (financial vs. non-financial claims), the verdict set, verbatim evidence with citations, and the claim that it replaces multiple calls. This goes beyond annotations, though it does not detail failure modes or latency.

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

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

The description is lengthy but well-structured and front-loaded with trigger phrases. Every sentence provides value, explaining usage, processing, output, and efficiency gains. It could be shortened slightly, but the structure aids comprehension.

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

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

The tool has only 2 simple parameters and no output schema, but the description details return values (verdict, actual value, citation, reasoning). It covers the primary use cases and output semantics, though error handling or ambiguous-claim behavior is not mentioned.

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 enhances both parameters: it gives example claim formats and elaborates on tolerance_pct, including default cap at 5 and use for hallucination detection. This adds meaningful context beyond the schema.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources. It uses specific verbs like 'validate', 'verify', and 'fact check' and differentiates itself by describing two distinct pipelines (SEC EDGAR for financial claims, grounded pipeline for others) and output verdict types, which distinguishes it from sibling research tools.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also mentions it replaces 4–6 sequential calls, implying it is the consolidated tool for claim verification. It does not explicitly list exclusions or alternatives, but the context is clear.

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