Riksdagen Se

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

Beyond annotations (read-only, idempotent), it discloses the default Workers AI model is free, that passing _apiKey triggers Anthropic calls billed directly to the user, and the return shape {score, confidence, signals, raw_response}. This adds meaningful financial and side-effect context.

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

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

Three sentences, each earning its place: purpose, model/cost behavior, and return/use-case summary. Front-loaded with the core function.

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

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

Given no output schema, the description explains return values and use cases. It covers cost, default behavior, and param interpretation adequately for a read-only probe tool.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds some context (default model behavior, _apiKey cost) but largely reinforces schema info, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('probe') and resource ('LLMs'), clearly stating it scores visibility (0-100) per model for a business/brand/product/topic. It differentiates from siblings by focusing on LLM knowledge scoring and combining per-model results, not just searching documents or asking a pipe.

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 names use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It doesn't explicitly contrast with alternatives like scan_competitor_ai_presence, but the context is clear enough to infer when it applies.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable context beyond annotations: it routes to a vast index, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and is a fast single call. This gives the agent a clear picture of what will happen.

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: it front-loads the key directive ('PREFER OVER WEB SEARCH'), then lists covered domains, triggers, examples, and escalation paths. Every section earns its place, though it is somewhat verbose; a slightly tighter version could exist.

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 should mention return format—it does (structured answer with citation URIs). It also covers main use cases, triggers, alternative tools, and a note on breaking news. It doesn't discuss error handling or unsupported questions, but for a router-style tool, this is largely 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% for the single required parameter (question) with aliases. The description adds meaningful context about the type of questions to ask (factual, real-world entities, dates, numbers) and provides concrete examples. This goes beyond the bare schema 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 identifies this as a general-purpose factual Q&A tool that routes questions to one of 5,366 tools across 1,396 verified sources. It uses specific verbs like 'routes' and 'returns structured answer', and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', triggers like 'what is', 'look up', 'find', and examples. Also states when to step up to alternatives: ask_pipeworx_grounded for hallucination-resistant answers with verbatim evidence, deep_research for broad/multi-part questions. This is exemplary 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?

The description adds significant context beyond the annotations: it explains that candidate routing improvements are enabled live whenever one is under test (though none active now), and that it 'falls back to nothing' meaning it is a full working router. This discloses the experimental edge and potential variability without contradicting the readOnlyHint/idempotentHint 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 well-structured, front-loading the key point that it is a beta version. Each sentence adds value: the scope of the router, the current inactive state, usage direction, and no-fallback guarantee. It earns a 4 because it is slightly verbose but efficiently packed with relevant 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?

The tool has no output schema, but the description references the same response shape as ask_pipeworx, which is useful context. It also addresses the current experimental status and comparison to the stable router, making the description sufficiently complete for a wrapper tool of 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?

The input schema has 100% description coverage, listing the question parameter and all its aliases, so the baseline is 3. The description adds no additional parameter semantics beyond saying 'same arguments' as ask_pipeworx, but since the schema is fully self-explanatory, this is sufficient.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, an identical universal router with 5,366 tools, same arguments, and same response shape. It distinguishes from the stable ask_pipeworx by its experimental nature and live candidate routing improvements, making its purpose specific and differentiated 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?

The description explicitly states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing' and mentions that results are compared against the stable router. It also notes the current state (no active candidate) which helps the agent decide. However, it does not explicitly say when NOT to use it (e.g., when stability is preferred), so it falls slightly short of a 5.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses refusal semantics, exact return payload structure, and the fact that it uses ONLY tool results to avoid hallucination. It also lists possible refusal_reason values, giving a complete behavioral picture.

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

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

The description is long but information-dense, with every sentence adding value. It front-loads the key differentiator ('Hallucination-resistant') and uses structured lists for return values and refusal reasons, 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 the tool's complexity and the absence of an output schema, the description fully specifies the return shape and refusal behavior. It also covers cost, routing, and use cases, making it self-sufficient for an agent to decide when to invoke it and what to expect.

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

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

Schema coverage is 100% with all parameters documented as aliases for 'question.' The description adds no additional parameter-level meaning beyond what the schema already provides, but it does clarify that the question is a natural-language query, which is already in the schema. 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 purpose: a 'hallucination-resistant answer mode for high-stakes reads' that routes like ask_pipeworx but extracts answers exclusively from tool results. It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx and naming use cases where grounded answers are required.

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 whenever an answer will be quoted, cited, or acted on...' and when-not-to-use: 'prefer ask_pipeworx for casual lookups.' It also mentions the cost trade-off (one extra LLM call), which helps the agent decide between alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond these: it explains parallel fan-out, resolver contract with confidence levels, safety short-circuiting (low_confidence_match), closed/inactive market handling (market_closed_or_inactive), wide-spread tradeability warnings, GDELT fallback/retry behavior, and cancellation-rule risk. It even quantifies edge cases like flat-50¢ void settlements. No contradictions with annotations.

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

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

