randomuser

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds valuable context: default model is free, Anthropic requires BYO key with direct billing, and details the return structure (per-model fields and combined view). 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 three sentences, front-loading purpose and defaults, then adding technical details and use cases. Every sentence contributes 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?

The description covers all aspects: what the tool does, how to use it (parameters, defaults, API key), what it returns (per-model scores), and when to use it. No output schema exists, but the return format is described sufficiently. Complete for a probe tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds meaning beyond schema by clarifying the default model, stating when _apiKey is needed, and giving examples for entity and context. It enriches but does not revolutionize the parameter 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 probes one or more LLMs for visibility scores (0-100) for a business/brand/product/topic. It specifies the verb 'probe' and resource 'LLMs for visibility', and distinguishes from siblings by focusing on multi-model visibility scoring.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and provides setup guidance (default model, optional _apiKey for Anthropic). It does not explicitly mention when not to use or differentiate from siblings, but 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 declare readOnly, openWorld, idempotent, non-destructive. Description adds value by explaining the routing mechanism, automatic argument filling, and output format (structured answer with pipeworx:// citation URIs). This goes beyond annotations, though does not detail failure modes or authentication requirements.

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 strongest directive ('PREFER OVER WEB SEARCH'), followed by domain list, mechanism, and usage triggers. Every sentence serves a purpose. Efficiently packed while remaining readable.

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 as a meta-routing interface to thousands of sources, the description covers target use cases, trigger patterns, supported domains, and output format. No output schema exists, but description sufficiently explains expected return structure. Complete for the tool's complexity.

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

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

Schema covers 100% with clear description of 'question' parameter and aliases. Description does not add new semantic meaning beyond the schema; examples are already in schema. Adequate but not enhanced.

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 routes questions to 3,751 tools across 886 sources for authoritative structured data. Differentiates from web search and lists specific domains (SEC filings, FDA, etc.). Distinguishes from siblings like 'deep_research' and 'validate_claim' by positioning as the primary factual query 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?

Explicitly says 'PREFER OVER WEB SEARCH' and provides exhaustive examples of when to use: factual questions about real-world entities, events, numbers. Lists trigger phrases like 'what is', 'look up', 'find'. Provides concrete examples. Does not explicitly exclude any cases, but the breadth of coverage makes this appropriate.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by disclosing that it costs one extra LLM call, that it returns explicit refusals with specific reasons, and that it uses only the tool result. 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 moderately long but well-structured: opening purpose, routing explanation, output format, usage guidance, and cost comparison. Front-loaded with key info. Could be slightly trimmed but every sentence earns its place.

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

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

Given the tool's complexity (routing, extraction, multiple refusal reasons, output shape) and the lack of an output schema, the description completely covers return format, use cases, comparison to sibling, and cost. No gaps for the agent to infer.

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% as all parameters are aliases for the question field, each described in the schema. The description adds little param-specific meaning beyond 'natural language question,' but the structural coverage is sufficient, 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 it is a 'hallucination-resistant answer mode for high-stakes reads' and contrasts with 'ask_pipeworx' for casual lookups. The verb 'extracts' and resource 'the data' are explicit, and the distinction from the sibling tool is unambiguous.

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

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

It explicitly says 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and 'prefer ask_pipeworx for casual lookups,' providing clear when-to-use and when-not-to-use guidance with a named alternative.

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

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

The description extensively covers behavioral traits: low-confidence handling, closed market detection, wide spread warnings, cancellation rules, and resolver contract details. Annotations already declare read-only, idempotent, and open-world; the description adds substantial 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?

The description is lengthy but well-structured with headings and categorized examples. It is concise for the amount of detail it conveys, though some repetition (e.g., low-confidence path explained twice) could be trimmed.

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

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

Given the tool's complexity and lack of output schema, the description is exceptionally complete, covering response shapes, edge cases (low confidence, closed markets, cancellation rules), and important caveats (e.g., resolver contract to inspect before trusting).

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining parameter usage (e.g., depth options, market input formats, include_raw for full payloads) and providing examples, raising the score.

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 a Polymarket bet by pulling Pipeworx data, accepts a slug, URL, or question text, and returns evidence and analysis. It distinguishes from siblings like polymarket_edges by focusing on ad-hoc research rather than pre-computed edges.

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

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

Explicit examples of when to use ('should I bet on X', 'what does the data say', 'is there edge in Z') are given. However, it does not explicitly mention when not to use or contrast with alternatives, though context implies 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 cover safety (readOnly, idempotent, non-destructive). Description adds: data sources, fiscal year handling, sorting behavior, and return format (paired data + citation URIs). No contradiction with annotations.

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

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

Single dense paragraph with no wasted sentences. Front-loaded with example queries and preference over alternatives. Could benefit from slight structuring (e.g., separating company/drug specifics), but remains clear and 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?

Covers input, data sources, sorting, count limits, return format, and edge cases (fiscal year handling). No output schema needed, but description adequately specifies what to expect. Very complete for a comparison 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%. Description enriches parameters by explaining what data is pulled for each type (e.g., revenue, net income for companies; adverse-event counts for drugs) and provides examples for the 'values' parameter.

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

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

Description clearly defines the tool as a side-by-side comparison of 2-5 companies or drugs, referencing specific data sources (SEC EDGAR, FAERS) and sorting by primary metric. Distinguishes from sibling tools like entity_profile and resolve_entity.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries. Specifies allowed entity count (2-5) and types. No ambiguous guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds significant behavioral context: decomposes into sub-questions, parallel routing, verbatim evidence with citations, gaps for unanswered facets, and expected time (15-60s). 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 every sentence adds value. It is front-loaded with the core purpose and then provides details. A slight reduction could improve conciseness, but the density of useful information justifies the length.

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

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

No output schema exists, so the description must explain return values. It does: 'Returns a structured findings packet... verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, and gaps[]'. Combined with annotations and schema, this provides a complete picture for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the enum values for depth ('quick=3, standard=5 (default), thorough=8 (paid plans)') and that the question parameter can be broad/multi-part, aiding parameter selection.

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

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

The description starts with 'Grounded multi-source research in ONE call', clearly defining the verb (research) and resource (multi-source). It distinguishes from ask_pipeworx by specifying use for broad/multi-part questions. The explanation of decomposition and parallel routing adds specificity.

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

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

Explicitly states when to use this tool ('Use for broad or multi-part questions') and when not ('use ask_pipeworx for single lookups — it's one LLM call instead of many'). Also mentions requirements (Pipeworx account, paid plan for 'thorough' depth), providing clear context for 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 declare readOnlyHint=true and destructiveHint=false, consistent with a read-only search. The description adds useful behavioral context: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes that results are 'ready to call directly.' 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 front-loaded with the core purpose and usage guidance. It is somewhat verbose with the list of domains, but each element adds value. A slightly more structured format (e.g., bullet points) could improve readability, but it is still effective.

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 lack of an output schema, the description thoroughly explains what is returned (tool names, descriptions, schemas with examples) and how to use the results (ready to call directly). It covers purpose, when to use, parameter details, and expected output, making it complete for a tool-discovery tool.

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

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

Schema coverage is 100%, and the description adds significant value: it lists aliases for the query parameter, provides concrete examples ('analyze housing market trends', 'look up FDA drug approvals'), and clarifies the limit parameter. This goes beyond the schema by offering usage patterns.

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

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

The description clearly states the purpose: 'Find tools by describing the data or task.' It includes a specific verb ('find') and resource ('tools'), and distinguishes from sibling tools by positioning itself as a meta-tool for discovery. The list of domains further clarifies the scope.

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

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

The description explicitly advises: 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear when-to-use guidance. It does not explicitly state when not to use, but the 'FIRST' implies it is the entry point, effectively excluding other tools for initial 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?

Annotations already show readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by mentioning USPTO API sunset and soft-fail behavior, and details the return fields, going 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 paragraph but packs a lot of information efficiently. Starts with example queries, then preference, sources, returns, and input notes. Slightly long but well-organized.

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

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

No output schema, so description must explain return values. It thoroughly describes all components: CIK, filings, fundamentals, patents, news, LEI. Also handles edge case (patents soft-fail). Complete for a complex tool.

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

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

Schema coverage is 100% with descriptions. Description adds examples, clarifies type must be 'company', and explains value can be ticker or CIK (not names), providing 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?

The description clearly states the tool creates a 'full cross-source profile of a US public company' using specific verbs like 'profile', 'research', 'brief me on'. It distinguishes from siblings by explicitly preferring over chaining single-pack lookups.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and notes 'names not supported (use resolve_entity first if you only have a name)'. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds that it deletes memory by key, but does not elaborate on permanence or side effects. With annotations, this is minimally adequate.

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

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

Two sentences: first states purpose, second gives usage guidance and references siblings. No wasted words, front-loaded with the core action.

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 no output schema, the description fully covers purpose, when to use, and how it relates to sibling tools. Annotations cover safety. It is 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?

Schema coverage is 100% and the schema description for 'key' is clear ('Memory key to delete'). The tool description does not add extra parameter details beyond the schema, so 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 action (delete) and resource (previously stored memory by key). It distinguishes from siblings by mentioning pairing with remember and recall.

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

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

Explicit when-to-use scenarios are provided: stale context, task done, clear sensitive data. Also mentions pairing with siblings. No explicit when-not-to-use, but the positive guidance is 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 indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructiveHint. The description adds context about randomness and the specific fields returned, enhancing transparency beyond annotations.

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

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

Two sentences with no fluff. First sentence covers action and input, second covers output and optional parameter. Every word earns its place.

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

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

Given the presence of a complete output schema and thorough annotations, the description provides sufficient context for a simple generation tool. It covers input, output, and optional count without 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?

With 100% schema description coverage, the schema already documents both parameters. The description restates gender filtering and count specification, adding marginal context about randomness but not significant new semantics.

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

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

The description clearly states the tool generates random user profiles filtered by gender. It lists the returned data types (names, contact info, photos, demographics) and distinguishes from the sibling 'generate_users' which likely lacks gender filtering.

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

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

The description implies use when gender-specific profiles are needed, but does not explicitly state when to prefer this over 'generate_users' or other siblings. No when-not or alternative guidance is provided.

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, covering safety and idempotency. The description adds the process: fetches page, extracts title/description/key links, emits standard format. This adds some behavioral context but does not significantly exceed annotation coverage.

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

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

The description is two sentences: the first states purpose and format, the second lists use cases. It is front-loaded and efficient, with no filler. Minor reduction for not being as compact as possible, but still good.

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

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

Given no output schema, the description explains the output is a single text blob at site-root/llms.txt. It also covers the extraction process. For a simple tool with good annotations, this is adequately complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions 'Full URL' and 'Maximum number of link entries' but does not add meaningful semantics beyond what the schema already provides.

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

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

The description clearly states the verb 'Generate' and the resource 'llms.txt file for any URL'. It specifies the output format and purpose, distinguishing it from siblings like 'ai_visibility_check' or 'scan_competitor_ai_presence' which are for different tasks.

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

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

The description explicitly lists three use cases: indexing a client's site, drafting for own project, and auditing competitors. While it doesn't provide when-not-to-use or alternatives, the use cases are concrete and helpful.

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 the tool is read-only, open-world, and idempotent. The description adds the behavioral detail of generating random profiles, but does not disclose anything beyond what annotations imply.

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

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

The description is a single, well-structured sentence that front-loads the core action ('Generate random user profiles') and efficiently conveys all necessary information without waste.

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

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

Given the simplicity of the tool, the presence of an output schema, and complete annotations, the description fully covers what the agent needs to know for tool 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 coverage is 100% with clear descriptions for both parameters. The description reinforces the purpose of count and nationality with examples, adding minimal new meaning beyond the schema.

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

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

The description clearly states the tool generates random user profiles with specific attributes (names, addresses, emails, photos) and distinguishes it from sibling tools like generate_by_gender by focusing on nationality filtering and count.

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 generate random user data with optional nationality and count) but does not explicitly state when not to use it or mention alternatives among 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 value by specifying the returned fields and optional include_inactive parameter, but doesn't contradict annotations.

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

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

Two sentences, each serving a distinct purpose: first states what it does and returns, second provides usage guidance. No wasted words.

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

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

For a simple list tool with one optional parameter and no output schema, the description sufficiently covers return fields, usage context, and parameter implication. It is complete for the tool's complexity.

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

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

Schema coverage is 100% with a clear description for the only parameter. The tool description doesn't add new parameter semantics but implies default behavior (active only) which aligns with the schema's default false.

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 'List the caller's active subscriptions' with a specific verb and resource, and lists return fields. It distinguishes itself from siblings like subscribe, unsubscribe, and others by focusing on listing.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel' providing clear when-to-use context and pointing to alternatives (add/cancel via sibling tools).

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

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

Discloses rate limit (5 per identifier per day) and that it's free and doesn't count against tool-call quota. Annotations are all false, so description carries full burden and does so effectively. 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?

Concise yet comprehensive: one paragraph covering purpose, usage, exclusions, rate limits, and quota info. Every sentence adds value. 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?

For a simple feedback tool with 3 parameters, the description fully covers what each parameter means and how to use them. No output schema, but return values are likely straightforward; no additional information needed.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds context: explains enum values further, guides use of context object, and advises to 'Describe the issue in terms of Pipeworx tools/packs.' Adds marginal value beyond schema.

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

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

Clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' Explicitly lists feedback types (bug, feature, data_gap, praise) and distinguishes from sibling tools which are for other purposes.

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

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

Provides explicit when-to-use scenarios: broken/stale data (bug), missing tool (feature/data_gap), positive experience (praise). Also gives guidance on what not to do: 'don't paste the end-user's prompt.' Clearly differentiates from other tools.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds that data comes from CF analytics engine, no PII, and caching is 5min-1h, providing valuable behavioral context.

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

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

Description is concise with front-loaded purpose, numbered use cases, and no redundant sentences. Every sentence earns its place.

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

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

Given the simple tool with one optional param, strong annotations, and no output schema, the description fully covers purpose, usage, behavior, and data source.

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

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

Schema coverage is 100% and already describes the window parameter including its effect. The description does not add new meaning beyond the schema, meeting the baseline.

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

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

The description clearly states it returns top tools, packs, and call volume over a window. It differentiates from siblings like ask_pipeworx and 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?

Three specific use cases are listed (discovering hot data, confirming popular tool, aligning use case). No explicit exclusion or alternative, but context is clear.

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

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

The description adds substantial behavioral context beyond annotations: fill check against live CLOB depth, semantic anchor (Jaccard similarity), partition filter for placeholder slugs, and error conditions. 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 lengthy but well-structured with sections, examples, and no redundancy. Every sentence provides value given the tool's complexity.

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

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

Despite no output schema, the description thoroughly explains the response structure (opportunities array, partition_check, fill check). Covers inputs, modes, edge cases, and limitations completely.

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 tool description adds examples, mode explanations, and deeper meaning for both parameters, exceeding baseline.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies two modes (event and topic) with distinct use cases, distinguishing it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It warns that calling with no arguments fails, 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 readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral context: model families, edge calculations, slippage assumptions, knob effects, caching, and diagnostics. 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 lengthy but packed with necessary details for a complex tool. Front-loaded with purpose and segments. Could be slightly more concise, but every sentence adds value. Well-structured with clear sections.

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?

Comprehensively covers output structure (by_segment, diagnostics), edge fields, caching, and Fed bet exclusion. No output schema, but description compensates fully. All aspects of tool behavior are explained.

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 deep semantics for each parameter: e.g., explains min_liquidity as tradeable-edge filter, slippage_pp as execution cost, and how min_partition_leg_kelly applies to per-leg Kelly. Provides operational context 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 it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with specific segments. It distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx-based edge.

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 built for 'what should I bet on today' and describes when to use. Provides context for Fed bets exclusion but does not explicitly contrast with sibling tools like polymarket_arbitrage or bet_research.

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, and non-destructive behavior. The description adds significant behavioral context: data source (daily snapshots), gap handling, decay computation method (not intraday), history depth, and response structure. 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 densely informative yet well-structured: purpose, example, args, response fields, limitations. Every sentence adds value, and key information is front-loaded.

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

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

Despite no output schema, the description thoroughly explains the return structure (tracked[], expired[], snapshot_dates[]) with field details and caveats. Covers limits and edge cases (gaps, TTL) for a complete picture.

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

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

Schema description coverage is 100% (both params described). The description adds default values (14 days, '1wk') and clarifies that 'window' refers to snapshot family, but does not add extensive new meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots. Answers "how long has this edge existed and is it shrinking?"' It distinguishes from siblings like polymarket_edges (snapshot source) by focusing on historical tracking.

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 usage context through an example comparing fresh wide edges to 3-week-old edges, implying when to use this tool. It explains limits (60-day TTL, decay from daily closes) but does not explicitly name alternative tools for contrast.

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, open-world, non-destructive, and the description adds rich behavioral details (walks ladder, returns verdict, explains forced_directional_risk, etc.) without contradicting any annotations.

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

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

The description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and each sentence adds information. However, it is somewhat verbose and could be tightened without losing clarity, especially given the length.

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

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

Given the complexity (two modes, 4 parameters, no output schema), the description fully covers input behavior, output fields for both modes, and edge cases (thin_legs, forced_directional_risk). It is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, but the description adds significant value beyond schema by explaining how size_usd is interpreted differently across modes (max spend vs proceeds vs settlement notional) and how side defaults in basket mode. This elevates it above the baseline of 3.

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

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

The description clearly states it's a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishes between single-market and basket modes, and specifies which sibling tools (polymarket_arbitrage, polymarket_edges) it should be used with.

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' and warns about partial basket fills converting arb to directional. Provides clear when-to-use and when-not-to-use guidance.

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

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

The description adds significant detail beyond annotations: it explains compatibility_warning conditions (non-equivalent bet shapes, no token overlap), temporal alignment checks, and skipped cross-type/subtype counters. It fully discloses that many queries yield no tradeable spreads, complementing the readOnlyHint and idempotentHint annotations without contradiction.

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

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

The description is fairly long but every sentence carries necessary information covering modes, response details, and warnings. It is front-loaded with the core purpose and structured logically from concept to modes to response to cautions. Minor verbosity is justified by the tool's complexity.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure including leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It covers all major edge cases and provides a realistic expectation of results, making the tool fully understandable without external documentation.

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 enriches each parameter with practical examples and context: it explains the topic shortcuts with a full list, and gives explicit ticker/slug format examples. This adds meaning beyond the schema's minimal descriptions.

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

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

The description explicitly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by specifying 'cross-venue' and highlighting its unique mode options and safety fields.

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

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

The description provides strong context on when spreads are meaningful vs. when compatibility warnings arise, and warns that most pre-mapped topics return warnings. It implicitly differentiates from alternative approaches, though it could explicitly name sibling tools for comparison.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Adds context about scoping (anonymous IP, BYO key hash, account ID) and behavior when key omitted (lists all). 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 main action, followed by usage guidance, scoping, and pairing. Every sentence adds unique 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 read tool with one optional parameter, description covers purpose, usage, scoping, and pairing. Lacks detail about error handling (e.g., key not found) but overall sufficient.

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

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

Schema has 100% coverage with description for 'key'. Description adds clarification that omitting key lists all saved keys, which is not in schema. Provides examples in schema but description reinforces.

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

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

Description uses specific verbs 'retrieve', 'list all saved keys', and identifies resource 'value previously saved via remember'. Clearly distinguishes from siblings 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?

States when to use (look up context stored earlier) and provides concrete examples (ticker, address, notes). Implicitly excludes storage or deletion tasks, but no explicit 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 indicate read-only, open-world, idempotent, and non-destructive. The description adds the side effect of mark_read flagging events as read, and describes 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 concise, front-loaded with purpose, and each sentence adds necessary detail without redundancy.

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

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

Given no output schema, the description covers return fields, parameter usage, polling behavior, and alternative access. It is complete for the tool's complexity.

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

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

All 5 parameters have schema descriptions (100% coverage). The description adds value with examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explains the effect of mark_read, going beyond the schema.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying the verb 'pull' and resource. It distinguishes from siblings like 'list_subscriptions' by focusing on reading alerts.

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

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

The description gives context on polling and mentions an alternative endpoint for scripts/dashboards. It explains filtering and mark_read behavior, but does not explicitly contrast with siblings like 'recent_changes'.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details fan-out to multiple sources, fallback behavior (GDELT→GNews when rate-limited or 5xx), soft-fail for USPTO due to API sunset, and return structure (changes[] grouped by source, total_changes count, citation URIs). No contradiction with annotations.

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

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

The description is well-structured, front-loaded with example queries, and each sentence adds distinct information. Slightly lengthy but justified given the multi-source complexity. Could be trimmed slightly but still effective.

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

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

Given no output schema, the description explains return structure. With 3 required parameters and complex multi-source behavior (fan-out, fallback, soft-fail), the description covers all necessary context for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% (all 3 parameters described). The description adds value: clarifies type is only 'company', explains since format (ISO date or relative shorthand with examples like '7d', '30d', '3m', '1y'), and recommends typical value ('30d' or '1m'). Also clarifies value can be ticker or CIK.

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

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

The description clearly defines the tool as a change feed for a company over a time window, citing specific sources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishing it from the sibling tool entity_profile. The verb 'fans out' and resource 'change feed' are specific.

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

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

Explicitly states when to use this tool versus entity_profile: 'Use entity_profile instead when you want the static profile... regardless of window.' Also provides example queries and recommends typical monitoring window ('30d' or '1m').

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

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

Discloses scoping (by agent identifier), persistence differences (authenticated vs anonymous), and retention (24 hours for anonymous). Annotations indicate idempotentHint=true and destructiveHint=false, but description adds 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?

Front-loaded with core purpose in first sentence. Every sentence adds essential information: usage guidance, behavior, pairing. No redundant or extraneous text. 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?

For a simple tool with 2 parameters and no output schema, the description fully covers purpose, behavior, usage, and relationship to siblings. Nothing missing 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?

Input schema covers both parameters with descriptions (100% coverage). The description adds value with examples of valid key-value pairs (e.g., 'subject_property', 'target_ticker'), aiding semantic understanding slightly 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 'Save data the agent will need to reuse later' with specific verb+resource (save memory key-value pairs). It distinguishes from siblings like recall and forget by mentioning them as complementary tools.

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

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

Provides explicit when-to-use guidance: 'when you discover something worth carrying forward' with concrete examples (ticker, address, preference). Also mentions alternatives: 'Pair with recall to retrieve later, forget to delete.'

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 true, and destructiveHint false. The description adds behavioral context by stating each call cascades through multiple endpoints and replaces 2-3 manual lookups, which goes 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?

The description is relatively long but well-structured and front-loaded with examples and key guidance. Every sentence provides useful information, though minor trimming could be possible without losing value.

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

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

Despite lacking an output schema, the description comprehensively details the return values for each entity type (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation for drug). This provides complete contextual information for the agent to interpret the tool's results.

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

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

All parameters are documented in the schema (100% coverage). The description enhances meaning by explaining what kinds of values are accepted for 'value' per entity type (e.g., ticker, CIK, name for company; brand or generic for drug), and clarifies that 'type' enum is restricted to 'company' or 'drug'.

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

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

The description uses specific verbs like 'resolve' and 'look up', clearly stating it converts a name to a canonical identifier. It also distinguishes supported types (company, drug) and gives examples of queries, making it distinct from sibling tools.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It also details each supported type and what each returns, enabling the agent to decide when to invoke this tool over 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 safe, read-only, idempotent behavior. Description adds the probing mechanism, return format (score, confidence, signal density), which is useful 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?

Three sentences: purpose, mechanism, use case and output. Front-loaded with action, 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 4 parameters, no output schema, and rich annotations, the description fully explains input semantics and output structure (ranked list with metrics). No 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%, but description adds meaning: entities are brand/business names, first is subject; context disambiguates; models list supported values and API key need. This enhances 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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking by score. It differentiates from sibling tools like ai_visibility_check (single probe) and compare_entities (generic comparison).

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

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

Explicitly mentions use case for competitive AI-marketing audits and gives a concrete question. Implies not for single entity (use ai_visibility_check), but does not explicitly differentiate from compare_entities.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses important behaviors: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list timeouts. It also details the return format (summary block, per-advisory detail, links, recent alternatives). 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 and front-loaded with the core purpose. Every sentence adds useful information, covering use cases, return values, limitations, and performance caveats. It is efficient without being verbose.

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

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

Given the tool's complexity (composite check, multiple data sources, partial failures), the description is thorough. It explains what is returned, how failures are handled, and the ecosystem scope. Since there is no output schema, the description adequately covers return values and behavior.

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

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

The input schema already provides descriptions for both parameters (package and version), achieving 100% coverage. The description adds value by clarifying that scoped packages are accepted and that version defaults to latest when omitted. This is additive but not extensive, so a 4 is appropriate.

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

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

The description clearly states it is a composite check for npm packages, using deps.dev and bundlephobia. It specifies the verb 'scan' and the resource 'dependency', and distinguishes itself from sibling tools by limiting to the npm ecosystem.

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

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

The description explicitly tells when to use the tool: whenever an agent asks about safety, popularity, size, or cost of npm packages. It also provides a clear exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This guides the agent to alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds valuable behavioral details: embeddings model (BGE-base-en), overlapping windows (500-char), character limit (200K chars with truncation), and output format (passages with offsets and similarity scores). 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?

Every sentence adds value; front-loaded with core purpose, then technical details. 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?

Despite no output schema, description fully explains return format and technical details, making it complete for agent understanding.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaningful examples for query parameter and clarifies text max size and limit defaults 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 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article) and distinguishes from alternatives by explaining it saves context and returns only relevant passages.

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 the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded. Also mentions truncation limit and flagging.

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

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

