Tweedekamer Nl

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond that: the default model is free, while Anthropic requires a BYO key with direct payment, and it discloses the return shape (per-model score, confidence, signals, raw_response plus combined view). 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 three well-structured sentences, front-loaded with purpose, then behavior, then use cases. Every sentence adds distinct information without redundancy or fluff, making it appropriately sized and directly 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 adequately covers return values ('per-model {score, confidence, signals, raw_response} + a combined view'). It also covers default behavior, optional models, and cost implications, making it complete for an agent to decide invocation. The tool is moderately complex but the description addresses all necessary aspects.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameter understanding by detailing that '_apiKey' is only needed for Anthropic and that the default model is used when 'models' is omitted. It also clarifies the 'context' parameter's purpose (disambiguates common names), adding value beyond the schema descriptions.

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

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

The description uses a specific verb ('Probe'), identifies the resource ('one or more LLMs'), and states the core output ('score visibility (0-100) per model'). It clearly distinguishes itself from sibling tools by focusing on LLM visibility scoring rather than general asking/researching. The mention of default model and optional Anthropic probing adds specificity.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to pass '_apiKey' (to probe Anthropic). However, it does not explicitly contrast with sibling alternatives like deep_research or scan_competitor_ai_presence, so it misses explicit exclusionary 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 readOnly=true, openWorld=true, idempotent=true, and destructive=false. The description adds behavioral context beyond those flags, such as 'Routes the question to the right one of 5,564 tools', 'fills arguments', 'works on every tier', and 'one fast call'. It also mentions the response format with citation URIs, which is useful and non-contradictory to 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 lengthy but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and structured into clear sections: scope, routing behavior, usage triggers, examples, and alternatives. The 'Use whenever' list partially repeats the earlier domain list, so it could be tightened, but the overall structure 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?

There is no output schema, but the description covers what the agent needs: it returns 'the structured answer with stable pipeworx:// citation URIs'. It describes the tool's scope, routing mechanism, triggering phrases, examples, and alternatives, which is complete for a complex routing tool even without 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?

The schema covers 100% of the six alias parameters, so the baseline is 3. The description adds value by giving example question phrasings ('what is', 'look up', 'get the latest') and a few concrete examples like 'current US unemployment rate' and 'Apple's latest 10-K'. This supplements the schema's natural-language instruction 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 clearly identifies the tool as a question router: 'Routes the question to the right one of 5,564 tools across 1462 verified sources' and 'returns the structured answer with stable pipeworx:// citation URIs.' It explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research, and from web search, so the agent knows exactly what this tool does.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH for questions about...' and lists specific domains. It also states when to step up to alternatives: 'for a hallucination-resistant single answer use ask_pipeworx_grounded; for a broad/multi-part question use deep_research.' This makes the decision boundaries clear.

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

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

The description adds significant behavioral context beyond the annotations: it discloses that the tool is experimental, may switch between candidate routing improvements live, currently matches ask_pipeworx, and that there is no fallback—it is a full working router. This exceeds what annotations alone convey and prevents misconceptions.

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 no waste: it states the beta relationship, current state, usage instruction, and a clarifying caveat. Information is front-loaded and each sentence earns its place.

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

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

For a universal router with 6 parameters, full schema coverage, and rich annotations, the description is complete. It explains the response shape via the reference to ask_pipeworx, addresses the current runtime state, and clarifies that the tool is fully functional rather than a degraded fallback.

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

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

Schema description coverage is 100%, with the question parameter and all five aliases fully documented. The description only references 'same arguments' without adding extra parameter semantics, but since the schema handles this dimension completely, the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, an identical universal router over 5,564 tools. It distinguishes itself from the stable sibling ask_pipeworx by emphasizing its experimental routing candidate status, making the purpose and differentiation explicit.

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

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

The description explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and clarifies that with no active candidate it currently matches ask_pipeworx. It gives clear context for use, though it does not explicitly enumerate when not to use it versus ask_pipeworx_grounded.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses key behavioral traits: extraction is limited to tool-result content, success returns evidence/confidence/source/fetched_at, and failures return structured refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also surfaces the extra LLM call cost, adding meaningful operational context not present in annotations.

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

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

The description is dense and well-structured: one sentence for identity, one for mechanism, one for return/refusal contract, and one for usage guidance. Every sentence contributes distinct information without 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?

Despite no output schema, the description fully specifies the success return shape and the refusal protocol, covers when to use and when not to use, and notes the extra LLM call cost. Given the tool's complexity, this is a complete and self-sufficient description for an agent.

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

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

Schema coverage is 100%: all six parameters are documented aliases for 'question' with a clear description. The tool description does not add parameter-level meaning beyond the schema, so baseline 3 is appropriate; it correctly references filling arguments but does not explain question formatting or constraints.

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

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

The description clearly defines a grounded, hallucination-resistant answer mode for high-stakes reads, distinguishing it from sibling ask_pipeworx by emphasizing evidence extraction and explicit refusals. It names the tool's function and its differentiator in the first sentence.

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

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

The description explicitly states when to use the tool ('whenever an answer will be quoted, cited, or acted on... must not invent facts'), provides concrete domains (financial verdicts, legal claims, medical lookups), and directs users to prefer ask_pipeworx for casual lookups due to the extra LLM call cost. This is explicit when/when-not guidance with a named alternative.

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

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