The description is long but structured with clear header sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence provides useful operational detail for a complex tool with no output schema. It is front-loaded with the core purpose and usage. The length is justified by the tool's complexity, though it borders on needing a summary paragraph for quick scanning.

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 documents return shapes: result.market fields, result.analysis fields, result.evidence, result.market_match_* contract, result.parent_event, and news fallback fields. It covers safety mechanisms, blocking behaviors, and resolution-rule risk. Given the tool's high complexity and absence of output schema, the description is remarkably complete and leaves no significant gap.

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% — all three parameters (market, depth, include_raw) have detailed descriptions in the schema. The description adds some meaning (e.g., fan-out examples illustrate how depth affects sources, and it explains the market parameter's three forms), but it largely reinforces what the schema already provides. Baseline 3 is appropriate because the schema does the heavy lifting; the description does not significantly compensate beyond that.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It goes on to describe the resolve-classify-fan-out-compare behavior, which clearly distinguishes it from sibling tools like polymarket_edges or validate_claim that focus on narrower aspects. The purpose is immediately clear and non-tautological.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' — clear usage context. It also gives safety caveats (e.g., inspect market_match_confidence before trusting analysis). However, it does not explicitly name alternative tools or state when not to use this tool, lacking the 'when-not/alternatives' distinction needed for 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 indicate a read-only, idempotent, non-destructive operation. The description adds substantial contextual behavior: pulls LATEST 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts results by primary metric, returns paired data with citation URIs, and quantifies efficiency (replaces 8–15 lookups). This exceeds the annotation baseline and provides useful behavioral 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 compact yet information-dense. It opens with trigger phrases, follows with a core purpose statement, then gives type-specific details, sorting behavior, and output characteristics. All sentences earn their place; no fluff or redundancy. The length is justified by the tool's breadth.

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 explains what results look like (paired data, citation URIs, sorted by primary metric). It covers both entity types and their data sources, addresses fiscal-year handling, and communicates the primary use case. For a comparison tool with moderate complexity, this is complete and 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 the baseline is 3. However, the description adds meaningful semantic details beyond the schema: for type='company', it lists specific financial fields (revenue, net income, cash, long-term debt); for type='drug', it specifies data sources (FAERS, FDA approvals, trials). This enriches parameter understanding without duplicating schema info.

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: side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes from siblings by explicitly contrasting with sequential single-pack lookups and using specific trigger phrases ("X vs Y", "rank these companies"). The verb 'compare' plus resource (companies/drugs) is 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 provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It lists triggering query patterns and describes alternatives indirectly ('sequential lookups'). This is clear, actionable guidance on when to use this tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds rich behavioral context beyond that: returns gaps[] for unanswered facets, never invents evidence, uses semantic excerpting rather than head-truncation, explains contradictions[] for certain depths, and discloses latency expectations (15-60s, thorough up to ~90s). 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 structured and front-loaded: account requirement and alternatives appear first, followed by core behavior, use cases, and depth mechanics. Every sentence adds distinct information, though it could be tightened without losing value. Slightly verbose but not wasteful.

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

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

Given the tool's complexity (orchestrating 5,366 tools, multiple depth modes, output packet with citations/gaps/contradictions) and no output schema, the description is exceptionally complete. It explains return values, evidence fields, citation URIs, hop fields, gap recovery, and latency, leaving little ambiguity for an agent.

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

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

Schema coverage is 100% for both parameters, with detailed enum descriptions for depth (quick/standard/thorough and their facet counts). The description adds marginal value by reiterating that 'thorough' needs a paid plan and clarifying second-hop behavior, but the schema already covers most parameter semantics. 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 a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1396 STRUCTURED data sources... in ONE call.' It explicitly distinguishes itself from siblings by naming ask_pipeworx for single lookups and open-web/news topics, and explains that deep_research routes facets to 5,366 tools in parallel.

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: 'Best for broad/multi-part questions over structured data.' Also gives clear exclusions and alternatives: '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.' This goes beyond implied usage.

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, non-destructive behavior. The description adds valuable behavioral context: it returns top-N results with names, descriptions, and full schemas, and states that results are ready to call directly without a second lookup. This enriches the operational understanding 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 moderately long but front-loaded with the core purpose and a clear use-case statement. The extensive domain list is somewhat long but directly supports the usage guidance, and every sentence adds value without redundancy. It could be tightened, but it is well organized.

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

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

With no output schema, the description effectively fills the gap by stating what the tool returns (top-N tools with names, descriptions, full input schemas) and providing concrete examples. Combined with strong usage guidance and annotations, it paints a complete picture for the 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?

Schema coverage is 100% (all 6 parameters documented in the input schema). The description does not add substantive parameter-level detail beyond what the schema already provides, so the baseline of 3 is appropriate. The domain list is usage guidance, not 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 specific verb+resource ('Find tools by describing the data or task') and clearly distinguishes this meta-tool from siblings by explaining it discovers other tools. The domain list and 'Call this FIRST' signal its unique role.

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 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 clearly frames it as the exploratory entry point versus direct tool calls.

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

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

Annotations declare read-only/idempotent, but the description adds rich behavioral context: parallel fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF; specific return fields; recent_filings URIs; patents API sunset with soft-fail; GDELT→GNews fallback. No contradiction.

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

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

The description is long but information-dense, with every clause contributing (examples, return fields, fallbacks, limitations). Slightly run-on but well front-loaded with natural language triggers. Earns a 4 for efficient use of space.

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

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

No output schema, but the description fully enumerates return components (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), explains fallback chains, and notes API sunset and input restrictions. Complete for a complex 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% (type and value already documented). Description adds examples ('AAPL', '0000320193') and reinforces zero-padded CIK, but doesn't add meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call', with specific verbs like 'profile', 'research', 'brief me'. It distinguishes from siblings by explicitly preferring over chaining single-pack lookups and directing name-only users to resolve_entity.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and gives a clear exclusion: 'names not supported (use resolve_entity first if you only have a name)'. Also notes the patents API sunset soft-fail 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 destructiveHint=true and readOnlyHint=false, and the description confirms destructive behavior. It adds contextual use cases and the 'clear sensitive data' rationale, which goes beyond the annotations.

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

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

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

For a simple one-parameter tool with full schema coverage and annotations, the description covers purpose, when to use, and complementary tools. No output schema needed since it's a delete operation.

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

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

Schema coverage is 100%, with the 'key' parameter already described as 'Memory key to delete.' The description's phrase 'by key' adds no new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Delete a previously stored memory by key') with a specific verb and resource. It also distinguishes from sibling tools by mentioning 'Pair with remember and recall.'

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also names alternatives/companion tools, making the usage context unambiguous.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds process transparency by describing the fetch-extract-emit workflow and noting the output is a text blob ready for site-root, which goes beyond the annotation baseline.

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

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

