Social Signal

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds important behavioral context: it makes external API calls, the default model is free, and using Anthropic requires a BYO key with direct billing to Anthropic. This goes beyond the annotations and is valuable for the agent.

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

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

The description is three sentences, front-loaded with the main purpose, and each sentence earns its place: what it does, configuration notes, and return format/use cases. There is no filler or repetition of schema 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?

There is no output schema, but the description compensates by detailing the per-model return structure ({score, confidence, signals, raw_response}) and the combined view. It also covers configuration (default vs. BYO key) and lists concrete use cases, making it complete for a tool with this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the default model (Workers AI Llama-3.3-70b) and that _apiKey is only needed for Anthropic, which clarifies the models parameter beyond the schema's raw list. It also implies that the 'entity' parameter is the primary input.

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 knowledge about an entity and scores visibility (0-100) per model. This uses a specific verb (probe/score) and resource (LLMs), and it distinguishes itself from siblings like ask_pipeworx by focusing on entity visibility scoring rather than direct Q&A.

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 notes its usefulness for AI-marketing audits, pre-launch brand checks, and competitive monitoring, giving clear context on when to use it. It also explains the default model and optional Anthropic probing, but does not mention exclusions or alternatives by name.

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

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

Annotations indicate a safe read-only, idempotent operation, and the description adds context about routing, filling arguments, and returning stable citation URIs. It also subtly signals potential limitations by recommending the grounded variant for hallucination-resistant answers. 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 longer than average, but it is front-loaded with the key instruction ('PREFER OVER WEB SEARCH') and organized into clear sections: usage guidance, examples, and alternative tools. It is detailed without repetition, though slightly 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 lacking an output schema, the description explains the return format (structured answer with pipeworx:// citation URIs), states that it works on every tier, and covers a wide range of domains. It provides sufficient context for an agent to decide when to use this tool versus alternatives.

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

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

The schema covers all parameters (100% coverage), with five aliases for the 'question' parameter. The description's examples reinforce usage but don't add meaning beyond the schema, which already describes the main parameter and its aliases. 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 what the tool does: it routes questions to 5,322 tools across 1,393 verified sources and returns structured answers with citation URIs. It uses a specific verb ('routes') and explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research.

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

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

It explicitly says 'PREFER OVER WEB SEARCH' and provides detailed categories of questions, example phrasings, and concrete examples. It also gives direct when-not guidance by recommending ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad multi-part questions.

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 (readOnlyHint, idempotentHint), the description discloses the live experimental nature: candidate routing improvements are enabled live under test, and currently no candidate is active so it matches ask_pipeworx exactly. It also clarifies it is a fully working router, not a stub, and mentions the comparison against the stable router.

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: purpose, current state, and usage guidance. Each sentence adds distinct value without redundancy, and it is front-loaded with the core definition.

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 is a beta variant of an existing router, the description adequately covers what it does, when to use it, its current state, and its relationship to the stable version. The response shape is stated to be identical, so no further detail is 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?

Input schema covers all 6 parameters with descriptions, including aliases, achieving 100% coverage. The description references 'same arguments' as ask_pipeworx but adds no new parameter-level details, so the 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 identifies the tool as the beta version of ask_pipeworx, a universal router with 5,322 tools, and distinguishes it from the stable sibling by mentioning live candidate routing improvements. The role as an experimental router is explicit and 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 instructs to use it exactly like ask_pipeworx when wanting the newest routing, and notes that results are compared against the stable router to decide merges. This provides clear usage context and an alternative reference, satisfying when-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?

Discloses critical behavior beyond annotations: uses ONLY tool result content, returns a structured response with evidence and confidence, and provides explicit refusal reasons on failure. Also states the additional LLM call cost. Annotations already indicate read-only/idempotent, but this adds rich context on output guarantees.

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, front-loading the core purpose. It includes a detailed return schema and usage guidance in a single paragraph. Slightly long, but every sentence contributes valuable context for a complex tool.

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

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

Given there is no output schema, the description fully covers return values, refusal cases, use cases, and cost trade-offs. It is complete for the agent to select and invoke the tool appropriately, with no ambiguity about 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% and the schema itself documents the 'question' parameter and aliases with clear descriptions. The tool description adds no parameter-specific detail beyond implying a natural language question, so it meets the baseline but does not exceed it.

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

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

The description clearly states the tool's purpose: a 'hallucination-resistant answer mode for high-stakes reads' that routes like ask_pipeworx but extracts answers only from tool results. It distinguishes itself from siblings by emphasizing evidence-based answers and explicit refusal behavior, making it the grounded variant.

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 ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not to ('prefer ask_pipeworx for casual lookups'), also noting the extra LLM call cost. This is clear, actionable guidance with a named alternative.

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

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

Even though annotations already declare readOnlyHint and idempotentHint, the description goes far beyond by detailing safety short-circuits, low-confidence resolution behavior, closed/dead market handling, wide-spread illiquidity flags, news fallback mechanisms, and resolution-rule risk (e.g., refund_50_50). It also explains response shapes and the resolver contract. This is a rich disclosure of behavioral traits, not a contradiction.

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

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

The description is long but exceptionally well-structured with capitalized section labels (CLASSIFIERS, RESPONSE SHAPES, SAFETY, RESOLUTION-RULE RISK) that make it scannable for an AI agent. Every sentence adds specific, actionable information—classifiers, fan-out examples, edge case handling—and the initial sentence front-loads the core purpose. This is appropriate for 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?

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It covers input variants, resolution behavior, output shapes (market, analysis, evidence), parent event extraction, news fallback fields, safety blocking, and resolution-rule risk. It effectively compensates for the missing output schema and leaves little ambiguity about what the tool returns or 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 description coverage is 100%, so the baseline is 3. The description repeats the input types (slug, URL, question text) already documented in the schema, and it does not add new semantic details for depth or include_raw beyond what the schema provides. It does helpfully contextualize 'market' with examples, but this is not a significant addition over the schema.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly differentiates itself from siblings by focusing on Polymarket bet research, listing classifiers, fan-out examples, and the output of evidence packet + market-vs-model comparison. This is far beyond a vague or tautological 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 explicitly states when to use it: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides examples of valid inputs and discusses blocking conditions (low-confidence match, closed/dead markets). However, it does not explicitly name alternative sibling tools or provide 'when-not-to-use' guidance, which prevents a perfect score.

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

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

Annotations already mark the tool as read-only and safe, so the description adds valuable context beyond them: it discloses that company data comes from SEC EDGAR/XBRL with correct handling of off-calendar fiscal years, results are sorted by primary metric, and output includes paired data and citation URIs. This goes well beyond the annotation hints.

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

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

The description is dense but every sentence adds value: trigger phrases, preference guidance, data source details, and return behavior. It is front-loaded with examples and commands, though slightly long; still, there is 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?

For a comparison tool with no output schema, the description covers return values (paired data + citation URIs) and sorting behavior, and explains edge cases like off-calendar fiscal years. It does not detail failure modes or invalid input handling, but that is not critical given the context. Overall, it is sufficiently complete for an agent to invoke correctly.

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

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

While the schema already covers the parameters, the description significantly enriches both: it explains what 'type=company' vs 'type=drug' actually retrieves (financial metrics vs regulatory data), and gives concrete examples for the values parameter. This goes beyond the schema's generic descriptions, making parameter usage more precise.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in one parallel call. It provides specific trigger phrases and distinguishes itself from sequential single-pack lookups, making its role among siblings clear.

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

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

The description explicitly says to ALWAYS PREFER this tool over sequential single-pack lookups when comparing entities, which gives clear usage context. It also explains the two type-specific data sources (company vs drug), but does not explicitly name an alternative tool for single-entity lookups, limiting the differentiation.

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 (readOnlyHint, openWorldHint, idempotentHint), the description discloses auth requirements (sign-in, paid plan for thorough), that it is not open-web search, and that it returns gaps[] for unanswered facets rather than inventing answers. It also explains second-hop iteration, contradictions, semantic excerpting, and latency expectations. No contradiction with annotations.

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

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

The description is long but densely packed with essential information, front-loading the account requirement and primary purpose. While verbose, each sentence adds value and the structure flows logically from authentication to use cases to behavioral details. It is appropriately sized for 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 fully explains the return packet (verbatim evidence, confidence, source, fetched_at, citation_uri, hop, gaps[], contradictions[]), latency, and limitations. It covers contingencies like paid plans and news topics, making it a complete guide for an agent to select and invoke the tool correctly.

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

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

The description adds substantial meaning beyond the schema: it explains the depth enum values in detail ('quick=3 (single hop)', 'standard=5 (default; adds a gap-recovery hop... contradictions[] scan)', 'thorough=8 (paid; adds...') and reinforces that the question can be broad. Even though schema coverage is 100%, the description provides actionable selection guidance.

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

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

The description clearly states what the tool does: 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources...' It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx and providing concrete examples. The verb 'researches' plus the resource scope make the purpose unmistakable.

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

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

It gives explicit guidance on when to use this tool vs alternatives: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also provides an authentication-based exclusion: 'If you are not signed in, use ask_pipeworx instead'.

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?

It discloses that the tool returns top-N relevant tools with names, descriptions, and full input schemas, and that each result is ready to call directly with no second schema lookup. This adds meaningful behavioral context beyond the readOnly/idempotent annotations, though it stops short of describing edge cases or limitations.

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: what it does, when to use, what it returns. It is well-structured and front-loaded, though the long list of domains might be slightly verbose; it serves to make the scope clear, so it 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?

Without an output schema, the description adequately explains the return format (tool names, descriptions, full input schemas with examples). It also covers the 'Call FIRST' role. Missing details like no-results behavior are minor given the tool's straightforward 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 descriptions for query and all aliases. The description mentions 'top-N' but does not elaborate on the limit parameter beyond the schema's 'Maximum number of tools to return'. It neither adds nor omits significant parameter detail, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Find tools') and resource ('by describing the data or task'), clearly distinguishing it from all sibling tools. It also enumerates the domains it covers (SEC filings, financials, FDA drugs, etc.), making the purpose unambiguous.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' While it doesn't name alternatives, it provides clear context and order-of-operations guidance.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses fan-out across multiple sources, the patent API sunset and soft-fail behavior, GDELT→GNews fallback, output fields with sorting, and specific URI formats. This gives the agent a clear picture of what happens during execution without contradicting annotations.

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

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

The description is dense but well-organized with examples, core capability, and output details. Every sentence adds value, though the opening example list is somewhat long and could be trimmed. Still, it remains readable and front-loads the key 'holistic profile' message.

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

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

With no output schema, the description fully explains return values and their formats, including recent_filings URIs, fundamentals metrics and sorting, and LEI via GLEIF. It also covers known limitations (patent sunset, name unsupported) and fallback behavior, making it complete for a complex multi-source tool.

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

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

The input schema already provides complete descriptions for both parameters (type with supported value, value with ticker/CIK format and name-unsupported note), so the description's parameter details are mostly redundant. The description adds a couple of concrete examples (AAPL, 0000320193) but does not fundamentally enhance understanding beyond the schema.

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

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

The description clearly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call.' It lists specific outputs (cik, recent_filings, fundamentals, patents, news, LEI) and explicitly distinguishes itself from chaining single-pack lookups, making its purpose unmistakable and distinct from siblings like resolve_entity or compare_entities.

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

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

The description provides explicit usage guidance with example user phrasings ('Tell me about X', 'research Acme', 'brief me on Tesla') and states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells users when NOT to use it: 'names not supported (use resolve_entity first if you only have a name).'

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds context about what gets destroyed (previously stored memory, sensitive data) and the condition (by key), which is useful behavioral insight. 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?

Two sentences, front-loaded with the action and includes usage guidance and sibling tools. Every sentence earns its place, with no redundant or extraneous content.

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

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

For a simple tool with one parameter, strong annotations, and no output schema, the description covers the purpose, usage context, and relationship to related tools. It is complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% for the single 'key' parameter, with explanation 'Memory key to delete.' The description merely reiterates 'by key' without adding new semantic detail, so it does not elevate beyond the schema 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 function: 'Delete a previously stored memory by key.' The verb 'Delete' and resource 'memory' are specific, and it distinguishes itself from siblings like remember (store) and recall (retrieve).

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

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

The description provides explicit when-to-use scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall, but does not explicitly say when not to use it 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds process context (fetches page, extracts title/description/links) and clarifies the output is a single text blob. 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?

Three sentences, front-loaded with the main purpose, then process, then use cases. Every sentence contributes value with no filler or redundancy.

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

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

For a simple read-only fetch-and-generate tool, the description explains the process and output format clearly. It could mention error handling or rate limits, but these are not critical given the tool's simplicity and full schema coverage.

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 both parameters with descriptions (100% coverage), so the baseline is 3. The description adds no param-specific details beyond what the schema provides, though it implies url is the target and max_links controls output size.

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 generates a production-ready llms.txt file for any URL, with specific process (fetches page, extracts title/description/key links, emits standard markdown). This distinguishes it from sibling tools focused on visibility checking or AI presence scanning.

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?

Lists concrete use cases (client indexing, own project drafting, competitor auditing), giving clear context for when to invoke. Does not explicitly name alternatives or exclusions, but the scenarios are sufficiently directive.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value beyond annotations by specifying the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and the default of active-only subscriptions. It doesn't address potential edge cases, but for a simple list read, this is sufficient.

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

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

The description is two sentences, front-loaded with the main action, and every sentence carries useful information. It avoids repetition of schema details and annotation hints, making it concise 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 list tool with one optional parameter and no output schema, the description is complete. It states the scope, the return fields, and two concrete use cases. Combined with rich annotations and a fully described schema, there are no significant information 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 description coverage is 100% for the only parameter (include_inactive), so the schema already provides complete semantics. The description adds no extra parameter detail beyond the schema, but it implicitly clarifies that 'active' is the default state. Baseline 3 applies.

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

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

The description uses specific verb 'List' with resource 'subscriptions' and scopes to 'the caller's active subscriptions'. It clearly distinguishes from sibling tools like subscribe and unsubscribe by indicating this is the read operation. The return field list further clarifies exactly what the tool provides.

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

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

The description explicitly states when to use this tool: 'review what you're monitoring before adding more' (implying subscribe) and 'to find an id to cancel' (implying unsubscribe). This provides clear contextual guidance relative to 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?

Annotations only provide hints (all false), but the description goes beyond by disclosing rate limits ('Rate-limited to 5 per identifier per day') and cost/quota implications ('Free; doesn't count against your tool-call quota'). It also mentions the team's daily digest and roadmap impact, which is behavioral context not present in structured fields.

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

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

The description is compact yet information-dense: every sentence serves a purpose—defining the action, specifying when to use, offering content guidance, and disclosing rate limits. It front-loads the core purpose and uses a clear structure without fluff or repetition of schema fields.

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 feedback submission tool with no output schema and simple parameters, the description covers all necessary aspects: purpose, usage scenarios, content expectations, and operational constraints (rate limit, quota). It even includes an example of the tool's use case (wrong/stale data, missing tool) which fully prepares the agent for correct invocation.

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

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

Schema already documents all parameters with 100% coverage, so baseline is 3. The description adds value by providing guidance on message content—'Describe the issue in terms of Pipeworx tools/packs' and 'don't paste the end-user's prompt'—which complements the plain-text 'message' field. It also implicitly clarifies the 'type' parameter semantics by linking each category to specific situations, though the schema already does this well.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly specifies the action (sending feedback) and the resource (Pipeworx team). It distinguishes itself from sibling research/query tools by framing the purpose around reporting bugs, feature gaps, and praise, making it unmistakably a feedback submission 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 states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' This gives clear criteria and even references specific feedback types, guiding the agent on appropriate invocation. It also advises against pasting user prompts, which is a useful usage constraint.

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 beyond this by disclosing data provenance ('derived from CF analytics-engine'), privacy ('no PII'), the data shape ('(pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This provides useful context not captured in annotations.

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

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

The description is appropriately sized, starting with an engaging summary question, then returning the core function, followed by a numbered list of use cases, and a final note on data source and caching. Every sentence carries meaningful information, 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?

With no output schema, the description still conveys the overall return shape: 'Returns the top tools, top packs, and total call volume' and 'just (pack, tool, count)'. It also covers use cases, data source, caching, and privacy, making it complete enough for a simple single-parameter read-only tool.

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

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

The schema provides 100% coverage for the 'window' parameter with a clear description of options and trade-offs. The tool description merely echoes this information without adding new meaning, so it meets the baseline but does not exceed it.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window'. It names a specific verb and resource, and distinguishes itself from siblings by emphasizing it shows what 'other AI agents are calling' right now, not a general search or 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 provides explicit 'Useful for' scenarios (e.g., discovering hot data sources, confirming canonical tool choice), which gives clear context on when to use it. However, it does not explicitly mention when not to use it or name alternative sibling tools, so it falls short of a 5.

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

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

The description goes far beyond the read-only annotations, detailing behaviors like live CLOB depth via fill_check, the 20% placeholder filter that can return null, the skipped_low_similarity rejected pair count, and the warning not to trade when realizable_edge_pp ≤ 0. This is rich, non-redundant context.

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

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

The description is long but well-structured with clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a front-loaded summary. Every sentence adds information, though some repetition (e.g., partition_check mentioned multiple times) makes it slightly less concise than ideal.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so effectively: it outlines the opportunities[] fields, partition_check object, and fill_check behavior. It also covers edge cases like placeholder filtering and similarity thresholds, making it 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?

The schema already covers both parameters with descriptions, so the baseline is 3. The description adds valuable examples (e.g., 'fed-decision-may-2026') and clarifies mode-specific semantics (event vs topic), which enriches what the schema provides. Still, the schema does most of the work, so 4 is appropriate.

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

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

The description opens with a clear verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This specifies the tool's purpose and distinguishes it from siblings by detailing unique modes (trending_scan, event, topic) and mentioning related tools like 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?

It explicitly states when to use each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...'. It also directs users to polymarket_fill_risk for custom sizing, clearly differentiating from an alternative tool. This is excellent practical 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 read-only, idempotent, open-world. The description goes well beyond by detailing response segments, diagnostics, caching at KV level keyed on knobs, the exclusion of Fed bets from ranking, and the rationale for why Fed signals are unreliable. It also discloses that partition arbs return kelly_fraction_half=0 at parent level, a non-obvious behavior. 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 dense, lengthy paragraph (~400 words). It front-loads the main purpose, but the sheer volume of technical detail, all-caps segment names, and run-on sentences make it less concise than ideal. Every sentence does provide information, but structure could be improved with bullets/segmentation. Adequate for a complex tool, but not a model of conciseness.

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

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

Given no output schema, the description thoroughly explains the response top-level structure, segment contents, diagnostics, and parameter knobs. It also covers caching and staleness behavior. It addresses why segments might be empty via diagnostics and covers Fed candidate placement. This is highly complete for a tool of this complexity.

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

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

Schema descriptions cover 100% of parameters, but the tool description adds key semantics not in the schema, such as min_partition_leg_kelly applying to per-leg Kelly inside top_legs and min_kelly never filtering partition_overround. It also groups min_liquidity/max_spread_pp as 'tradeable-edge knobs'. This exceeds baseline 3, though not all 9 parameters receive additional commentary.

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 opening sentence clearly states it scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, using a specific verb (scan/return) and resource (Polymarket markets). The detailed segment breakdown further distinguishes it from sibling tools like polymarket_arbitrage or edge_tracker by describing unique output segments and knobs.

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: 'Built for "what should I bet on today"' and notes agents can discover opportunities without paging hundreds of markets. It does not explicitly name alternatives or exclusions, but the context implies when to use it. Missing explicit 'when not to use' for 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?

Annotations already mark the tool readOnly, idempotent, and non-destructive. The description adds substantial behavioral details: snapshots are written on cache-miss so gaps mean no scan, history is bounded by a 60-day TTL, and decay is computed from daily closes of edge_pp_net (not intraday). This goes far beyond annotation hints.

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

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

The description is well-structured with ARGS, RESPONSE, and LIMITS sections. Every sentence contributes operational or interpretational value, and despite length, it remains scannable and front-loaded with the core purpose.

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

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

Given there is no output schema, the RESPONSE section fully explains returned fields (tracked[], expired[], snapshot_dates[]) and their semantics. LIMITS also covers data availability and caveats, making the tool usable 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%, providing defaults and clamps for both parameters. The description adds the concept of 'snapshot family' for the window parameter and clarifies days as a lookback across snapshots, which enriches the schema's straightforward 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 provides edge persistence and decay telemetry built from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. This specific verb+resource scope distinguishes it from sibling polymarket_edges, which presumably provides raw edges.

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

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

The description gives clear context by contrasting a fresh wide edge with a 3-week-old wide edge, implying this tool is for assessing edge age and decay. It does not explicitly name alternatives or when-not-to-use, but the context and LIMITS (TTL, cache-miss gaps) provide adequate usage guidance.

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

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

The annotations already declare the tool read-only, idempotent, open-world, and non-destructive, so the description adds behavioral depth by explaining ladder walking, slippage computation, return fields, and the risk of partial basket fills stranding the user unhedged. It also clarifies default side selection and size_usd interpretation, enriching the safety profile without contradicting any annotation.

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

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

The description is long but efficiently organized into clear sections (SINGLE-MARKET and BASKET), with each sentence carrying essential setup, interpretation, or risk information. It remains front-loaded with the core purpose, and no sentence is redundant.

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

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

For a tool with no output schema, the description lists the key return fields for both modes, specifies edge-case behaviors (clamping, auto side), and provides actionable guidance on when to use it. The complexity is high, but the description covers all necessary operational and interpretive details.

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 the input schema fully documents the parameters, the description materially extends their meaning: it explains that market selects single-market mode while event selects basket mode, that side defaults vary by context, and that size_usd is interpreted as spend/target proceeds in single-market mode but settlement notional in basket mode. It also notes clamping and the auto side logic, which the schema alone does not convey.

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

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

The description opens with a specific verb+resource ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and clearly distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk. It also details two operational modes (single-market and basket), making its scope unmistakable.

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

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

It explicitly instructs when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, referencing thin-book overround and partial-fill directional risk, and implies it's not needed for small trades below that threshold.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints, but the description goes far beyond by disclosing specific edge-case behaviors: compatibility_warning conditions (two distinct cases), temporal_alignment impact, skipped_cross_type/subtype counters, and the note that real cross-venue spreads are rarer than the shortcut list suggests. This exceeds what annotations provide.

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

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

The description is long but meticulously structured: purpose first, then TWO MODES, RESPONSE, SAFETY FIELDS, and a caution. Every section adds specific value, though the density and sentence length make it slightly heavy. It earns its length but could be tightened.

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

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

For a complex tool with no output schema, the description covers both input modes, response structure (leg-by-leg prices, spread[].top_spreads_pp), safety fields, temporal alignment, and skipped-pair counters. It also explains what 'aligned:false' means for interpreting spreads, making the tool fully usable 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?

Even though schema coverage is 100%, the description enriches parameter meaning by explaining the two modes: 'topic' as a set of pre-mapped shortcuts (with the full list in the schema), and explicit ticker/slug usage with override semantics ('Overrides the topic-mapped side'). This contextualizes how parameters interact and clarifies expected values beyond plain schema descriptions.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', which clearly identifies the specific verb (compute spread) and resource (two named prediction markets). It distinguishes from sibling tools like polymarket_arbitrage by emphasizing cross-venue comparison, and it details two distinct modes of operation.

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

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

The description clearly explains when to use the tool via two modes and provides explicit warnings about when spreads are not meaningful (compatibility_warning, temporal_alignment:false). It also cautions that 'pre-mapped ≠ tradeable' and that most pre-mapped topics return warnings. However, it does not explicitly reference sibling tools as alternatives, so it stops short of full when-to-use versus alternative guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds scoping behavior ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the list-all-keys behavior, which are meaningful 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?

Three sentences with front-loaded core function, followed by concrete use cases and scope. Every sentence adds value—no fluff or repetition, making it highly concise 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 one-parameter tool with robust annotations and schema, the description covers purpose, usage, scope, and relationships to remember/forget. No significant gaps remain, and the return format is not essential given the output schema is absent.

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 key parameter is already described as 'Memory key to retrieve (omit to list all keys).' The description mirrors this without adding new parameter-specific details, so the baseline 3 applies.

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

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

The description clearly states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument),' which is a specific verb and resource. It distinguishes from siblings by explicitly pairing with remember and forget, making its role 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 usage context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also names the paired tools (remember, forget), guiding when to use this tool versus alternatives.

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

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

The description states that mark_read:true flags events read, causing subsequent calls to show only newer events. This contradicts the annotation readOnlyHint=true, indicating a write side-effect. Annotations also claim idempotentHint, but mark_read makes repeated calls non-idempotent. Therefore, the description directly contradicts the structured metadata.

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

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

Three sentences, front-loaded with the primary action and return payload, then filtering/side-effect, then polling/alternative endpoint. Every sentence adds distinct value with no 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?

With no output schema, the description provides key return fields (source, citation_uri, raw event payload) and explains side-effects of mark_read. It also mentions the persisted nature of the feed and alternative access. The absence of an explicit statement about the readOnly annotation's contradiction with mark_read creates minor confusion, but the description itself is thorough. Slight deduction for not clarifying the mutable nature against the annotation.

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

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

Schema already covers all parameters (100% coverage), giving baseline 3. The description adds meaningful context beyond schema: an example type filter ('sec_8k') and the persistent consequence of mark_read, which helps the agent understand parameter effects. It does not mention unread_only, but the schema covers it.

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

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

The description clearly states the tool pulls fired events from the subscription feed, with a specific verb and resource. It distinguishes the tool from siblings by focusing on alerts with source, citation_uri, and raw event payload, as well as filter options.

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

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

The description gives clear context: it's for polling recent alerts from the feed, with filtering and mark_read behavior. It also mentions an alternative endpoint for scripts, which aids usage decisions, though it does not explicitly contrast with sibling tools 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?

The description goes well beyond annotations by detailing source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO), a soft-fail for PatentsView, and the return structure (changes[] grouped by source, total_changes count, citation URIs). It also explicitly mentions 'ONE parallel call' as an operational characteristic. 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 but front-loaded with purpose, then logically progresses to sources, parameters, return value, and alternative tool. Every sentence adds distinctive information; no fluff or repetition.

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

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

Given the tool's complexity (multiple sources, fallbacks, soft-fails, flexibility in `since`), the description is remarkably complete. It covers what the tool returns, how sources behave, and when to use an alternative. With no output schema, the description carries the burden for return semantics and does so effectively.

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

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

The input schema already has 100% coverage, so baseline is 3. The description adds significant value for `since` by explaining accepted formats (ISO date or relative shorthand with examples) and recommending '30d' or '1m' for typical monitoring. It also describes `value` as ticker or zero-padded CIK, but that repeats the schema. No additional nuance for `type`, so not a full 5.

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

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

The description clearly states the tool's function with specific verbs ('change feed', 'fans out') and the resource (company). It uses natural language queries to illustrate intent and explicitly distinguishes itself from the sibling tool entity_profile by stating 'Use entity_profile instead when you want the static profile'. The scope (last N days/weeks/months) and data sources are also specified.

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

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

The description provides explicit when-to-use guidance through example queries and states an alternative for a different use case: 'Use entity_profile instead when you want the static profile... regardless of window.' It also clarifies the fallback behavior (GDELT preferred, GNews on rate-limit/5xx) and supports typical monitoring patterns with `since` suggestions.

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, the description reveals persistence semantics: authenticated users get persistent memory, anonymous sessions retain for 24 hours, and data is a key-value pair scoped by identifier. It does not explicitly state overwrite behavior, but annotations already note idempotency, so the added context is valuable.

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

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

Four sentences efficiently cover purpose, usage, scoping, persistence, and companion tools. The description is front-loaded with the core action, and every sentence adds useful information without redundancy.

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

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

For a simple two-parameter write operation with no output schema, the description covers what to store, when to use it, scoping, retention, and lifecycle (recall/forget). It is complete given the tool's complexity and available annotations.

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 both parameters fully, but the description adds contextual examples of keys (resolved ticker, target address, user preference) and values (findings, preferences, notes), enriching the meaning beyond placeholder schema entries.

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

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

The description states a specific action 'Save data' with a clear purpose: reuse later across conversations or sessions. It provides concrete examples (ticker, address, user preference, research subject) and distinguishes itself from siblings by explicitly naming recall and forget as companion operations.

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

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

Explicit 'Use when you discover something worth carrying forward' defines the trigger scenario. It also names complementary tools: 'Pair with recall to retrieve later, forget to delete', which clarifies when to use this tool versus siblings.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable behavioral context: it accepts multiple input forms (ticker, CIK, name; brand or generic), auto-disambiguates, cascades through multiple lookup endpoints internally, and returns specific fields including citation URIs. This goes well beyond the annotations.

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

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

The description is thorough but every sentence contributes: purpose examples, usage directive, type-specific outputs and input forms, and the value-add comparison to manual lookups. It is front-loaded with the core purpose and uses clear formatting (SUPPORTED TYPES) to enhance readability 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?

There is no output schema, so the description must explain return values, and it does completely: for company it lists ticker, CIK, company_name, and citation URI; for drug it lists RxCUI, ingredient, brand, and citation URI. It also covers input variants and disambiguation, making the description sufficient for an agent to use the tool correctly without further inference.

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

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

The input schema already covers both parameters with descriptions, so baseline is 3. The description adds substantial meaning by providing concrete examples ('AAPL', '0000320193', 'ozempic') and clarifying input format fallbacks for each type, plus explaining what value each type returns. This elevates the parameter documentation 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 resolves a user-spoken name to the canonical/official identifier, with concrete examples ('ticker for', 'CIK for', 'RxCUI for'). It explicitly lists supported entity types (company, drug) and the exact outputs, distinguishing it from sibling tools that use identifiers rather than resolve them.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID', which is a direct when-to-use guideline. It also defines the two supported types, signaling that other entity types are not covered, and notes that this tool replaces 2-3 manual lookups, conveying its role as a pre-processing step.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral detail: it invokes ai_visibility_check per entity, ranks results, and returns score, confidence, and signal density. This contextualizes the open-world nature without contradicting annotations. It does not disclose potential costs or rate limits, but annotations minimize that need.

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, front-loaded with the primary action, no redundancy. Every sentence adds value: comparison scope, mechanism, use case, and return format.

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 4 params and no output schema, the description gives a clear picture of what it does, how it works, and what it returns. It could be more explicit about entity count constraints and model selection, but the schema covers those. The return format description ('ranked list with score, confidence, signal density') compensates for the missing output schema.

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

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

Schema covers 100% of parameters, so the baseline is 3. The description reinforces that 'entities' are brand/business/product names and that the first is the subject, but this is already in the schema. It does not add new parameter semantics, just restates the purpose.

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

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

The description opens with 'Compare AI visibility across multiple entities side-by-side,' a specific verb (compare) and resource (AI visibility) with scope (multiple entities). It further differentiates from siblings like ai_visibility_check by noting it probes multiple entities and ranks by score, and from compare_entities by focusing on AI visibility specifically.

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 'Useful for competitive AI-marketing audits' with an example query, providing clear context for when to use. Implicitly contrasts with ai_visibility_check (single-entity) by emphasizing 'across multiple entities.' However, it does not explicitly state exclusions or name alternative tools for single-entity checks beyond the mechanic reference.

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

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

The description goes beyond the readOnly/idempotent annotations by disclosing that the tool makes composite external API calls, includes a latency caveat ('bundlephobia's first measurement on a new version can take 5-30s'), and explains graceful degradation ('sources_failed will list it if it times out, the rest still returns'). It also notes ecosystem limitations. This is rich behavioral context not covered by annotations.

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

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

Although the description is longer than most, it is densely packed with useful information: purpose, use cases, return fields, ecosystem scope, latency, and failure handling. Every sentence earns its place and the structure flows logically. No fluff or repetition.

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

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

Given that there is no output schema, the description compensates by listing all return fields (summary block, per-advisory detail, links, recent versions). It also covers partial failure behavior, timeouts, and ecosystem constraints. For a composite tool with 2 parameters, this is highly complete and leaves little ambiguity about what the tool does and returns.

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

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

Schema coverage is 100% with clear parameter descriptions for 'package' and 'version'. The tool description does not add extra meaning beyond what the schema already provides; it merely mentions the default behavior of 'version' which is already documented. Thus, baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a composite 'should I add this npm package' check that fans out to deps.dev and bundlephobia. It specifies the exact services and data points involved, distinguishing it from general scanning tools. The verb 'scan' and resource 'dependency' are specific and unambiguous.

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

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

The description explicitly states when to use the tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides a clear exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', offering an alternative path for non-npm packages. This satisfies the 'when/when-not/alternatives' criteria.

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

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

Annotations already cover readOnly/idempotent/destructive, but the description adds crucial operational behavior: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and output per passage (offsets + similarity scores). This is far richer than the annotations alone and discloses edge-case behavior (truncation). 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?

Three sentences, front-loaded with the core purpose, then a use case, then implementation details. Every clause adds value—no filler or repetition. The structure moves from 'what' to 'when' to 'how', which is ideal.

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

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

For a search/retrieval tool with no output schema, the description fully covers the return shape (passages with offsets and scores), the algorithmic details (embedding, cosine, windows), the limitations (200K cap, truncation), and the integration context (pairs with grounded). This leaves little ambiguity for an agent deciding whether and how to invoke.

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 does not significantly augment parameter semantics beyond what the schema already provides; it reinforces that 'text' is the pulled record and gives example queries, but these are also in the schema descriptions. No compensation needed.

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

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

The description states a specific verb and resource: 'Semantic search INSIDE a fetched record' with clear mechanics. It distinguishes itself from siblings by name-checking ask_pipeworx_grounded and explaining the niche role (searching within already-fetched text). This is unambiguous and differentiated.

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

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

The description explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also gives a concrete pairing recommendation with ask_pipeworx_grounded, explaining the workflow. This goes beyond vague context to actionable decision guidance.

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

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

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description reveals significant behaviors: handle-shape-based network inference, a networks_tried field for ambiguous handles, a clear distinction between null days (outside feed reach) and measured zeroes, and the directional-proxy limitation. These are rich, non-obvious details that materially affect interpretation of results. 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 fairly long but every sentence serves a purpose: scope, output, usage examples, network inference, null handling, exclusions, and caveats. It front-loads the core purpose and uses examples to ground the handle format. The length is justified by the tool's complexity, though a tighter phrasing could earn a 5.

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

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

With no output schema, the description carries the burden of conveying return behavior, and it does so well by explaining the time series shape, average engagement, most recent post timestamp, and the networks_tried field. It also articulates edge cases (null vs zero, ambiguous handles). Minor gap: it never names the exact JSON structure of the time series (e.g., array of {date, count}), but the textual description is sufficient for an agent to interpret results.

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

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

The schema already provides complete descriptions for both parameters (handle and days) at 100% coverage, so the schema carries the load. The description adds some contextual color—e.g., handle shape inference and examples—but does not introduce parameter syntax beyond what the schema states (e.g., 'days' min/max/default are already in the schema). Baseline 3 is appropriate because the description adds marginal value over the schema.

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

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

The description opens with a specific verb+resource: 'POSTING CADENCE for one social media account as a TIME SERIES,' and enumerates exactly what is returned (posts per day, average engagement, final post timestamp). It also distinguishes itself from siblings by explicitly excluding X/Twitter and naming the supported networks (Bluesky, Mastodon, Reddit, Hacker News), making the tool's scope 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 answers typical user questions ('how often does this account post', 'has this account gone quiet', etc.), which strongly signals when to use it. It also sets an important boundary: 'X/Twitter is excluded (paid API),' so users don't expect X coverage. However, it does not explicitly name alternative sibling tools like social_topic_volume for topic-based queries, leaving some ambiguity about when to choose this over related 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?

Despite annotations already indicating readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, the description adds critical behavioral context: 'A bucket is a number only where that network was truly measured; where reach ran out it is null, so a measured zero is always distinguishable from an unobserved gap' and details the 'window_actually_covered block'. These explain output semantics beyond the annotation cues.

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

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

The description is well-structured and front-loaded: it defines the tool in the first sentence, states the questions it answers, describes return values, then covers null semantics and limitations, finishing with examples. Every sentence adds useful information; no filler.

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

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

With 5 parameters and no output schema, the description is remarkably complete. It describes the return shape ('per-bucket count broken out by network, running totals, engagement sums... and an explicit window_actually_covered block'), clarifies coverage gaps, and explains limitations. This gives an agent enough context to invoke and interpret results 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%, so baseline is 3. The description's examples (e.g., 'topic "bitcoin", days 7, bucket "day"') mirror the schema's examples and do not add meaning beyond what the schema already provides. The schema itself already explains defaults, caps, and network enum values.

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

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

The description opens with 'SOCIAL MEDIA VOLUME as a TIME SERIES: how many posts mention a topic, bucketed by day or hour' – a specific verb (count/measure) + resource (posts mentioning a topic) + time-series scope. This clearly distinguishes it from siblings like social_account_activity, which focuses on account activity, not topic volume.

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

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

It provides concrete examples ('topic "bitcoin", days 7, bucket "day" for a week-long attention curve') and explicitly states coverage limitations ('X/Twitter is excluded... directional proxy'), which tells the agent when to use it and what to expect. However, it does not explicitly name alternative sibling tools, so it falls short of a 5.

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

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

The description adds substantial behavioral context beyond the annotations: it requires a Pipeworx OAuth account, notes anonymous/BYO cannot persist, explains the always-on feed, phone verification, 10/day SMS cap, and how delivery works. Annotations are not contradicted.

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 appropriately sized for the tool's complexity. It is front-loaded with the purpose and return value, followed by requirements, supported types, and delivery channels. Every sentence earns its place with no filler.

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

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

For a complex creation tool with no output schema, the description covers purpose, return value, authentication, all supported types, delivery channels, verification, and limits. It provides enough context to invoke the tool correctly even without consulting the full schema.

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

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

The schema already covers 100% of parameter descriptions, but the tool description adds valuable semantics: examples like items:['5.02'] = officer change, Polymarket topic handling, FRED series_id usage, and delivery channel constraints. This goes 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 uses a specific verb-resource pair: 'Create a proactive monitoring subscription to a live-data event stream' and states the return value (the new subscription id). It clearly distinguishes subscribe from sibling tools like list_subscriptions, unsubscribe, and recent_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 provides clear context for when to use the tool: proactive monitoring of a live-data event stream, with required OAuth account and supported subscription types. It does not explicitly name alternatives or exclusion criteria, but the context is strong enough to guide 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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the output format (category-bucketed example questions), the fact it draws from a 'live catalog,' and that each example includes the exact tool and argument shape. This 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 long but well-structured: it front-loads natural-language questions, then gives a compact explanation of the output, invocation modes, and positioning. It is slightly dense—packing many categories and tool names into one continuous sentence—but every clause serves a purpose and nothing feels repetitive.

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

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

For a simple tool with one optional parameter and no output schema, the description is exceptionally complete. It explains what the tool returns, the categories it covers, how to call it with and without `topic`, when to use it first, and what meta-tools it introduces. Combined with strong annotations, there is no meaningful gap in the agent's ability to select and invoke this tool.

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

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

Schema coverage is 100% for the optional `topic` parameter, so the baseline is 3. The description adds value by translating the schema's enum-like list into natural-language focus areas ('finance', 'pharma', 'betting') and by clarifying that omitting topic returns a cross-category spread. This enrichment justifies one point 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?

The description uses specific verbs and a clear subject: it 'returns category-bucketed example questions' and positions itself as the 'onboarding entry point.' It distinguishes itself from siblings by instructing the agent to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and by explicitly listing the meta-tools it can teach you to call.

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the two invocation modes—'Call with no arguments for the full spread, or pass topic'—which is actionable usage guidance beyond a generic purpose statement.

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 (readOnlyHint:false, idempotentHint:true, destructiveHint:false), the description adds that ownership is enforced and that cancellation deactivates rather than deletes, preserving historical data for recent_alerts. This provides useful behavioral context beyond what annotations already convey, though it omits some possible 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?

The description is two sentences, front-loaded with the primary action, 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?

For a simple one-parameter tool with no output schema, the description covers the main operation, ownership rules, and the deactivation behavior, which is sufficient for an agent to invoke it correctly. It could mention error handling, but that's a minor omission.

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

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

The schema already provides 100% coverage with a description for the id parameter ('Subscription id (uuid) returned by subscribe.'). The description only adds 'by id' which is redundant with the schema, so it doesn't add meaningful new parameter semantics.

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

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

The description clearly states the tool cancels a subscription by id, using a specific verb ('Cancel') and resource ('subscription'). This distinguishes it from siblings like subscribe (opposite action) and list_subscriptions (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?

It provides clear context: ownership is enforced, so only your own subscriptions can be canceled, and it notes the row is deactivated not deleted, which preserves historical events via recent_alerts. This implies when to use the tool, though it doesn't explicitly mention alternatives or 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 readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: it explains the two processing paths (structured SEC EDGAR + XBRL for company-financial, grounded pipeline for anything else), the verdict enum, and that it returns evidence with a citation. This gives the agent a realistic expectation of how the tool operates.

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

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

The description is longer than average but earns its length: it starts with trigger phrases, states purpose, then details routing, return value, and the composite nature of the tool. Each sentence adds distinct information without redundancy. A slight trim would make it more concise, but it remains 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?

With no output schema, the description must explain return values, and it does: verdict, grounded/structured value with pipeworx:// citation, and reasoning. It also covers the routing logic for claim types and the composite nature (replacing 4-6 calls), which is sufficient for a complex tool. Minor gaps like error scenarios are partially covered by the 'inconclusive/unsupported' verdicts, making this comprehensive overall.

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 provides 100% coverage of both parameters with detailed descriptions: claim syntax and tolerance_pct range, override behavior, and default cap. The main description adds minimal parameter insight beyond 'exact percent-delta math', so the schema already carries the semantic burden. This matches the baseline for high schema coverage.

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

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

The description clearly defines the tool as 'natural-language claim verification against authoritative sources' and lists trigger phrases like 'fact check' and 'verify the claim that'. It uniquely distinguishes itself from sibling tools by describing the dual-path architecture (SEC EDGAR/XBRL for company-financial claims vs. grounded pipeline for other claims), making the purpose unambiguous.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct', providing a clear when-to-use directive. It also explains how different claim types are routed, which implies the tool is the go-to for all fact-checking. However, it does not name specific sibling tools or give explicit 'when not to use' scenarios, so it falls slightly short of a 5.

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