Even though annotations already mark it as read-only, idempotent, and non-destructive, the description adds extensive behavioral detail: parallel fan-out, resolver contract with confidence levels, short-circuiting on low-confidence matches, closed-market handling, illiquidity flags, GDELT fallback failures, and cancellation-rule parsing. This goes far 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 long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) that aid scanning. It is front-loaded with the core purpose, and each section carries unique operational value. However, the sheer length makes it slightly less concise than ideal.

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 specifies response shapes (result.market, result.analysis, result.evidence), statuses, safety mechanisms, and resolution-rule risks. It covers edge cases like illiquid markets, closed markets, fallback failures, and gives re-query hints. Nothing critical is missing for correct invocation and interpretation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaningful parameter semantics beyond what the schema already provides; it mostly repeats the market input types and include_raw behavior. The fan-out examples are about tool behavior, not parameter meaning.

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 clearly differentiates from siblings by mentioning the evidence packet and market-vs-model comparison, and it lists concrete use cases ('should I bet on X', etc.).

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

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

It provides explicit when-to-use guidance ('Use for...') and category-specific fan-out examples that help the agent decide. However, it does not name alternative sibling tools or explicitly state when not to use it, so it lacks the exclusions that would earn a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral context: handling of off-calendar fiscal years, data sourcing from SEC EDGAR/XBRL and FAERS, result sorting by primary metric, and the return of paired data with citation URIs. This exceeds the safety-only disclosure and fully informs the agent about side effects and output characteristics.

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

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

The description is dense but every sentence earns its place. It opens with trigger phrases, then states the tool's advantage, then details per-type behavior and output format, all without redundancy. The structure is effective for quick parsing by an agent.

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

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

For a tool with two types and no output schema, the description is highly complete. It explains data sources, specific metrics returned, sorting behavior, output format (paired data + citation URIs), and the efficiency benefit over sequential lookups. This gives the agent all needed context to invoke correctly and anticipate results.

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

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

Although schema coverage is 100%, the description enriches both parameters: it explains the enum values (company/drug) with what each pulls, and gives concrete formats for values (tickers/CIKs vs drug names) with examples. It also explains that results are sorted by the primary metric, adding meaning beyond the raw schema definitions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in one call, with specific trigger phrases ('compare', 'vs', 'which is bigger'). It distinguishes itself from sibling single-entity tools like entity_profile or query_entity by emphasizing the parallel comparison and its efficiency advantage.

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 with trigger phrase examples and a clear directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also differentiates the two entity types (company vs drug) and specifies the data sources per type, giving the agent clear selection criteria.

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

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

The annotations only state readOnly/openWorld/idempotent/destructive hints, but the description goes far beyond: account requirements and paid plan limitations, latency 15-60s (up to ~90s), the fact that it never invents data and returns gaps[], the `hop` field and resolvable citation URI semantics, semantic excerpting behavior, and contradictions[]. No contradiction with annotations; it adds substantial behavioral context.

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

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

The description is long but densely informative, with a logical flow from account requirement to purpose to alternatives to depth details to output semantics to latency. It is front-loaded with the essential purpose. A few details (e.g., the exact signup URL) could be considered extraneous, but overall every sentence adds value for a tool with this complexity.

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

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

Given the tool has no output schema, the description fully covers the return format: findings packet, verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field. It also covers edge cases (empty gaps for non-catalog topics), timing expectations, and depth-specific behaviors. Everything an agent would need to invoke and interpret results is present.

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, but the description adds deeper meaning: it explains each `depth` value (quick/standard/thorough) in terms of facets, hops, gap recovery, and contradictions scan, and clarifies that `question` can be broad/multi-part because decomposition is the point. This goes well beyond the baseline for complete 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 leads with a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources... in ONE call.' It distinguishes from siblings by explicitly contrasting with ask_pipeworx and emphasizing this is not open-web search. The return type (findings packet) is also clearly stated.

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 and when-not-to-use guidance. It says 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also explains the depth tiers and when 'standard' or 'thorough' resolves multi-step questions. This is far beyond minimal 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 discloses that results include names, descriptions, full input schemas, and curated examples, and that results are ready to call directly without a second schema lookup. This adds value beyond the readOnlyHint and idempotentHint annotations, which already establish a non-destructive, repeatable operation. The behavior of returning ready-to-use tool schemas is explicitly stated.

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

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

The description is front-loaded with the core purpose, then usage, then return behavior. The domain list is somewhat long but earns its place by conveying the tool's breadth. Every sentence adds substance, though it is a bit longer than strictly necessary.

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 search/discovery tool, the description covers the key aspects: what it does, when to use it, and what it returns (including the readiness of results). No output schema exists, but the description compensates by explaining the return format. It is complete enough for an AI agent to decide when and how to invoke it.

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

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

All six parameters have descriptions in the schema, so coverage is 100%. The description doesn't add much beyond what the schema already provides, except for implying top-N results which aligns with the 'limit' parameter. Since the schema carries the load, a 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 opens with a specific verb+resource pair: 'Find tools by describing the data or task.' It clearly distinguishes this tool from siblings like deep_research or get_entity_by_id by focusing on tool discovery rather than domain-specific operations. The scope is explicit, listing many data categories.

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?

'Use when you need to browse, search, look up, or discover what tools exist' gives a clear trigger condition. 'Call this FIRST when you have many tools available' adds strong sequential guidance. It lacks explicit exclusions or named alternatives, but the context is well established.

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 behavioral traits beyond the annotations, such as the parallel fan-out across sources, specific return fields, patent endpoint soft-failing due to API sunset, and fallback chains (GDELT→GNews). These details meaningfully extend the readOnly/openWorld/idempotent hints without contradiction.

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

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

