Passwordgen

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value beyond annotations by detailing the default model (Workers AI Llama-3.3-70b, free), the optional Anthropic probing with BYO key and direct billing, and the return format (per-model object + combined view). No contradiction with annotations.

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

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

Two sentences, each earning its place. First sentence front-loads the core purpose and scoring. Second sentence adds key detail on defaults, API key use, and return format. No redundancy or unnecessary words.

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

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

Given the tool's moderate complexity (4 params, no output schema), the description is complete enough. It explains purpose, defaults, optional key, return structure, and use cases. Minor gap: does not mention rate limits or error handling, but overall sufficient for selection and invocation.

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

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

Schema description coverage is 100% (all 4 parameters documented in input schema). The description adds extra meaning: entity includes examples, models explains default behavior, _apiKey clarifies billing, and context explains use. This exceeds the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It specifies the verb 'probe' and the resource 'LLMs', and distinguishes from siblings by focusing on AI visibility scoring, which is unique among the listed siblings.

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

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

The description explicitly suggests use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. While it does not state when not to use or list alternatives, the context is clear enough for an agent to decide.

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

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

Annotations already declare the tool as read-only, idempotent, and open-world. The description adds valuable behavioral context: it routes to 5,008 tools across 1,318 sources, returns structured answers with stable citation URIs, works on every tier, and is a fast single call. No contradiction with annotations.

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

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

The description is relatively long but well-structured: front-loaded with the key preference directive, followed by functionality, then examples, then sibling comparisons. Every sentence adds value, though it could be slightly shorter without losing clarity.

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

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

Given the complexity (6 parameters, no output schema), the description is complete. It explains what the tool returns (structured answers with citations), when to use, alternatives, and provides varied examples. It handles the lack of output schema by describing the output nature.

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

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

Schema coverage is 100% with all parameters being aliases for the question string. The description mentions that the question is in natural language and lists the aliases again, adding minimal new meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: it routes questions to authoritative structured data sources and returns answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded (hallucination-resistant single answer) and deep_research (broad multi-part questions), making it easy for the agent to select the right 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?

The description provides explicit guidance: 'PREFER OVER WEB SEARCH for questions about current or historical data...', 'START HERE for most questions', and specifies when to step up to alternatives (ask_pipeworx_grounded, deep_research). It also gives concrete examples of when to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds valuable context about source-preference ranking and that it is a full working router, not a fallback. However, does not detail what 'candidate routing improvements' entail.

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

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

Two concise sentences front-load key identity and usage information. Every sentence adds value with no redundancy.

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

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

Adequately describes the tool's role, relationship to sibling, and behavioral traits. No output schema exists, but description notes 'same response shape' as ask_pipeworx, providing enough context for invocation.

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

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

Schema coverage is 100% with all parameters documented (many aliases for question). Description mentions 'same arguments' but adds no extra meaning beyond schema.

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

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

Clearly states it is a beta version of ask_pipeworx with identical routing but experimental improvements like source-preference ranking. Distinguishes itself from the stable sibling ask_pipeworx.

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

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

Explicitly tells when to use: 'when you want the newest routing'. Also describes fallback behavior and comparison with stable router, guiding appropriate selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds context on hallucination resistance, explicit refusal reasons, and cost trade-off. No contradiction.

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

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

Well-structured with purpose first, then mechanism, return format, use cases, and cost comparison. Each sentence adds value, though slightly longer than 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?

Given complexity (refusal logic, multiple sources, cost), description covers return format, refusal reasons, and trade-off with sibling. No output schema, but description is complete enough.

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

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

Input schema has 6 parameters all aliases for question with 100% description coverage. Description adds no new meaning beyond noting aliases, 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?

Clearly states it's a hallucination-resistant answer mode for high-stakes reads, explaining the process of routing, fetching, and extracting answer only from tool result. Distinct from sibling ask_pipeworx.

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

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

Explicitly specifies when to use: for answers that will be quoted, cited, or acted on, and when not to: prefer ask_pipeworx for casual lookups. Provides clear alternatives.

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

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

The description extensively discloses behavior beyond annotations: market resolution, classifier, fan-out examples, response shapes, resolver contract, parent extractor, news fallback, safety short-circuits, and resolution-rule risk. Annotations provide read-only and idempotent hints, but the description adds critical 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 lengthy but well-structured with bold section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). Each section adds necessary detail, though some parts could be tightened (e.g., 'In practice resolved markets...'). Overall, it earns its length.

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

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