Annotations indicate idempotentHint: true, but the description does not clarify whether duplicate subscriptions are allowed or treated as no-ops. However, it does disclose important behaviors: account requirement, rate limit (10/day for sms), webhook signing secret returned once, and auto-disable after 10 consecutive failures. 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 relatively long but well-organized, starting with purpose and return value, then listing types, then delivery channels. Every sentence adds value, though it could be slightly more structured (e.g., bullet points) for easier parsing. It avoids redundancy with the schema.

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

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

For a tool with 3 parameters, no output schema, and moderate complexity, the description covers all necessary aspects: return (subscription id), preconditions (OAuth account), type-specific behaviors, delivery options with constraints (SMS cap, webhook retries). It is complete enough for an agent to use correctly.

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

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

The input schema has 100% coverage, but the description adds significant meaning: it provides concrete examples for each subscription type and its params, explains the 'delivery' object deeply (email validation, SMS verification requirement, webhook HMAC signing). This goes well beyond the schema's basic descriptions.

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

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

The description clearly states the tool's action: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb ('Create') and resource ('subscription'), and differentiates from siblings like list_subscriptions and unsubscribe by its creation purpose.

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

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

The description includes explicit usage context: requires a Pipeworx OAuth account, lists supported subscription types with examples, and details delivery channels. It does not explicitly state when to avoid using this tool or compare it with alternatives, but the context is clear enough for an agent to understand the domain.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context: returns examples drawn from a live catalog, and explains the behavior difference between no argument and topic argument. No contradictions. Slightly less than 5 because it doesn't mention any potential performance or data freshness caveats.

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: begins with typical user queries, then states the purpose, then usage guidelines. It is front-loaded with key information. Slight room for trimming but excellent overall.

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 adequately explains the return format: category-bucketed example questions with tool+argument shapes. It covers the one parameter and its optionality. Sufficient for an agent to understand what to expect and how to 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 coverage is 100% with a single optional parameter. The description adds significant meaning: explains that omitting topic gives full spread, and passing topic focuses on a specific area. It also enumerates the valid topic values beyond the schema description.

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

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