The description is dense but efficient, using examples and semicolon-separated details. While slightly long, every segment earns its place by conveying source list, return structure, and constraints. The front-loaded examples make the tool's intent immediately recognizable.

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

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

Given the complexity and absence of an output schema, the description thoroughly explains all return components (cik, filings, fundamentals, patents, news, LEI), including URI formats and sorting. It also covers current limitations and fallbacks, making it sufficient for an agent to invoke and interpret results.

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

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

The input schema already provides 100% coverage, including examples for value and instruction to use resolve_entity for names. The description repeats this information without adding additional semantic depth beyond the schema, 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 clearly defines the tool as a 'full cross-source profile of a US public company in ONE parallel call,' with multiple example queries. It distinguishes itself from sibling tools by explicitly preferring it over chaining single-pack lookups and noting the need to use resolve_entity for name inputs.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies when not to use the tool directly ('names not supported — use resolve_entity first'), offering a clear alternative.

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 and idempotentHint, and the description aligns by saying 'Delete.' It adds context about clearing sensitive data and pairing with remember/recall, which provides value beyond the annotations, though it does not disclose additional side effects (e.g., irreversibility) beyond what the destructive hint implies.

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 action, and every word earns its place. It covers purpose, usage, and pairing 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 tool with one parameter, no output schema, and strong annotations, the description covers the essential information: what the tool does, when to use it, and how it relates to siblings (remember/recall). No critical context is missing.

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

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

The input schema fully describes the only parameter 'key' with the same semantics ('Memory key to delete'). The description adds no extra meaning beyond restating 'by key,' so a baseline score of 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 clearly states the tool's function: 'Delete a previously stored memory by key.' This uses a specific verb and resource, and distinguishes it from siblings by specifying 'previously stored' and pairing with 'remember and recall' for complementary operations.

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 when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' This gives clear when-to-use scenarios and mentions pairing with related tools, though it does not explicitly state when not to use it.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context by explaining the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also discloses the output format ('single text blob ready to drop at site-root/llms.txt'), 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 four sentences, each providing distinct value: purpose, process, output, and use cases. It is front-loaded with the core action and avoids redundancy. 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 tool with 2 parameters, full schema descriptions, and strong annotations, the description is highly complete. It covers the input (URL), the process, the output format, and practical use cases. It even mentions the standard llms.txt format, which is essential context. No output schema exists, so the description's explanation of the text blob output fills that 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%, and the description does not add significant meaning about parameters beyond what the schema already provides. The description mentions 'any URL' but doesn't clarify max_links semantics beyond the schema's default and max. Therefore, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL'. It uses a specific verb ('generate') and resource ('llms.txt'), and explains the process (fetches, extracts, emits). This distinguishes it from sibling tools like scan_competitor_ai_presence, which focus on auditing presence rather than generating a file.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It clearly states when to use the tool, though it does not mention alternatives or when-not-to-use conditions, 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?

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds minimal behavioral context beyond the schema, mentioning the ability to inline related records via $expand. It doesn't describe return format or error behavior, but for a read-only fetch operation this is acceptable.

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

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

The description is two sentences, front-loaded with the core purpose, and includes a concrete GUID example and optional parameters. Every sentence earns its place with no redundancy.

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

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

For a simple fetch-by-id tool with well-documented parameters and safe annotations, the description covers the essential usage. There is no output schema, but 'Fetch one record' implies the return. It could mention not-found behavior, but the description is otherwise complete for the tool's simplicity.

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

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

Schema description coverage is 100%, with each parameter (id, entity, select, expand) already well-documented in the schema. The description adds little beyond what the schema provides, only repeating the GUID example and the purpose of $select/$expand. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Fetch one Tweede Kamer record by its GUID id.' This is a specific verb and resource, and the GUID-based lookup distinguishes it from sibling search tools like query_entity or search_people.

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 direct instructions on how to use the tool: pass the entity name and the record Id, with optional $select and $expand. It gives clear context for usage, though it does not explicitly name alternative tools or state when not to use this tool.

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

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