The description is three sentences that front-load the core purpose, then describe the process and output, and finally list use cases. Every sentence adds value with 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?

The description covers what the tool does, how it works, the output format, and common use cases. Since there is no output schema, the description of the text blob output is helpful. It lacks edge-case handling details (e.g., errors on invalid URLs), but for a straightforward tool this is 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?

The input schema covers both parameters (url and max_links) with descriptions, so schema coverage is 100%. The description does not add additional meaning to the parameters beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It also explains the purpose (letting AI crawlers index the site) and differentiates from sibling tools focused on research, voting, or subscriptions.

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

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

The description explicitly lists 'Useful for:' scenarios (getting a client's site indexed, drafting your own llms.txt, auditing competitors), giving clear context for when to use the tool. It doesn't explicitly name alternatives or exclusions, but the guidance is sufficient for most cases.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds useful behavioral context by stating the result nests under 'dokumentstatus.dokument,' which is not visible in the schema or annotations. It also clarifies id case-insensitivity (e.g., lowercase accepted), which is a behavioral trait beyond the schema's example.

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 exceptionally concise: two sentences, front-loaded with the main action, and every word contributes. It includes the essential purpose, an example, and the result path without any filler. This is a model of efficient documentation.

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 rich annotations, the description is nearly complete. It covers what, how, and where the result nests. The only minor omission is a note about possible error conditions or the absence of certain metadata fields, but given the simplicity and the annotation coverage, this is not a significant gap.

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 provides full coverage for the 'id' parameter with a clear description and example. The description adds extra semantic value by noting that the id can be provided in either uppercase or lowercase ('HD024189' or 'hd024189'), which is not stated in the schema. This enriches the understanding beyond the structural schema.

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

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

The description clearly states the tool's purpose: 'Fetch a single document's full metadata by its id.' It specifies the exact resource (document), the action (fetch), and the scope (single document by id). This clearly distinguishes it from sibling tools like search_documents or recent_changes, which handle multiple documents or searching.

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 usage context: use this when you have a specific document id and need its full metadata. It doesn't explicitly exclude alternatives or name them, but the singular 'by its id' makes the use case clear. The sibling tool names provide context, but the description itself doesn't explicitly compare to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by specifying the response nesting structure (personlista.person[]) and Swedish field names, which is helpful context beyond the safety profile. It does not contradict annotations.

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

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

The description is two concise sentences, front-loaded with the core purpose and followed by a useful response structure note. Every word earns its place, with 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?

For a simple tool with two optional parameters and no output schema, the description adequately covers purpose and result shape. It mentions the nesting path and key fields, though it omits potential details like pagination or result size limits, which are not critical for this list 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 descriptions and examples for both parameters (kn and parti), covering 100% of parameters. The description only restates that filtering is optional, adding no new semantic detail beyond the schema.

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

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

The description clearly states the tool lists current Riksdag members with optional filters for party and constituency. The verb 'List' and the specific resource (Riksdag members) distinguish it from sibling tools like list_votes and list_subscriptions.

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

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

The description implies usage when one needs current Riksdag members and mentions optional filters, but it does not explicitly state when to use this tool versus alternatives or any exclusions. There is no direct comparison to sibling tools (e.g., search_documents or entity_profile).

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 destructiveHint, so the safety profile is covered. The description adds behavioral context by enumerating the exact return fields and explicitly stating 'caller's' scope, providing value beyond the annotations without contradicting them.

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

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

Two sentences precisely front-load the purpose and directly state return fields and typical usage. Every word earns its place; no filler 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?

Given a simple list tool with one optional parameter and no output schema, the description is complete: it enumerates all return fields, explains the active-subscriptions default, and gives practical usage guidance for related workflows.

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

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

The schema covers the single parameter (include_inactive) at 100% with its own description. The tool description only reinforces the active-vs-inactive distinction, adding minimal semantic value over the schema.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), clearly distinguishing it from sibling tools like subscribe and unsubscribe. It also scopes the tool to a specific caller and active state, leaving no ambiguity about what it does.

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

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