Given the tool's complexity, lack of output schema, and 3 parameters, the description is exceptionally complete. It covers behavior, response structure, error cases, safety, and resolution-rule risk, leaving no major gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining the 'market' parameter accepts slugs, URLs, or questions, and provides examples. For 'depth' and 'include_raw', it clarifies behavior and default vs. use cases.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data in one call. It specifies the verb 'research', the resource 'Polymarket bet', and the method. It distinguishes from siblings like 'polymarket_edges' which focus on different aspects.

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

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

The description explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It provides clear context but does not explicitly state when not to use the tool or name alternatives.

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

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

Annotations already declare readOnly, idempotent, openWorld. Description adds key behaviors: off-calendar fiscal year handling, sorted results, citation URIs in response. 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?

Front-loaded with example queries and packed with useful details. Every sentence adds value, but slightly long. Could be tightened slightly.

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

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

No output schema, so description must explain return format. Mentions 'paired data + pipeworx:// citation URIs' and sorted by primary metric. Adequate for a complex tool, but could detail response structure more.

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

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

Schema coverage is 100%; description adds significant meaning: explains what data each type fetches, that values are tickers/CIKs for company and drug names, and enforces min/max items. Compensates well beyond schema.

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

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

Description clearly states side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs). Distinguishes from sequential lookups and sibling tools like entity_profile.

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

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

Explicitly recommends over sequential lookups with example queries. Provides constraints (2-5 entities, one call). Could be improved by mentioning when not to use (e.g., single entity or more than 5), but still strong.

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 as non-destructive. The description adds extensive behavioral context: parallel decomposition, tool routing, output findings packet (evidence, confidence, source, citations, gaps, contradictions), per-depth behavior, hop field, semantic excerpting, and timing estimates. 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?

While front-loaded with account requirement and fallback, the description is verbose and includes some jargon (e.g., 'pipeworx:// citation') that may hinder quick scanning. It could be more concise while retaining essential details.

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

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

Given the tool's complexity (depth levels, account tiers, output structure, fallback) and no output schema, the description is quite complete. It covers output findings, gaps, contradictions, citations, and timing. However, the exact JSON structure of the findings packet is not specified, which slightly limits completeness.

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

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

Schema coverage is 100%, providing baseline 3. The description adds significant value by explaining the depth enum values in detail (quick=3 facets, standard=5 with gap recovery, thorough=8 with iterative hop) and clarifying that the question parameter accepts broad multi-part queries. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: grounded multi-source research across 1318 structured data sources in a single call. It explicitly distinguishes from siblings like ask_pipeworx (single lookup, current news) and mentions alternative use cases.

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 (broad/multi-part structured questions) and when-not-to-use (single lookups, current news), along with fallback instructions (ask_pipeworx, ask_pipeworx for breaking news). It also notes account tiers and prerequisites.

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 beyond this by explaining that results include full input schemas with curated examples, are ready to call directly, and that the tool accepts multiple aliases for the query. It does not contradict annotations and provides useful behavioral context about the output format.

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, beginning with the core purpose and followed by example domains and key details. It is fairly concise, though the list of domains could be shortened without loss of clarity. Overall, it is efficient and front-loaded with the most important information.

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

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

Given the tool's role (search/discovery) and the absence of an output schema, the description adequately explains what is returned: 'names, descriptions, and full input schemas (with curated examples)' and that results are ready to call. It also describes the limit parameter. This provides sufficient context for an AI agent to understand the response structure, though more detail on the exact format could improve completeness.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reiterates that q, task, search, description are aliases for query and notes the default and max for limit, but these details are already in the schema. No additional semantic value is added beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous example domains (SEC filings, financials, FDA drugs, etc.) and explains that it returns top-N relevant tools with names, descriptions, and schemas. This distinguishes it from sibling tools, which are specific data-access tools, making its role as a meta-discovery tool 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?