Annotations already declare this as read-only and non-destructive. The description adds value by detailing the return fields, the scope ('caller's' subscriptions), and the default behavior of listing only active subscriptions. This gives the agent a clear picture of the tool's behavior without contradicting annotations.

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

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

The description is two sentences: the first states the purpose and output, the second provides usage guidance. No wasted words, and the key information is front-loaded.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description covers everything needed: what it returns, when to use it, and its role relative to subscribe/unsubscribe. The annotations and parameter schema complement it well.

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

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

The only parameter (include_inactive) is fully documented in the schema with 100% coverage, so the description doesn't need to add anything. The description doesn't explicitly mention the parameter but its mention of 'active subscriptions' aligns with the default. Baseline 3 applies given high schema coverage.

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

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

The description clearly states the tool lists the caller's active subscriptions and names the specific fields returned (id, type, params, etc.), making it distinct from sibling subscribe/unsubscribe tools. The purpose is specific and unambiguous.

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

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

The description provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel.' This gives clear context for when to use it, though it doesn't explicitly name alternative tools or state when not to use it.

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

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

Beyond the all-false annotations, the description discloses return behavior (claim_token when no account), the follow-up mechanism via a later pipeworx_feedback call, rate limit (5 per identifier per day), zero cost (free, doesn't count against quota), and that the team reads digests daily. No annotation 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 dense; every sentence serves a clear purpose: what the tool does, when to use it, exclusions, behavioral nuances, and limits. It is front-loaded with purpose and usage guidance, with no fluff or repetition of annotations.

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

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

With no output schema, the description fully explains the lifecycle: file with optional context, receive a claim_token, later check status. It covers all key aspects for a feedback tool, including open-world boundaries, rate limits, and costing. The description is entirely adequate for an agent to decide when and how to invoke it.

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

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

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds genuinely useful guidance: do not paste the end-user prompt, describe the issue in terms of Pipeworx tools/packs, and demonstrates claim_token syntax. This extra semantic guidance justifies a 4, though the schema already carries most of the load.

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

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

The description opens with a specific verb-resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback types (bug, feature, data_gap, praise) and explicitly excludes tools from other MCP servers, distinguishing it from sibling tools.

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

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

Provides explicit 'Use when...' criteria for each feedback type, explicit 'ONLY for tools served by this Pipeworx connection' exclusion, and directs users to file with other servers for non-Pipeworx tools. Also gives a fallback ('Not sure? Pipeworx tool names are the ones this connection lists').

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 this as read-only, open-world, idempotent, and non-destructive. The description adds valuable context beyond that: it reveals the data source ('derived from CF analytics-engine'), privacy characteristics ('no PII'), and caching behavior ('Cached 5min-1h depending on window'). This enriches the agent's understanding of freshness and data provenance.

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 with a clear one-sentence summary, followed by return details, use cases, and a technical note. Every sentence contributes information without redundancy, making it appropriately sized and easy for an agent to parse.

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

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

With no output schema, the description partially explains the return values ('top tools, top packs, and total call volume'), but it does not specify the exact structure or formatting of the response. Still, for a simple aggregate tool with one optional parameter and strong annotations, the description provides enough context to infer expected behavior.

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

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

The schema covers 100% of the parameter definitions, including the window's default and semantics. The description adds extra meaning by linking the window choice to cache freshness ('Cached 5min-1h depending on window'), which is not in the schema. This goes beyond the baseline of 3 for high schema coverage.

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

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

The description states the tool's function with a specific verb and resource: 'Returns the top tools, top packs, and total call volume over a recent window.' It clearly distinguishes itself from siblings by emphasizing the aggregate, self-aggregating nature of the data ('What other AI agents are calling on Pipeworx right now') and the use cases for discovering hot data sources and validating canonical choices.

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

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

The description provides explicit use cases for the tool: discovering hot data sources, confirming canonical tools, and checking alignment with other agents' needs. However, it does not explicitly state when NOT to use it or name alternative tools, so it falls short of the 'explicit when/when-not/alternatives' threshold.

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, but the description goes far beyond by disclosing the FILL CHECK behavior (realizable_edge_pp ≤ 0 means do not trade), the PARTITION FILTER (drops placeholder slugs, returns null signal), and the SEMANTIC ANCHOR requirement (≥0.30 Jaccard similarity). It also surfaces skipped_low_similarity, which is valuable behavioral context not implied by annotations. No contradiction is present.

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

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

The description is dense but well-structured, using labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize complex behavior. It is front-loaded with the no-args entry point and mode selection. Every sentence earns its place by adding operational detail, and there is no redundant or filler content. Given the tool's complexity, the length is justified.

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

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

With no output schema, the description compensates by outlining the response structure (opportunities[] with gap_pp, suggested_trade, reasoning, and partition_check fields). It covers all three invocation modes, edge cases like null arb signals and fill checks, and provides actionable guidance on when to use a sibling tool. This is a complete and self-sufficient description for both selection and correct invocation.

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

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

While the input schema covers 100% of parameters, the description adds significant meaning: it explains that 'event' uses event slugs or full Polymarket URLs, walks child markets, and performs date-axis/threshold-axis ordering plus partition checks. 'topic' is described as a seed question that triggers cross-event scanning, with a concrete example of the pattern it catches. This goes well beyond the schema's basic 'string' type and 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 opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this from sibling tools like polymarket_edges, polymarket_edge_tracker, and polymarket_fill_risk by focusing on arbitrage detection rather than edge tracking or fill-level risk. The mention of 'For custom sizing use polymarket_fill_risk' further delineates its 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?

Explicit usage instructions are provided: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', and 'topic for a themed cross-event scan.' It recommends event mode for specific markets and explains when cross-event mode is preferable. It also names an alternative tool for custom sizing, making the when-to-use/why crystal clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world hints. The description goes well beyond by disclosing that it returns edge_pp_net after slippage, Kelly fractions capped at 0.25, a 24h-move warning, caching behavior ('Cached 1h at KV level'), model-specific parameter details (e.g., per-sport alpha values, gate relaxations), and diagnostics for empty segments. This is rich behavioral context with no contradictions.

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

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

The description is long but densely packed with necessary domain-specific information (model families, response fields, knobs, diagnostics). It front-loads the purpose and uses clear section markers (e.g., 'TRADEABLE-EDGE KNOBS'). Each sentence earns its place, though it could be slightly more scannable with breaks; still highly efficient given the complexity.

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

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

With no output schema, the description fully explains the return structure: by_segment, fed_candidates/fed_note, and _diagnostics with funnel counters. It also explains why segments may be empty, the meaning of each key field (edge_pp_net, kelly_fraction, liquidity, spread), and the Fed signal caveat. For a complex tool with 9 parameters and no output schema, this is exceptionally complete.

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

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

Schema coverage is 100% for all 9 parameters, so the baseline is 3. The description adds substantial extra meaning by explaining the role of tradeable-edge knobs (min_liquidity/max_spread_pp drop unrealizable edges), the special behavior of min_partition_leg_kelly (per-leg Kelly inside partitions, not parent level), and the subtlety that partition arbs always return kelly_fraction_half=0 at parent level. This compensates well 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 opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly differentiates from sibling tools by emphasizing its three model families and 'what should I bet on today' use case, which is distinct from related Polymarket tools like polymarket_arbitrage or polymarket_edge_tracker.

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 it is 'Built for "what should I bet on today"' and explains that agents discover opportunities without paging hundreds of markets. It provides context on when to use it (for tradeable-edge discovery) but does not explicitly name alternative sibling tools or state when not to use them. Clear context but no exclusions, matching a score of 4.

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 richly discloses behaviors: snapshots are written on cache-miss, gaps indicate no scan, history is bounded by a 60-day TTL, and decay is computed from daily closes not intraday. It also details the response components (tracked, expired, snapshot_dates), going far beyond the annotations' read-only and idempotent hints.

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

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

Though lengthy, the description is densely structured with labeled sections (RESPONSE, LIMITS) and every sentence adds value, including the caveat about fresh vs old edges. The length is justified by the need to explain the non-obvious response semantics.

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

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

With no output schema, the description must define the return structure, and it does comprehensively (tracked[] with trend/decay, expired[] with lifespan, snapshot_dates[]). It also covers limitations like TTL and snapshot gaps, making it self-contained 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?

The input schema already documents both parameters (days and window) with descriptions and defaults, so coverage is 100%. The description only restates these defaults and adds 'max 30' which matches the schema's clamp; no additional parameter semantics are provided.

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

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

The description clearly states it provides 'Edge persistence and decay telemetry' and answers a specific question about edge age and shrinking. This distinguishes it from sibling tools like polymarket_edges by focusing on historical snapshot analysis.

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

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

The description explains the intended use case: identifying whether an edge is fresh or old to inform trade decisions. It doesn't explicitly name alternative tools for comparison, but the context makes clear when this telemetry is relevant, though it lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds behavioral detail beyond annotations: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and in basket mode identifies 'forced_directional_risk' legs. This gives useful insight into potential failure modes without contradicting the read-only nature.

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 (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). It front-loads the core purpose and then systematically details modes, parameters, and usage guidance. Every sentence carries meaningful content, though some redundancy exists between the schema and the description. Appropriately sized for a tool with two modes.

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, 4 params, no output schema), the description is highly complete. It details return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc.), explains parameter interpretation, warns about partial fills and thin legs, and provides a clear use-case context. It covers both happy path and failure modes, making it self-sufficient despite no output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial semantics beyond the schema: it explains the single-market vs basket interpretation of size_usd (max spend vs target proceeds vs settlement notional), clarifies default side behavior in basket mode, and notes the 'REQUIRES one of market or event' constraint. This enriches the parameter meaning beyond the schema 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 opens with a specific verb-resource pair: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' immediately clarifying what the tool does. It also distinguishes itself from siblings by explicitly referencing polymarket_arbitrage and polymarket_edges, framing itself as the pre-trade risk check for those tools.

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

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