The description gives explicit, actionable context: use it to review what you're monitoring before adding more subscriptions or to find an id to cancel. It clearly suggests when to use it relative to subscribe/unsubscribe, though it doesn't explicitly list exclusions or name alternatives.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds significant value by disclosing the response structure (nested under voteringlista.votering[]) and row-level fields (namn, parti, valkrets, rost) with allowed vote values, going beyond what annotations provide.

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 purpose and followed by essential return structure. Every sentence earns its place, with no filler or redundancy.

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

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

With no output schema, the description fully covers the return value structure and key fields. Combined with comprehensive parameter schema and safety annotations, the tool is well-specified for an agent to invoke correctly.

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

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

The input schema covers 100% of parameters with descriptions and examples. The tool description adds no parameter-specific semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states the action (List), the resource (individual member votes/voteringar), and the scoping context (parliamentary session and committee-report designation). This clearly differentiates it from sibling tools like list_members and get_document.

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

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

The description gives clear context on when to use the tool: when needing individual member votes for a specific rm and bet. It doesn't explicitly name alternatives or exclude other tools, but the specificity implies appropriate usage, so a 4 is 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?

The description discloses important behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free and not counting against tool-call quota, and that the team reads digests daily with signal affecting roadmap. No contradiction with annotations.

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

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

The description is four sentences with zero filler. It opens with the action ('Tell the Pipeworx team...'), then immediately gives usage conditions, content rules, and quota information. 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 feedback tool with no output schema and rich input schema, the description covers purpose, when to use, what to include, rate limits, and quota behavior. It is fully complete for an agent to select and invoke correctly.

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

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

Input schema covers all 3 parameters at 100% coverage, so baseline is 3. The description adds extra guidance on message content (specific, 1-2 sentences, 2000 chars) and reinforces the use of context fields by saying to describe in terms of Pipeworx tools/packs, exceeding basic schema semantics.

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

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

The description clearly states the tool's purpose: telling the Pipeworx team something is broken, missing, or needs to exist. This specific verb+resource phrasing distinguishes it from sibling tools like ask_pipeworx or subscribe, which are for asking questions or managing subscriptions.

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

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

It explicitly enumerates when to use the tool: when a tool returns wrong/stale data (bug), when a desired tool isn't in the catalog (feature/data_gap), or for praise. It also provides content instructions like describing issues in terms of Pipeworx tools/packs and not pasting end-user prompts, which helps the agent decide and formulate feedback.

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 (readOnly, idempotent, non-destructive), the description adds meaningful context: self-aggregating from analytics-engine, no PII, output shape (pack, tool, count), and caching delays (5min-1h). This helps set expectations about data freshness and privacy 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 front-loaded with a summary sentence, then outputs, use cases, and technical traits. Each sentence provides distinct value with 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?

Even without an output schema, the description covers the return content, use cases, data source, privacy guarantees, caching, and parameter behavior. This is complete for a simple read-only aggregation 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 only parameter (window) is fully documented in the schema with semantics for shorter vs longer windows. The tool description merely repeats the enum values without adding extra meaning, so it meets the schema-coverage baseline of 3.

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

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

Clearly states the tool returns top tools, top packs, and call volume over configurable windows, with a one-line summary of what it tracks. Distinguishes itself from sibling tools by focusing on aggregate agent usage rather than individual queries or document retrieval.

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

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

Provides three explicit use cases (hot data sources, canonical tool confirmation, alignment with agent needs) that give clear context for when to use it. Does not explicitly name alternatives or exclusions, but the use cases imply the right situations compared to siblings like discover_tools or ask_pipeworx.

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

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

Annotations already mark this as read-only/idempotent, but the description adds substantial behavioral detail: monotonicity checks, partition-sum validation, Jaccard similarity threshold, placeholder filtering, and fill check against live CLOB depth. It also warns 'do not trade it' when realizable_edge_pp ≤ 0, which is a critical behavioral caution beyond what annotations provide.

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-organized into clear sections (modes, SEMANTIC ANCHOR, PARTITION FILTER, Response, FILL CHECK). It is front-loaded with the core purpose. Every sentence contributes meaningful information about behavior or usage. For a tool with this complexity, the length is justified, though a slight trim could improve conciseness.

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

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

Given there is no output schema, the description adequately covers the return structure (opportunities[] with fields, partition_check{}) and describes edge cases like null arb signals and fill-check failure conditions. It also contextualizes its role among sibling tools by referencing polymarket_fill_risk for custom sizing, making the tool's integration clear.

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

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

The input schema already covers 100% of parameters with clear descriptions and examples for both `event` and `topic`. The description reinforces these by explaining mode-specific behavior (e.g., event walks child markets, topic searches related events) and adds semantic anchor/filter context that influences parameter interpretation. It adds value over the schema but is partially redundant.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the three modes (trending_scan, event, topic), each with a specific purpose, which goes beyond a generic statement and sets clear expectations.

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

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

The description explicitly instructs when to use each mode: no args for trending_scan, `event` for a specific market, and `topic` for cross-event scanning. It also provides an alternative-tool recommendation: 'For custom sizing use polymarket_fill_risk.' This is practical, actionable guidance without needing to infer from 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?