Explicitly instructs: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance. It does not explicitly state when not to use it, but the context implies it is not needed when the user already knows the specific tool. It lacks mention of alternatives, though siblings are not alternatives to 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 readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable behavioral context: it fans out across multiple sources, makes a parallel call, and mentions the patent API sunset (soft-fails). However, it does not detail potential rate limits or other failure modes. Still, it adds sufficient 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 a single dense paragraph but front-loaded with example queries. It contains all necessary information without excessive verbiage. Slightly more structured formatting (e.g., bullet points) could improve readability, but overall it is 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?

Despite no output schema, the description thoroughly lists return elements (cik, filings, fundamentals, patents, news, LEI) and notes edge cases like the patent soft-fail. For a complex aggregation tool, it provides complete context for the agent to understand what it returns and how it behaves.

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 description adds crucial meaning: it clarifies that the 'type' parameter only supports 'company' (with person/place coming soon) and that 'value' must be a ticker or zero-padded CIK (names not supported). This extra context helps the agent use the parameters correctly.

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

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

The description uses specific verbs and resources: 'full cross-source profile of a US public company'. It clearly distinguishes from sibling tools like 'resolve_entity' (for names) and 'compare_entities' (for comparison). The description also provides example queries, 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?

The description explicitly states when to prefer this tool over chaining individual lookups: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when not to use it: 'names not supported (use resolve_entity first if you only have a name).' This provides clear guidance on alternatives and exclusions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description confirms the destructive nature ('Delete') but adds no new behavioral details beyond usage context. It does not contradict annotations.

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

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

The description is two sentences: first sentence states purpose, second provides usage guidance and pairs with siblings. No extraneous information, perfectly 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 tool with one required parameter, no output schema, and annotations covering safety, the description fully addresses when to use and how it relates to other tools. It is complete for the complexity level.

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

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

The single parameter 'key' is fully described in the schema (schema description coverage 100%). The tool description mentions 'by key' but adds no parameter meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key.' It specifies the action (delete) and the resource (memory by key), and distinguishes from siblings like 'remember' and 'recall' explicitly.

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

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

The description provides explicit when-to-use scenarios: when context is stale, task is done, or to clear sensitive data. It also pairs with alternatives ('Pair with remember and recall'), giving clear 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' 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?

Two sentences, front-loaded with purpose, concise details, no redundant information. Every sentence adds value.

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

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

No output schema but description explains output as 'single text blob ready to drop at site-root/llms.txt.' Context covers target audience and use cases. Could mention error handling or rate limits but not critical given readOnly hint.

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 (url, max_links). Description repeats schema info ('Full URL', 'Maximum number of link entries') without adding new semantics. Baseline 3 is appropriate.

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

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

Clearly states 'Generate a production-ready llms.txt file for any URL' with specific verb and resource, mentions target AI crawlers (ChatGPT, Claude, Perplexity), and is distinct from all sibling tools (none similar).

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

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

Provides clear contexts: '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.' Does not explicitly state when not to use or name alternatives, but no relevant siblings exist.

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 safe properties (readOnly, idempotent, not destructive). Description adds context about randomness source (CSPRNG) and output details (entropy), enhancing transparency.

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?

Single sentence, front-loaded with core action, no wasted words. Efficient and clear.

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

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

No output schema, but description mentions return includes password(s) and entropy. Covers main aspects for a password generator.

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

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

Schema covers all 7 parameters with descriptions (100% coverage). Description adds minimal extra meaning beyond 'control character sets and length.' Baseline 3.

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

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

Description clearly states action (generate), resource (password), and key attributes (cryptographically-random, offline, CSPRNG). It distinguishes from sibling generate_pin.

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?

No explicit guidance on when to use this tool vs alternatives. Mentions keyless/offline but doesn't specify scenarios or when not to use.

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 no destructive action. The description adds context: 'cryptographically-random' indicates strong randomness, and 'keyless, offline' suggests no external dependencies. This extends beyond the annotations without contradicting them.

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

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

Single sentence, no filler, front-loaded with key information. Every word serves a purpose, making it easy for the agent to quickly grasp the tool's function.

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

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

For a simple tool with no output schema, the description explains what it does but not what it returns (e.g., whether output is a single PIN string or array). This omission leaves the agent uncertain about the return format, which is a gap for a straightforward generation tool.

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

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

Schema coverage is 100%, with each parameter already described (count and length). The description does not add any new information about parameter semantics, such as defaults or constraints. Baseline 3 is appropriate since the schema handles the documentation.

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

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