The description gives an explicit when-to-use instruction: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical edge on thin books is not capturable, partial basket fills create unhedged positions), providing clear context and implicitly naming alternatives.

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

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

The description extensively details the output fields including compatibility_warning conditions, temporal_alignment, and skipped cross-type/subtype counters, which goes well beyond the read-only/idempotent annotations. It honestly notes that most pre-mapped topics are not tradeable, adding significant behavioral context.

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

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

The description is structured with TWO MODES, RESPONSE, SAFETY FIELDS headers and front-loads the core purpose. While detailed, some redundancy exists (e.g., the tradeability warning appears twice) and it runs long, but each section is scannable and valuable.

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

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

With no output schema, the description thoroughly explains the response structure, edge cases, and interpretation of safety fields, making it complete for this tool's complexity. It covers all possible output scenarios and their implications.

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

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

The schema already covers all parameters with descriptions (100% coverage), and the description adds the mode context and override behavior, enhancing understanding of how the parameters interact. The schema does the heavy lifting, but the description adds extra meaning about the two modes.

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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific modes. It distinguishes itself from Polymarket-only sibling tools by focusing on cross-venue comparison and the same outcome across venues.

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

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

The description specifies two usage modes (topic shortcuts vs explicit ticker/slug) and advises that pre-mapped topics often return compatibility warnings, implying explicit pairings are more reliable. It does not explicitly name alternative tools, but the context and guidance are clear.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior, and the description aligns with these. It adds useful behavioral context such as 'Returns matching records under `value`', 'Entity names and fields are Dutch', and 'Always set $top to bound responses'. It does not describe pagination or error behavior, but the annotations cover the safety profile.

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

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

The description is compact and front-loaded, with the core purpose in the first sentence. It includes concrete examples and an essential usage caveat without unnecessary filler. 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 an 8-parameter OData passthrough tool with no output schema, the description covers the essential operational context: entity set type, Dutch naming, return location, common query operators, and the need to bound responses. The schema covers parameter details, and annotations cover safety. It could mention paging or entity list more explicitly, but it is sufficiently complete for an agent to use correctly.

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

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