The description clearly states the tool's purpose: returning category-bucketed example questions for onboarding. It lists specific categories and mentions that each question comes with tool+argument shapes. The title 'What Can I Ask Pipeworx?' aligns well. It distinguishes from siblings like ask_pipeworx or discover_tools by focusing on onboarding and example generation.

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

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

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 use no arguments vs passing a topic. This clearly differentiates usage from other tools.

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

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

Annotations already indicate idempotentHint and destructiveHint. The description expands by explaining ownership enforcement, deactivation semantics, and the persistence of historical events, which adds significant behavioral context.

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

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

Two sentences with no redundancy. Core action stated first, then key constraints and side effects. Any additional detail would be unnecessary given tool simplicity.

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 one-parameter tool with no output schema, the description fully covers purpose, constraints, and side effects. It references related tools (recent_alerts) for context. 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% and the description does not add meaning beyond what the schema already provides for the single parameter. Per guidelines, baseline 3 is appropriate.

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

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

The description clearly states the tool's action ('Cancel a subscription by id'), identifies the resource (subscription), and differentiates from siblings like 'subscribe' and 'list_subscriptions' by noting ownership enforcement and deactivation behavior.

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 context on when to use (you must own the subscription) and what happens (deactivation, not deletion), implicitly guiding usage. It also references 'recent_alerts' for historical data. However, no explicit alternatives or when-not-to-use guidance is given.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds behavioral details beyond these: it returns a verdict, extracted structured form, actual value with citation, and percent delta. It also mentions the v1 limitation to company-financial claims. No contradiction with annotations.

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

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

The description is concise yet comprehensive. It starts with concrete examples, then states the use case, followed by scope and output details. Every sentence adds meaningful information without redundancy.

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

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

For a tool with one parameter and no output schema, the description fully covers the purpose, usage, behavioral traits, and return information. It explains what the tool does, when to use it, what it returns, and its limitations. 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?

The input schema has 100% description coverage for the single 'claim' parameter. The description reinforces the meaning with examples and clarifies the expected format (natural-language factual claim). This adds value beyond the schema's brief description.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific examples and delimits the scope (company-financial claims for public US companies). This distinguishes it from sibling tools like 'deep_research' or 'entity_profile', which are more general.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes that the tool replaces 4–6 sequential calls, implying efficiency. While it does not explicitly state when not to use, the scope 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.