The description goes far beyond the readOnlyHint/openWorldHint/idempotentHint annotations by disclosing complex internal logic: five model families, three response segments, per-sport alpha values, placeholder-slug filters, Kelly caps, slippage assumptions, caching behavior at the KV level, and diagnostic funnel counters. This is rich behavioral context that fully informs the agent of what to expect.

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 every sentence carries specific technical detail (model families, gates, response structure). It front-loads the purpose and then systematically explains segments and knobs. While it could be trimmed, the structure (segments, knobs, response top-level) makes it navigable.

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 explains the response shape: by_segment with three segments, fed_candidates/fed_note, and _diagnostics. It also covers why segments might be empty (filter_skips, stale top-N). This makes the tool's behavior complete for an agent selecting and invoking it.

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

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

The input schema already covers all 9 parameters with detailed descriptions (100% coverage). The tool description adds semantic context beyond the schema by explaining how the knobs interact, e.g., min_partition_leg_kelly applies to per-leg Kelly because parent-level Kelly is zero by design, and slippage_pp is subtracted before ranking. This goes above the baseline but is not ecessarily exhaustive since the schema is already strong.

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+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx data and returning ranked opportunities.

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

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

The description states the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also notes that Fed bets surface but are excluded from ranking due to unreliable signals, giving an explicit exclusion. However, it does not name alternative tools explicitly, so it stops short of a 5.

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

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

Beyond the readOnly/idempotent annotations, it discloses TTL limits (60-day snapshot), snapshot gap behavior (cache-miss writes), and that decay is computed from daily closes of edge_pp_net, not intraday. This adds significant behavioral context.

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

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

The description is front-loaded with purpose, then args, then response structure, then limits. Although long, each sentence adds operational detail and no placeholder filler exists; the structure makes it scannable.

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 defines the response shape (tracked[], expired[], snapshot_dates[]), explains edge_pp_net sign convention, trend categories, and lifecycle. It also covers historical depth limitations, making it complete for complex telemetry.

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 documents both parameters with defaults and clamps (100% coverage). Description restates defaults and adds 'snapshot family' and 'lookback' terminology, but does not fundamentally expand on the schema descriptions, so baseline 3 is appropriate.

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

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

The description explicitly states it provides 'edge persistence and decay telemetry' and answers a specific question ('how long has this edge existed and is it shrinking?'), which clearly distinguishes it from sibling polymarket_edges that likely only reports 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?

It gives clear context for when to use this tool (when edge age/trend matters) and references polymarket_edges snapshots as its data source. However, it does not explicitly state when not to use it or name alternatives, so it stays at clear-context rather than 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?

Despite annotations indicating a safe read-only/idempotent operation, the description adds substantial behavioral detail: it explains that the tool 'walks the ladder,' returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict), and discloses the risk of partial fills and 'forced_directional_risk' in basket mode. This goes well beyond the annotations' basic safety hints.

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

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

The description is long but highly structured, with clear sections for required parameters, single-market vs basket behavior, and usage guidance. Every sentence contributes important operational context (e.g., the risk warning about partial fills). While it could be tightened, the density of useful information justifies 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 the tool's complexity (two modes, multiple return values) and the absence of an output schema, the description is remarkably complete. It enumerates return fields for both modes, explains the 'verdict' values (clean|degraded|cannot_fill), details the interpretation of `size_usd` in each mode, and explicitly warns about the dominant loss mode in real arb-bot P&L. This fully compensates for the missing output schema.

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

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

Schema descriptions already cover all parameters (100% coverage), so baseline is 3. The description adds meaningful semantics: it clarifies that `size_usd` is interpreted as 'max spend on buys, target proceeds on sells' in single-market mode and as 'settlement notional' in basket mode, and explains `side` defaults vary by mode (e.g., 'auto from partition sum'). This additional context elevates it above the baseline.

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

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

The description clearly defines the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' with an explicit verb-resource framing. It distinguishes itself from siblings by referencing 'polymarket_arbitrage SELL/BUY-EVERY-LEG signal' and 'polymarket_edges trade,' making its specific role unmistakable.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains when not to proceed due to theoretical overround being uncapturable and the risk of partial fills converting an arb into an unhedged position, effectively telling the agent when this tool is required.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes well beyond by detailing compatibility_warning triggers, temporal_alignment meaning, skipped_cross_type/subtype semantics, and a realistic tradeability caveat. No contradictions with annotations.

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

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

The description is long but well-structured with clear sections: intro, modes, response, safety fields, temporal alignment, skipped counters, and a concluding caveat. It front-loads the core purpose and each sentence adds value, though some elaboration on compatibility_warning details could be tightened without losing meaning.

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 thoroughly explains all key response elements: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It also covers edge cases and interpretive guidance, making it highly 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?

The input schema covers 100% of parameters with descriptions. The description adds semantic clarity by distinguishing the two modes ('topic' shortcuts vs explicit kalshi_event_ticker + polymarket_event_slug), explaining override behavior, and giving concept-level meaning beyond the schema's terse 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+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly differentiates from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison and explicitly lists two operation modes and response contents.

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

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

The description explains two modes (pre-mapped topic vs explicit tickers/slugs) and offers cautionary guidance (e.g., pre-mapped ≠ tradeable, compatibility_warning conditions). However, it does not explicitly name alternatives or state when NOT to use this tool versus other sibling tools, so it lacks full exclusivity 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 read-only, idempotent, and non-destructive. The description adds valuable context about scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the listing 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?