The description clearly states the tool generates a cryptographically-random numeric PIN. It specifies 'keyless, offline', distinguishing it from sibling tools like 'generate_password', which likely produces alphanumeric passwords. The verb and resource are precise.

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?

No explicit guidance on when to use this tool vs alternatives. While it's implied for numeric PINs, there is no mention of when not to use it or comparison to 'generate_password'. The description assumes the agent will infer usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety and idempotency are clear. The description adds that only active subscriptions are returned by default, but it does not contradict annotations. With rich annotations, the description adds moderate value.

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

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

The description is two sentences long, front-loaded with the core purpose, and contains no unnecessary words. Every sentence adds value.

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

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

Given the tool's simplicity (one optional boolean parameter, no output schema, rich annotations), the description is complete. It covers purpose, usage guidance, and parameter behavior adequately.

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

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

Schema coverage is 100% for the single parameter, and the description does not add additional meaning beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

The description explicitly states 'List the caller's active subscriptions' and enumerates the return fields (id, type, etc.), making the purpose very clear. It also implicitly distinguishes from siblings like subscribe/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?

The description advises using the tool 'to review what you're monitoring before adding more or to find an id to cancel', providing clear guidance on when to use it. It could explicitly mention when not to use it, but the context is sufficient.

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

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

Annotations provide no behavioral hints (all false). Description compensates fully: states rate limit of 5 per identifier per day, free usage, and explains team reads digests daily and affects roadmap. No contradictions.

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

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

Concise yet comprehensive: 5-6 sentences covering purpose, when to use, rate limits, and parameter guidance. Front-loaded with verb and resource. No unnecessary words.

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

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

For a simple feedback tool with no output schema, the description covers everything needed: usage, parameters, limitations, and team impact. No 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% but description adds meaning: explains enum values in detail, provides context on message format and length, and clarifies the optional context object's purpose (which tool, pack, vertical).

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

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