Schema description coverage is 100%, with detailed parameter descriptions already present. The tool description adds value with concrete OData examples and the emphasized $top guidance, which goes slightly beyond the schema. It does not fully compensate for the absence of an output schema, but for parameter semantics it is solid.

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 queries a Tweede Kamer OData v4 entity set with full OData passthrough. It distinguishes itself from siblings like get_entity_by_id by emphasizing entity-set-level querying and OData options. The scope, resource, and behavior are immediately obvious.

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 typical usage, including $filter, $select, $orderby, and $expand, plus the strong recommendation to always set $top. It does not explicitly name alternatives or state when not to use this tool, but the context is clear enough for an agent to choose it over more specific siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: scoping to identifier (anonymous IP, BYO key hash, account ID) and the listing behavior when key is omitted. This goes beyond the annotations without contradiction, though it could mention potential errors or rate limits.

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

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

The description is concise (three sentences) and front-loaded with the core action. Every sentence adds value: retrieval behavior, usage context, and scoping. No unnecessary 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 tool with one optional parameter and no output schema, the description is complete. It covers purpose, usage, scoping, and relationships to sibling tools. Annotations handle safety, so no major gaps remain.

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

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

Schema coverage is 100% and the schema already describes the 'key' parameter. The description adds meaning by explaining the optional behavior (omit to list all) and the type of keys (user target ticker, address, etc.), enriching beyond the schema's basic description.

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

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

The description clearly states the tool's verb ('Retrieve') and resource (saved memories), and distinguishes it from siblings by explicitly mentioning 'previously saved via remember' and 'list all saved keys'. It also clearly differentiates from 'remember' and 'forget' in the sibling list.

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

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

Provides explicit guidance on when to use: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). It also contrasts with re-deriving from scratch and pairs with remember/forget, offering clear context and implicit exclusions.

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

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

Annotations include readOnlyHint: true and idempotentHint: true, but the description states that mark_read:true flags returned events as read and makes the next call only show newer ones. This is a mutating, non-idempotent side effect, directly 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 and each sentence adds value, covering behavior, filters, side effects, and an external endpoint. It is slightly longer than necessary but remains efficient and well-structured.

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

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

With no output schema, the description compensates by detailing the return payload (source, citation_uri, raw event payload) and explains filtering, mark_read behavior, and polling. Some details like limit and unread_only are left to the schema, which is acceptable.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds concrete examples like type 'sec_8k' and ISO timestamps, and explains the mark_read side effect beyond the schema's basic definition.

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

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

Clearly states it pulls fired events from the user's subscription feed and returns the most recent alerts with metadata like source and citation_uri. This distinguishes it from siblings such as list_subscriptions and recent_changes.

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 says polling works fine and points to an alternate HTTP endpoint for scripts and dashboards, giving clear context for usage. However, it does not explicitly compare against sibling tools or state when not to use it.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds rich behavioral detail not present in the annotations: the fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail due to API sunset, and the returned citation URIs. It also signals rate-limit/failure behavior.

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

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

The description is a dense, single block of text, but every piece earns its place: use cases, source fan-out, fallback behavior, parameter expectations, and return summary. It is front-loaded with the user-intent phrases, though it could be slightly better structured with more whitespace or bullets.

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 the return shape (structured changes[] grouped by source, total_changes count, pipeworx:// citation URIs), the data sources, and failure modes. This is a complete picture for a complex tool with no 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%, so the baseline is 3. The description repeats the `since` format and provides examples ('7d', '30d') already present in the schema, and clarifies `value` accepts ticker or CIK — but these are already documented. It adds no substantial new parameter semantics beyond the schema.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, with explicit user-facing phrasings ('What's new with X', 'updates on Acme'). It distinguishes itself from the sibling entity_profile by contrasting the change feed with the static profile tool.

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

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

It gives concrete example queries and states the exact alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This provides a clear when-to-use and when-not-to-use directive, plus context on the parallel fan-out behavior.

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

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

Annotations cover idempotency and non-destructiveness, but the description adds valuable behavioral context: key-value pairs scoped by identifier, persistent vs 24-hour anonymous memory, and pairing with recall/forget. This goes beyond annotations without contradicting them.

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

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

Three sentences, front-loaded with the core purpose, followed by usage guidance, storage details, and retrieval/deletion pairing. Every sentence contributes meaningful information with 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?

For a 2-parameter, no-output-schema tool, the description covers the what, when, how, and persistence. It fully compensates for the lack of an output schema and leaves no significant operational questions unanswered.

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

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

Schema coverage is 100%, with descriptions for both key and value including examples. The description only restates the key-value relationship and adds no deeper semantics beyond what the schema already provides, 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 opens with 'Save data the agent will need to reuse later', clearly identifying the action and resource. It distinguishes from siblings by pairing with recall and forget, and provides concrete examples like 'resolved ticker, target address, user preference' 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?

It explicitly states when to use: 'Use when you discover something worth carrying forward...' and clarifies persistence across conversation/sessions. It does not list exclusions, but clearly frames the tool's niche versus recall and forget, giving sufficient context for an agent to decide.

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

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

Beyond annotations (readOnlyHint, idempotentHint, openWorldHint), the description reveals critical behavioral traits: it cascades through multiple lookup endpoints internally, degrades gracefully when GLEIF or OpenFIGI are unavailable, explicitly reports unresolved identifiers under an 'unresolved' key, and explains that ISINs resolve to legal entities via GLEIF. No contradiction with annotations exists.

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

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

The description is a single dense paragraph containing a wealth of information. While all content is relevant, it lacks structural breaks (e.g., bullet points for supported types), and some redundancy exists (e.g., the initial list of identifiers is repeated inside the 'company' description). It is longer than necessary, though 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?

Given the absence of an output schema, the description compensates well by explaining what the tool returns (canonical identifiers with source labels, unresolved list). It covers graceful degradation, cross-source resolution logic, and the range of input types. It does not explicitly enumerate the output fields, but the detail provided is sufficient for an agent to understand the response shape.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial value by expanding on parameter semantics: for `type`, it explains the resolution process per entity type; for `value`, it provides concrete examples (ticker, CIK, ISIN, brand/generic names) and explains how ISINs are mapped to legal entities. This goes well beyond the schema's minimal 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 starts with concrete user query examples (e.g., 'What's the ticker for…'), clearly states the verb 'resolve a user-spoken NAME to the canonical/official identifiers', and distinguishes itself from sibling tools like get_entity_by_id by explicitly saying 'Use FIRST whenever you have a name but need an ID.' It specifies the supported entity types (company, drug) and the scope of resolution, making the purpose highly specific and actionable.

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

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