Three sentences, front-loaded with the main action, then use case, then scoping and companion tools. Every sentence contributes distinct information without waste.

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

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

Given the simple one-parameter tool with comprehensive annotations and schema description, the description covers purpose, usage, alternatives, and scoping. It is complete for an agent to select and invoke correctly.

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

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

Schema covers 100% of the parameter (key) including the omit-to-list behavior. The description adds concrete examples of what keys represent ('user's target ticker, an address, prior research notes'), enriching the schema description slightly.

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

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

The description clearly states the tool retrieves a value previously saved via remember or lists all keys when the key is omitted. It distinguishes itself from siblings (remember, forget) by explicitly mentioning them, and gives concrete examples of use (ticker, address, notes).

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 to look up context the agent stored earlier' and names alternatives: 'Pair with remember to save, forget to delete.' Also mentions scoping to identifier, which helps decide applicability.

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 contradicts the annotation readOnlyHint: true. It explicitly states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which indicates a state-changing operation. This is a direct contradiction with the read-only hint, earning a score of 1 per the rubric. Additional behavioral details (like return contents) are provided, but the contradiction undermines trust.

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

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

The description is well-structured and front-loaded: it states the primary purpose in the first sentence, then efficiently covers return payload, filtering, mark_read semantics, and polling/alternative access in subsequent sentences. Every sentence contributes unique information with minimal redundancy.

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

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

Given the tool's complexity (5 optional parameters, no output schema), the description is highly complete. It explains what the tool returns (source, citation_uri, raw event payload), how to filter, the mark_read side effect, and even mentions the alternative HTTP endpoint. The only missing piece is explicit handling of unread_only, but that is adequately covered in the schema, and the description covers enough for effective use.

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

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

The input schema has 100% description coverage for all 5 parameters, so the baseline is 3. The description adds value beyond the schema by providing a concrete example for the type parameter ('sec_8k') and explaining the functional impact of mark_read ('flag returned events read so the next call only shows newer ones'). This enriches the meaning beyond simple field descriptions.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' This is a specific verb+resource combination that distinguishes it from siblings like recent_changes (which likely covers different change events) and list_subscriptions (which lists subscriptions rather than fired events).

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 for use, including filtering options, the mark_read behavior, and the note that 'Polls work fine.' It also gives an alternative endpoint for scripts/dashboards, which helps users choose the right access method. However, it does not explicitly exclude any use cases or compare with sibling tools.

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

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

Beyond the read-only and idempotent annotations, the description discloses critical behavior: fans out to SEC EDGAR, GDELT→GNews fallback, and USPTO soft-fail after May 2025. It also mentions the return structure with grouped changes and citation URIs, providing rich context.

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

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

The description is dense but every sentence adds value: trigger phrases, source fan-out, fallback behavior, date format guidance, return structure, and alternative tool. No fluff or redundancy.

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

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

Given the tool's complexity (multiple data sources, fallbacks, soft-fail, and custom date handling), the description covers all critical aspects, including return format and limitations. No output schema exists, so this description carries the full burden and succeeds.

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

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

While the input schema covers all three parameters with descriptions, the tool description adds actionable guidance: examples of ISO and relative date formats, and a recommendation to use '30d' or '1m' for typical monitoring. This exceeds schema-only semantics.

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

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

The description clearly states the tool provides a change feed for a company over a time window, with natural language query examples. It distinguishes itself from sibling entity_profile by explicitly noting that tool 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?

The description provides explicit usage guidance: use entity_profile when wanting a static profile regardless of window. It also explains the fan-out behavior and fallback logic, giving the agent a clear sense of when this tool is appropriate.

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

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

Annotations already signal a non-read-only, idempotent, non-destructive mutation. The description adds valuable behavioral context beyond those hints: storage as a key-value pair scoped by identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. This meaningfully enriches the agent's understanding of side effects and lifecycle.

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: the first sentence states the core action, followed by usage guidance, storage details, persistence behavior, and companion tools. Every sentence earns its place without redundancy or fluff.

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

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

For a simple two-parameter tool with no output schema, the description covers all necessary context: what to save, when to use it, storage mechanics, persistence guarantees, and related tools. The agent has enough information to invoke this tool correctly and understand its effects.

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

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

The input schema fully describes both parameters (key and value) with examples, so the schema carries the semantic burden. The description adds general context about key-value scoping but no parameter-specific details beyond what the schema already provides. Baseline 3 is appropriate 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 opens with a specific verb and resource: 'Save data the agent will need to reuse later' and clearly distinguishes the tool from siblings by explicitly naming recall and forget as companion tools. The scope ('across this conversation or across sessions') further clarifies its unique role.

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

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

The description provides explicit guidance on when to use the tool: 'Use when you discover something worth carrying forward' with concrete examples such as ticker, address, or preference. It also names alternatives/companions ('Pair with recall to retrieve later, forget to delete'), making the decision boundary 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?

While annotations already declare readOnly, openWorld, and idempotent, the description adds valuable behavioral context: internal cascading through multiple endpoints, auto-disambiguation, return fields (ticker, CIK, company_name, citation URIs), and the benefit of replacing 2-3 manual lookups. It doesn't contradict annotations.

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

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

The description is longer than average but well-structured, front-loading query examples followed by structured 'SUPPORTED TYPES' breakdown. Every sentence adds value, avoiding fluff. The length is justified by the need to explain two distinct entity types with their return formats.

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 takes on the burden of explaining returns, and it does so thoroughly for both company and drug types, including citation URIs. It covers input variations and disambiguation but could optionally mention failure modes or rate limit behavior. Overall, sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, but the description substantially enriches parameter meaning with concrete examples (AAPL, 0000320193, 'ozempic', 'metformin') and type-specific return details. It clarifies how 'value' should be interpreted differently for company vs. drug types.

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 user-spoken names to canonical/official identifiers, with specific examples (ticker, CIK, RxCUI). It distinguishes itself from siblings by positioning itself as a prerequisite for other tools that require these identifiers, making its purpose unmistakable.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. The supported types and input/output examples further clarify the context. It doesn't explicitly mention when not to use, but the narrow scope and 'FIRST' directive make this a strong guideline.

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

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

The description adds context beyond the annotations by explaining the internal process (probes with ai_visibility_check, ranks by score) and the return format (ranked list with score, confidence, signal density). Annotations already declare read-only and idempotent behavior, so the added behavior about ranking and output structure is valuable.

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

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

The description is concise yet informative, with three sentences that each serve a purpose: stating the core function, explaining the process and use case, and describing the output. No redundant or filler text is present.

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

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

The description adequately covers the tool's operation: it describes the process, the return value, and a typical use case. It does not explicitly mention limitations (e.g., entity count bounds, error conditions), but the schema covers the 2-8 entity constraint. Given the tool's moderate complexity and lack of an output schema, the description provides sufficient contextual 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?

The schema covers 100% of parameters, so the baseline is 3. The description adds meaning by clarifying that the first entity is the 'subject' for narrative and the rest are competitors, which is not explicitly stated in the schema. It also explains the 'context' parameter as shared context applied to every probe, slightly enhancing schema descriptions.

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

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

The description clearly states the tool's action: 'Compare AI visibility across multiple entities side-by-side.' It specifies the resource (competitor AI presence), the process (probes with ai_visibility_check, ranks by score), and distinguishes from the sibling tool ai_visibility_check by focusing on multi-entity 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?

The description provides a concrete use case: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' It also implies when to use this over ai_visibility_check (when comparing multiple entities). However, it does not explicitly mention when not to use it or compare it to other entity-comparison tools like compare_entities.

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 and non-destructive. The description adds critical behavioral context: it fans out across two services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. 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?

Though longer than typical, every sentence carries unique, high-value information: purpose, usage, return fields, ecosystem limits, and failure behavior. Structure is well-organized with clear sections, making it easy to scan.

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 composite tool with no output schema, the description fully explains return fields, partial failure behavior, and ecosystem fallback, making it self-sufficient for an agent to invoke correctly.

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

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

Schema already covers 100% of parameters with descriptions. The description adds no new parameter-level semantics beyond confirming defaults and scoped packages, which are already in the schema. Baseline 3 applies due to 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 clearly states it is a composite 'should I add this npm package' check, combining deps.dev and bundlephobia, and explicitly limits to NPM ecosystem, distinguishing from sibling tools that scan other domains. The verb 'scan' and resource 'dependency' are specific and the scope is 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?

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also clearly states the exclusion for other ecosystems, directing users to 'deps.dev:version directly', making when-to-use and when-not-to-use very clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds valuable context by specifying that results are nested under 'dokumentlista.dokument[]' and that it searches Riksdagen documents, which goes beyond the annotations.

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

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

The description is two sentences, front-loaded with the primary action, and contains zero filler. It efficiently conveys scope, filters, and result shape without redundancy.

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

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

Given the 5 parameters are fully documented in the schema and annotations provide safety guarantees, the description offers a solid overview. It reveals the result nesting but does not mention the Swedish-language requirement explicitly (though the schema example suggests it) or any ordering/sorting defaults. A slightly richer description could fully compensate for the absence of an output schema.

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

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

Schema description coverage is 100%, with all five parameters documented in the input schema. The description only restates the filter types (free-text, document type, date range) without adding new parameter-level syntax or constraints. Since the schema does the heavy lifting, the baseline score of 3 applies.

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

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

The description uses a specific verb ('Search') with a clear resource ('Riksdagen documents') and enumerates document types ('motions, propositions, committee reports, written questions'). It also mentions filtering and the result structure, distinguishing it from sibling tools like get_document (single-document retrieval) and search_within (likely in-document search).

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

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

The description clearly states the tool's purpose and available filters (free-text, document type, date range), giving context for when to use it. However, it does not explicitly name alternative tools or state when not to use it, stopping short of 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses technical details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' It also mentions return values include offsets and similarity scores, which is important since there is no output 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 four sentences, each serving a distinct purpose: what it does, when to use it, how it works, and key constraints. It is dense but not overly verbose, front-loading the core function first. Slightly long but 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?

With no output schema, the description adequately explains return values (top-N passages, offsets, similarity scores) and truncation behavior. It also situates the tool within a workflow by pairing with ask_pipeworx_grounded. It lacks edge-case error handling details, but those are not essential for a semantic search tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by giving real-world examples for the query ('supply-chain risk', 'fiscal year 2024 revenue') and clarifying that text can be 'a SEC 10-K body, an article, a long tool result.' This complements the schema nicely without redundancy.

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 'Semantic search INSIDE a fetched record,' a specific verb+resource statement that clearly differentiates it from siblings like search_documents (which likely searches across documents) and get_document (which fetches a record). It explains what it does: pass text plus a query, get top-N passages with offsets and scores.

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 it: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also pairs it with ask_pipeworx_grounded, saying 'fetch with the gateway, ground over the relevant passages instead of the whole document,' giving clear context and an alternative approach.

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 include idempotentHint=true, yet the description states 'Returns the new subscription id,' implying each call creates a fresh subscription—a direct contradiction of idempotency. While the description does add useful context (auth requirements, delivery caps, webhook auto-disable), the contradiction per rubric forces a score of 1.

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

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

The description is dense but front-loaded with the core action and return value. It covers types, delivery, and prerequisites in a single paragraph. Slightly long, but justified by tool complexity; not bloated.

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

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

Given the tool's complexity, the description leaves little uncovered: authentication prerequisites, all supported types with examples, delivery channel mechanics (including phone verification, SMS caps, webhook signing and auto-disable), and the return value. With no output schema, this is very complete.

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

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

Schema coverage is 100% and already provides per-type parameter filters. The description adds semantic value by explaining item codes (e.g., 'items:["5.02"] = officer change') and gives concrete examples for three subscription types. This goes beyond the schema but is not a full replacement, so 4 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 opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' This clearly separates it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts. The inclusion of the return value ('Returns the new subscription id') further pins down its purpose.

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 establishes a clear prerequisite ('Requires a Pipeworx OAuth account') and explicitly points to an alternative for retrieving subscription results ('feed (always on — pull via recent_alerts or GET registry.pipeworx.io/alerts.json)'). It doesn't explicitly call out sibling tools for subscription management (list_subscriptions/unsubscribe), but the context is adequate.

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, open-world hints. The description adds valuable behavioral context beyond annotations: it returns category-bucketed examples drawn from a live catalog, and it teaches how to call other meta-tools. This enriches the agent's understanding of what the tool actually does at runtime.

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

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

Although the description is long, every clause earns its place: example queries, return value, categories, tool-call shape, usage instructions, and explicit first-use advice. The structure flows naturally from user intent to output to invocation details, 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?

The tool has one optional parameter and no output schema; the description fully covers what the tool returns (category-bucketed examples with tool shapes) and how to invoke it. It also situates the tool within the larger tool ecosystem, making it complete for an onboarding function.

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% for the only parameter `topic`, but the description goes further by listing example focus areas ('finance', 'pharma', 'betting') and explicitly stating the default behavior when omitted ('cross-category spread'). This adds practical meaning beyond the schema's field description.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with exact tool + argument shape. It explicitly lists the types of questions it handles ('What can I ask Pipeworx?', 'give me ideas', etc.), making it distinct from siblings like ask_pipeworx, which directly answers queries.

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.)'. It also explains the argument behavior (omit for full spread, pass topic to focus) which clarifies usage 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 indicate this is non-read-only, non-destructive, and idempotent. The description adds valuable context by explaining that the row is deactivated, not deleted, and that historical events remain available via recent_alerts. This goes beyond what annotations alone convey.

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

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