Clearly states the tool is for sending feedback about Pipeworx tools/packs. Differentiates from siblings by specifying categories (bug, feature, data_gap, praise) and explicitly excludes sharing end-user prompts.

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 scenarios: for bugs, feature requests, data gaps, praise, or other. Also includes what not to do (don't paste end-user prompt) and mentions rate limits and free usage.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral context: data source ('CF analytics-engine'), no PII, caching window (5min-1h). 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?

Text is concise with front-loaded main output, followed by bullet-like use cases. Every sentence serves a purpose 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?

Given full schema coverage, comprehensive annotations, and description explaining return structure and caching, the definition is complete for effective use.

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

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

Schema has 100% coverage for the single parameter 'window' with description. The description adds value by explaining trade-offs ('shorter windows surface what's hot right now; longer windows show steady-state demand'), beyond schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a window, with specific verb 'Returns' and resource. It distinguishes from siblings like 'discover_tools' by focusing on trending data.

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

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

Explicitly provides three use cases (discovering hot data sources, confirming canonical tools, aligning use cases). Does not state when not to use or list alternatives, but the context of sibling tools implies its niche.

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

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

Annotations indicate safe, read-only, idempotent behavior. Description adds extensive behavioral details: searches top ~200 markets, walks child markets, checks ordering, computes partition check, uses Jaccard similarity >=0.30, drops placeholder slugs, performs fill check against CLOB depth. 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?

Description is long but well-structured, starting with general purpose, then modes, then algorithmic details. Every sentence contributes necessary information. Could benefit from section breaks, but overall efficient.

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

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

Given the complexity and lack of output schema, description provides good detail on response structure (opportunities[], partition_check) and algorithms. Some minor gaps (e.g., exact types), but sufficiently complete for an agent to understand output.

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

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

Schema has 100% description coverage for both parameters. Description enriches by providing examples of event slugs and seed questions, and explains the no-arg case. Adds value beyond schema 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 states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific use cases. The purpose is precise 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?

Provides explicit guidance on when to use each mode: 'Call with NO args for trending_scan', 'event (recommended for a specific market)', 'topic for cross-event scanning'. Also explains when not to trade based on fill check and references polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds valuable behavioral context: caching (1h at KV level), edge_pp_net after slippage, Kelly fraction caps, 24h-move warning, and limitations like placeholder filters and Fed note. 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 lengthy but well-structured with bolded section headers and logical progression. Every sentence adds value, but some details (like exact historical gate values) could be trimmed for conciseness. Nonetheless, it remains readable and informative.

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

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

Despite having 9 parameters and no output schema, the description covers the response structure (by_segment, diagnostics), explains why segments might be empty (filter_skips), and describes each field in the opportunities. This gives the agent a complete mental model of the tool's behavior and output.

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

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

Although schema coverage is 100%, the description adds significant extra meaning for each parameter: e.g., for min_liquidity it suggests a value (5000) and explains why; for max_spread_pp it recommends setting to 2; for min_partition_leg_kelly it clarifies its purpose and how it differs from min_kelly. This greatly enhances agent 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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the use case 'what should I bet on today' and distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx disagreement and automatic discovery.

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

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

The description explicitly says the tool is built for discovering opportunities without paging hundreds of markets, and provides guidance on tradeable-edge knobs like min_liquidity and max_spread_pp. It also notes limitations (e.g., Fed bets are excluded) but does not explicitly state when to avoid the tool or contrast with 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 indicate read-only, idempotent, non-destructive behavior. The description adds rich behavioral details: response structure (tracked, expired, snapshot_dates), decay calculation method, data source gaps, and limitations. No contradiction with annotations.

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

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

The description is detailed but well-structured, with purpose front-loaded, response format explained, and limitations at the end. Slightly long but every sentence adds value, so high marks.

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 fully defines the response structure (tracked, expired, snapshot_dates) and covers limitations. The tool is simple with two optional params, so the description is sufficiently 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?

Both parameters are fully described in the input schema. The description adds meaning by explaining 'snapshot family' for window, clarifying the lookback for days, and noting cache-miss behavior, which enhances understanding beyond the schema.

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

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

Clearly defines the tool as providing edge persistence and decay telemetry from daily polymarket_edges snapshots, answering a specific question about edge age and decay. Distinguishes from siblings like polymarket_edges by focusing on time-series analysis rather than current edges.

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

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

Provides context with the example of a fresh vs 3-week-old edge, implying when to use this tool for historical analysis. Mentions limitations like 60-day TTL and data gaps, but does not explicitly contrast with alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds detailed behavioral context: walks the order book ladder, returns top-of-book depth, slippage, fills, and a verdict. It explains how size_usd is interpreted differently per mode and warns about unhedged directional risk, going well 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 lengthy but well-structured with bold section headers (REQUIRES, SINGLE-MARKET, BASKET) and a final usage note. Every sentence provides essential information for a complex tool, so the length is justified. Slightly more concise wording could improve it, but it remains clear and organized.

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

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

Given no output schema, the description must document return values, and it does so thoroughly. It enumerates all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp for single-market; theoretical_sum, capture_ratio, thin_legs for basket) and explains verdict labels. This ensures an agent can fully understand what the tool provides.

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

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

Schema coverage is 100%, but the description significantly enhances each parameter. It explains the dual-mode behavior for `market` vs `event`, default `side` logic for basket mode, and how `size_usd` is treated (max spend vs target proceeds for single-market, settlement notional for basket). This adds crucial context not present in schema descriptions.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth, with two distinct modes (single-market and basket). It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying its role as a pre-trade validation.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', provides rationale (theoretical overround not capturable, partial fills cause directional risk), and specifies required parameters for each mode.

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?

Provides extensive detail beyond annotations: response fields (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning with two cases, temporal_alignment, skipped counters). Annotations are readOnlyHint=true, which aligns with read-only data retrieval described.

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, starting with a high-level definition, then modes, response structure, and safety fields. Every sentence adds information, though it could be slightly more compact without losing clarity.

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

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

Given the complexity (3 optional params, no output schema), the description is highly complete. It covers response details, edge cases, safety warnings, and temporal alignment, ensuring the agent understands when spreads are meaningful.

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

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

Schema description coverage is 100% for all three parameters. The description adds value by explaining the 'topic' shortcuts with an explicit list, the override behavior for explicit tickers, and the exclusive nature of topic vs. explicit 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 it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and contrasts with siblings like polymarket_arbitrage by focusing on inter-venue differences.

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

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

Explicitly explains when to use (to compare prices across venues) and when not (compatibility_warning indicates non-equivalent bet shapes or temporal mismatch). It also manages expectations that pre-mapped topics often yield non-tradeable spreads.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds scoping details (scoped to identifier) and clarifies the non-destructive nature, adding value 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 two sentences, well-structured with core function first and usage details second. Every sentence is meaningful 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?

Despite lacking an output schema, the description explains return behavior (value or list of keys), scoping, and relationships with siblings, making it fully complete for its complexity.

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

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

The schema covers 100% of parameters. The description adds semantic context by explaining the behavior when key is omitted (list all keys) and gives examples of stored values (ticker, address, notes), enhancing 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 it retrieves a value previously saved via remember or lists all keys when omitted. It uses specific verbs ('Retrieve', 'list') and distinguishes itself from sibling tools like remember and forget.

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

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

The description explains when to use the tool (to look up context stored earlier) and how to use it (omit key for listing all keys). It also explicitly pairs it with remember and forget, providing excellent usage guidance.

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

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

Annotations indicate it's read-only, open-world, idempotent, and non-destructive. The description adds behavioral context, such as the mark_read parameter's effect on subsequent calls, and details about return fields. No contradiction with annotations.

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

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

The description is a single paragraph, front-loading the purpose. It is efficient but could be more structured with bullet points for parameters. Every sentence adds value, with no wasted words.

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

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

No output schema exists, so the description compensates by explaining return values (source, citation_uri, payload). It covers filtering, mark_read behavior, and polling vs HTTP endpoint. Adequate for a tool with 5 optional parameters.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description reinforces usage (e.g., 'Filter by type (e.g. "sec_8k") and/or since'), but adds minimal extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states 'Pull fired events from your subscription feed' using a specific verb and resource. It distinguishes the tool from siblings like 'recent_changes' by focusing on alerts with specific fields (source, citation_uri, payload).

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 mentions that polling works fine and points to an HTTP endpoint for scripts/dashboards, but does not explicitly state when to use this tool versus alternatives or when not to use it. Usage context is implied but lacks 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 declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral details: fan-out to multiple sources, GDELT→GNews fallback, USPTO soft-fail, return structure (changes[] grouped by source, total_changes count, citation URIs). 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 somewhat long (three sentences) but efficiently packs essential information. Every sentence adds value—purpose, usage guidance, and behavioral details. Slight reduction could improve conciseness, but it is well-structured and 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?

Given no output schema, the description thoroughly explains the return format (structured changes grouped by source, total count, citation URIs) and covers input semantics, source behavior, fallbacks, and soft-fails. It also references the alternative tool for static profiles, making it complete for a 3-parameter tool.

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

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

Schema coverage is 100% with detailed descriptions. The description adds valuable context: 'since' accepts ISO dates and relative shorthand with examples, 'type' is restricted to 'company', and 'value' can be a ticker or zero-padded CIK. This enhances understanding beyond the schema.

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

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

The description clearly states that the tool retrieves recent changes for a company from multiple sources (SEC, GDELT/GNews, USPTO) within a time window. It distinguishes itself from the sibling tool 'entity_profile', which provides static profiles, making the purpose 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 example queries ('What's new with X', 'latest on Y') and directs users to 'entity_profile' for static profiles. It also explains parameter usage for 'since' and the fallback behavior between GDELT and GNews. However, it does not explicitly state when not to use the tool, though the context is clear.

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

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

Annotations indicate mutation and idempotence. Description adds persistence details (24h for anonymous, persistent for authenticated) and scope by identifier, enriching 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?

Four sentences with no redundancy. First sentence immediately conveys purpose. All information is essential 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?

For a simple key-value store, the description covers usage, persistence, and pairing. No output schema needed. Adequately complete given tool complexity.

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

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

Schema coverage is 100% and schema descriptions are already clear. Description adds key naming conventions but does not significantly enhance parameter meaning beyond schema.

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

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

Explicitly states the action (save) and resource (data to reuse later). Distinguishes from sibling tools by mentioning pairing with recall and forget.

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

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

Provides clear guidance on when to use (discover something worth carrying forward) and mentions alternatives (recall, forget). Also addresses session types.

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. Description adds that it cascades through several lookup endpoints and replaces 2-3 manual lookups, providing useful internal behavior context. 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 well-structured with quotes for example queries and bullet-like sections for supported types. It is somewhat lengthy but each sentence adds value. Could be slightly more concise, but the structure aids readability.

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

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

Despite no output schema, the description fully explains return values for each type, including ticker, CIK, company name for companies and RxCUI, ingredient, brand for drugs. It also covers auto-disambiguation and input formats. The description provides all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with both parameters described. The description adds further meaning by providing examples of acceptable values for the 'value' parameter (e.g., ticker AAPL, CIK, drug names) and explaining what each type returns, which goes beyond the basic 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 resolves a name to an official identifier, with concrete examples like 'ticker for company' and 'RxCUI for drug'. It distinguishes from siblings by stating 'Use FIRST whenever you have a name but need an ID', which differentiates it from entity_profile and compare_entities.

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

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

Explicitly says when to use: 'Use FIRST whenever you have a name but need an ID.' Lists supported types and what each returns. Does not explicitly state when not to use, but the context implies if you already have an ID, you don't need this. Could be slightly improved by mentioning alternatives like entity_profile for already known IDs.

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 it safe (readOnlyHint, idempotentHint, non-destructive). The description adds that it internally calls ai_visibility_check, ranks results, and returns score, confidence, and signal density per entity. This provides useful behavioral context beyond the annotations.

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

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

The description is concise at three sentences, front-loaded with the main action, and every sentence adds value: purpose, process, and example use case. No fluff.

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

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

Given the four parameters are fully described in the schema and the description mentions return fields (score, confidence, signal density), the tool is fairly complete for a comparison tool. Could mention error handling or rate limits, but annotations cover safety. Sibling tools provide additional 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?

Schema coverage is 100% with all parameters described. The description adds overarching context (e.g., 'your brand + N competitors') but does not enhance per-parameter semantics beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check, ranking by score, and surfacing most/least recognized. It distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic), as it's specific to AI visibility for competitive audits.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question. It implicitly suggests using ai_visibility_check for single-entity checks by mentioning probes, but does not explicitly state when not to use this tool or list alternative tools beyond the sibling context.

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

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

Discloses key behaviors beyond annotations: fans out across services, partial failures degrade gracefully, bundlephobia first measurement can take 5-30 seconds. Annotations already indicate read-only, idempotent, non-destructive; description adds valuable 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?

Single paragraph is clear and front-loaded, but could benefit from slight restructuring (e.g., bullet points). Every sentence is informative, no wasted words.

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

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

Despite no output schema, description comprehensively explains return structure (summary block fields, per-advisory detail, links, alternative versions) and handles edge cases like partial failures and timeout behavior.

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

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

Schema coverage is 100%, but description adds useful context: package accepts scoped names, version defaults to latest published. This goes slightly beyond 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?

Description clearly states it is a composite check for npm packages, combining license, advisories, version history, and bundle size analysis. It uniquely distinguishes from sibling tools by its specific function.

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

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

Explicitly tells when to use: when agent asks about safety, popularity, size, or cost of an npm package. Also mentions limitations (NPM only in v1) and fallback for other ecosystems via deps.dev:version directly.

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?

Provides technical details beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. Annotations already mark it as read-only, idempotent, etc., so this adds valuable context without contradiction.

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

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

Three sentences that are front-loaded with purpose and usage. The last sentence includes technical implementation details which could be separate, but overall it's well-structured and not overly verbose.

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

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

Despite no output schema, it describes return value characteristics (passages with offsets and scores). Covers purpose, usage, parameters, behavior, and limitations (200K char cap). Complete for a tool with 3 simple parameters.

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

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

Schema coverage is 100% (baseline 3). Description adds examples for query ('supply-chain risk'), clarifies limit range (1-20, default 5), and mentions output features like character offsets and similarity scores that are not in 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 'Semantic search INSIDE a fetched record,' specifies the verb and resource, and gives concrete examples like SEC 10-K body. It also distinguishes from siblings by mentioning it pairs with ask_pipeworx_grounded and saves context when records are large.

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 when the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded. However, it does not explicitly exclude other sibling tools like deep_research or provide when-not-to-use scenarios.

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

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

Annotations indicate idempotent (safe retry) and not destructive. Description adds constraints: requires OAuth, phone verification, SMS cap (10/day), webhook auto-disable after 10 failures, and that return is subscription id. 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?

Packed with information but well-organized: main purpose, requirements, types, delivery. Some redundancy (e.g., SMS cap mentioned twice) but overall efficient for the complexity.

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

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

Covers prerequisites, return value (subscription id), supported types, delivery options, constraints (phone verification, SMS cap, webhook behavior). No output schema, but description sufficiently explains what to expect.

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

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

Schema coverage is 100%, but description adds extensive context: for 'type' provides examples for each enum, for 'params' gives detailed per-type schema, for 'delivery' explains each channel's requirements (email validation, SMS verification, webhook signing and auto-disable). This far exceeds 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?

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

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

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

States requirement for Pipeworx OAuth account and that anonymous/BYO cannot persist. Implicitly contrasts with recent_alerts (pull) and list_subscriptions. Lacks explicit when-not-to-use vs alternatives like deep_research or validate_claim.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, etc. The description adds useful context that the tool returns 'category-bucketed example questions … drawn from the live catalog of thousands of tools,' which informs behavior (no side effects, dynamic data). 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?

Description is front-loaded with trigger phrases and efficiently explains purpose, usage, and output. Every sentence serves a purpose, though the length is slightly high due to listing multiple categories. Could be trimmed slightly but overall 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?

Despite no output schema, the description fully explains what the tool returns (category-bucketed example questions with exact tool+argument shapes) and how to use it (no args vs. topic). Given the tool's complexity and low parameter count, this is complete and sufficient for effective invocation.

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

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

Schema coverage is 100% (1 optional param 'topic' with description listing allowed values and effect). The description repeats the same information from the schema, adding little new meaning. With high schema coverage, baseline is 3, and no extra value is provided beyond the schema.

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

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

Description clearly states the tool is the onboarding entry point for a connected agent, returning category-bucketed example questions with tool+argument shapes. It distinguishes itself from sibling tools like discover_tools by being the first step. The verb 'suggest' and resource 'questions' are specific and match title and trigger phrases.

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

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

Provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains when to call with no arguments vs. with topic. However, it does not explicitly mention when not to use this tool or compare to similar siblings like discover_tools, which could offer alternative discovery.

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

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

Description adds critical behavioral details beyond annotations: 'row is deactivated (not deleted)' and 'historical events stay available'. Aligns with annotations (idempotentHint, destructiveHint) and provides extra transparency about side effects.

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 action, no fluff. Every sentence adds value without redundancy.

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

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

For a simple tool with one parameter and thorough annotations, the description covers purpose, ownership, and data lifecycle completely. No output schema needed; effect is clear.

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

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

Schema coverage is 100% with clear parameter description. Description does not add new parameter info but implies the id comes from subscribe tool. For a single-id parameter, this is sufficient, earning above baseline.

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

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

Description clearly states the action 'Cancel a subscription by id' and specifies the resource (subscription). It distinguishes from siblings like subscribe and list_subscriptions by its specific verb and id-based targeting.

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

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

Provides clear context: ownership enforced (only own subscriptions) and effect (deactivation not deletion). Implicitly advises against using for others' subscriptions, but does not explicitly list alternatives or when-not-to-use scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: it explains the dual-pipeline approach (SCE EDGAR vs grounded), exact percent-delta math, the return of verbatim evidence with citations, and how it replaces multiple sequential calls. 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 a single dense paragraph that front-loads trigger phrases and is reasonably concise given the complexity. Every sentence adds value, but it could be slightly tightened (e.g., combining examples more efficiently).

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

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

The description fully explains the tool's purpose, operation (two pipelines), output format (verdict, actual value with citation, reasoning), and efficiency gains. Given no output schema, the description adequately describes the return values. It covers all essential contextual 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 repeats the claim parameter description and adds context about tolerance_pct overriding implied wording and default cap at 5, but this adds only marginal value beyond the schema's description.

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

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

The description clearly states the tool performs claim verification using natural-language phrases like 'Is it true that…' and 'fact check'. It specifies the two distinct pipelines (SEC EDGAR for financial claims, grounded for others), distinguishing it from sibling tools by being a specialized one-step verifier.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides examples of claim types and explains the routing logic, but does not explicitly state when not to use it or compare directly with siblings like 'deep_research' or 'ask_pipeworx_grounded'.

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