The description explicitly tells the agent when to use this tool ('Use FIRST whenever you have a name but need an ID'). It provides ample examples of query patterns (ticker lookup, CIK, ownership checks, ISIN resolution) that implicitly signal when not to use it (e.g., when you already have an ID). However, it does not explicitly name alternative tools for those cases, so a slight gap remains.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds valuable behavioral context beyond annotations: it discloses that the tool probes each entity with ai_visibility_check, ranks results, and returns a ranked list including score, confidence, and signal density. This provides insight into the tool's internal operation without any 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 three sentences, front-loads the core purpose, and packs in mechanism, use case, and return format without redundancy. Every sentence contributes meaningful information, and it is concise for a tool of this complexity.

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

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

Given no output schema, the description appropriately explains the return value (ranked list with score, confidence, signal density). Combined with full schema parameter descriptions and safety annotations, the description covers all essential aspects of the tool's behavior, use case, and outputs. No significant gaps remain.

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

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

The input schema already provides full descriptions for all four parameters (100% coverage), including the semantic distinction of the first entity as the subject and the optional API key for Anthropic models. The description adds little beyond rephrasing 'entities' as 'your brand + competitors,' which is already captured in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, ranks them by score, and identifies the most/least recognized. It explicitly distinguishes itself from related tools by naming ai_visibility_check as the underlying probe and focusing on comparative ranking, making it highly specific.

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

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

The description provides a concrete use case (competitive AI-marketing audits) and an example query ('does Claude know about us as well as our competitors?'), which strongly implies when to use the tool. It does not explicitly exclude alternatives like compare_entities, but the context is clear enough for an agent to select it appropriately.

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 read-only hints in annotations by detailing the composite fan-out behavior across two services, the exact return payload (summary block, per-advisory detail, links, alternative versions), and the graceful degradation of partial failures. It also discloses the potential 5-30s delay for bundlephobia's first measurement, which is important operational knowledge absent from structured fields.

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 organized with the core purpose front-loaded, followed by a clear 'use when' statement, return value summary, ecosystem caveat, and failure behavior. Every sentence contributes distinct, non-redundant information, and the length is justified given the tool's complexity.

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

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

Since there is no output schema, the description compensates by enumerating the summary fields, per-advisory details, links, and alternative versions returned. It also explains the partial-failure behavior and the NPM-only scope, making the description complete enough for an agent to invoke the tool confidently without needing further context.

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 full schema descriptions, so the description adds little new semantic meaning. The 'NPM ecosystem only' note reinforces package scope but is largely redundant with the schema field that already calls it an npm package name. The description does not introduce any syntax or format details beyond the schema, so the baseline 3 for high schema coverage 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 and resource: a composite 'should I add this npm package' check. It clearly distinguishes itself by naming the two data sources (deps.dev and bundlephobia) and by explicitly limiting to the NPM ecosystem in v1, thereby differentiating from the alternative 'deps.dev:version' path mentioned for other ecosystems.

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 exactly when to use the tool: whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also provides an exclusion/alternative by noting that PyPI/Maven/Cargo/Go packages should fall under deps.dev:version directly, giving the agent clear guidance on when not to use this tool.

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

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

Annotations already cover readOnly, idempotent, and non-destructive hints. The description adds valuable behavioral context: case-insensitive substring matching and the specific fields searched (surname, first name). It also discloses the return fields (id, name parts, role, party label), which is useful because there is no output schema.

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 succinct, three sentences that cover purpose, matching behavior, and return values. Every sentence adds distinct 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?

For a simple search tool with 3 parameters and no output schema, the description is complete: it explains what the tool searches, how it matches, and what it returns. Annotations cover safety, and the schema covers parameter details, so nothing is missing.

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

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