The description is two succinct sentences, front-loaded with the core action, and contains no redundant words. Every sentence provides necessary information.

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

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

Given the simplicity of the tool (single parameter, no output schema), the description covers all essential aspects: operation, ownership constraint, side effects, and relationship to recent_alerts. It is 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% with a clear parameter description ('Subscription id (uuid) returned by subscribe'). The description doesn't add further meaning to the parameter, 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 starts with 'Cancel a subscription by id', which is a specific verb + resource. It clearly distinguishes the tool from siblings like subscribe and list_subscriptions, and the ownership enforcement adds clarity about scope.

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

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

The description states that ownership is enforced ('you can only cancel your own subscriptions') and clarifies the deactivation behavior, implying when this tool should be used. It doesn't explicitly name alternative tools, but the context is clear enough.

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

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

Beyond the readOnly/idempotent annotations, the description details the internal pipeline (SEC EDGAR + XBRL fast path vs. grounded fallback), the tolerance_pct semantics with a default cap at 5, and the exact output components (verdict, actual value, citation, reasoning). This adds substantial behavioral context not visible 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?

Despite its length, the description is front-loaded with illustrative queries and a crisp purpose statement. Every subsequent sentence adds information about routing, output, or benefits. There is no filler or redundant restating of the title/name.

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 is comprehensive for a tool without an output schema: it specifies the input claim, optional tolerance, the two processing paths, the verdict types, the citation mechanism, and the reasoning output. It also mentions the tool replaces multiple sequential calls, giving a clear sense of scope and utility.

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?

Both parameters already have schema descriptions, but the tool description adds critical semantics: tolerance_pct overrides implied wording tolerance, is capped at 5, and is recommended for hallucination detection. The claim parameter is also illustrated with two concrete examples. This exceeds schema-only 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 begins with concrete user phrases and states the tool does 'natural-language claim verification against authoritative sources.' It clearly identifies the verb (validate/verify) and resource (factual claims), and distinguishes itself from research or search tools by focusing on verdict generation with citations.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two routing paths (company-financial vs. other claims). However, it does not explicitly name alternative tools or state when not to use it, so it falls slightly short of a 5.

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