Schema coverage is 100%, so parameters are fully described. The description adds meaning beyond the schema by explaining the matching behavior (case-insensitive substring) and explicitly tying the 'field' parameter to surname/first name, which clarifies how the 'name' parameter is interpreted.

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 action ('search') over a defined resource ('Tweede Kamer members/people (Persoon entity)') with a specific scope ('by name'). It differentiates from general search tools like 'search_within' by targeting people and specifying matching fields (surname/first name).

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 when to use this tool: when you need to find a person by name. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it over generic search tools. The 'Convenience search' label signals a specialized wrapper.

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 behavior beyond the annotations, such as the embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), and a 200K char cap with 'truncated and flagged' behavior. This provides crucial operational context that annotations alone do not convey. It also states that returned passages include offsets, enabling verification.

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 yet efficient, with every sentence serving a purpose. It front-loads the core functionality, then covers use case, pairing, and technical details without redundancy. The structure flows logically from definition to usage to limitations.

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 3-parameter tool with no output schema, the description is remarkably complete. It covers return value structure (passages with offsets and scores), performance characteristics (cap, truncation), and integration with a sibling tool. No critical aspect is omitted.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter semantics beyond the schema, such as implying 'text' is previously fetched content ('the text you already pulled') and giving query examples. However, it does not substantially enrich the meanings of 'limit' or 'text' beyond what the schema already provides.

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

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

The description clearly defines the tool as 'Semantic search INSIDE a fetched record' with a specific verb and resource, and distinguishes it from siblings by emphasizing it works on user-supplied text. It also specifies the output (top-N passages with character offsets and similarity scores), making the 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?

It explicitly states the primary use case: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' It also provides an alternative and complementary workflow by pairing with ask_pipeworx_grounded, giving clear guidance on when to use this tool versus alternatives.

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

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

Adds substantial context beyond annotations: OAuth requirement, persistent feed, email/sms/webhook details, phone verification, rate cap, webhook signing, and return value. No contradiction with annotations.

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

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

The description is dense and front-loaded with purpose, but it is somewhat long and duplicates schema details. Nonetheless, each sentence provides useful context.

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

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

For a complex tool with nested objects and no output schema, the description covers all necessary aspects: return value, authentication, supported types, delivery methods, and special constraints. It is complete.

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

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

The schema already fully documents all parameters with 100% coverage. The description repeats and provides examples (e.g., items:['5.02'] = officer change) but adds limited new semantics beyond the schema.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource, and mentions 'Returns the new subscription id.' This distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides context on when to use: requires a Pipeworx OAuth account, supports specific subscription types, and explains delivery channels. It does not explicitly name alternatives or exclusions, but the context makes it clear this is the creation 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 this a read-only, open-world, idempotent operation. The description adds that it draws from the live catalog of thousands of tools and returns exact tool+argument shapes, which is valuable behavioral context beyond annotations.

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

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

The description is long but information-dense, front-loaded with example user queries, and each clause adds specific detail about categories, return format, and usage. Slight redundancy with the schema but overall efficient for a tool of this complexity.

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

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

For a tool with one optional parameter and no output schema, the description fully covers what it returns, how to invoke it, and when to use it. It also names the meta-tools it can teach, making the context 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?

The schema describes the topic parameter with enum-like values and instructions to omit for a cross-category spread. The description reinforces with concrete examples ('finance', 'pharma', 'betting') and the same omission guidance, adding modest value beyond the schema.

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

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

The description clearly defines the tool as the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape. It distinguishes from siblings by explicitly mentioning meta-tools and focusing on 'what can I ask.'

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

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

It provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains the optional topic parameter for focusing, giving clear context for when to use it versus when to call with no arguments.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds important behavioral details: the row is deactivated not deleted, ownership is enforced, and historical events remain accessible via recent_alerts. This enriches the safety and side-effect understanding.

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

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

Two sentences, front-loaded with the core action, and every clause earns its place. 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?

For a simple one-parameter tool with no output schema, the description covers the core behavior, ownership boundary, and data persistence impact. It is sufficiently complete for an agent to invoke correctly and understand consequences.

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

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

Schema coverage is 100% with one parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description adds no new parameter semantics beyond saying 'by id', so it meets the baseline but does not exceed it.

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

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

The description states 'Cancel a subscription by id' with a specific verb and resource. It clearly distinguishes from sibling tools like subscribe and list_subscriptions through the cancel action and ownership constraint.

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

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

It provides clear context: ownership is enforced and the operation deactivates rather than deletes. However, it does not explicitly state when not to use this tool or directly name alternatives like subscribe or list_subscriptions, though mentioning recent_alerts for historical events gives some cross-reference.

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 readOnly/idempotent, but the description adds critical behavioral context: 'could_not_verify' means the check did not happen and must not be used as evidence, while 'unsupported' means no source exists. It also discloses error details, verdict types, and citation format, which is beyond annotation scope.

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

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

The description is thorough and front-loaded with query examples, but it is somewhat long. It includes valuable details on routing, verdicts, and error handling, with minimal redundancy, though a slight condensation would make it more concise.

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

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

Given there is no output schema, the description fully covers return values (verdicts, reasoning, citation), failure semantics (could_not_verify vs unsupported), and routing rules. It provides a complete picture for an agent to invoke the tool correctly, including edge cases.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds 'exact percent-delta math' and 'capped at 5' context for tolerance, but mostly echoes the schema's claim examples and parameter descriptions without significantly extending understanding.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with specific examples like 'fact check' and 'verify the claim that...'. It distinguishes itself from sibling tools by explaining the end-to-end pipeline and noting it replaces multi-step calls, making its function unambiguous.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use context. It also describes internal routing for different claim types, but does not explicitly name sibling alternatives for when-not-to-use, which would earn a 5.

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