Clickup

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

The description discloses behavioral traits beyond annotations: it explains the probing mechanism, return format (per-model with score, confidence, signals, raw_response plus combined view), and the cost model (free default vs BYO key for Anthropic). No contradictions with annotations.

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

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

The description is relatively concise at 3-4 sentences, front-loaded with the core action and result. It could be slightly more structured (e.g., bullet points for return fields), but every sentence adds value.

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

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

Given no output schema, the description adequately explains the return structure (per-model object + combined view). All parameters are described with their roles, and the tool's purpose is fully contextualized for a user unfamiliar with it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the default model for 'models' parameter, the purpose of '_apiKey' (BYO key), and the disambiguation role of 'context'. This exceeds baseline.

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

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

The description clearly states the tool probes LLMs for awareness of a business/brand/product/topic and scores visibility. It explicitly mentions AI-marketing audits, distinguishing it from sibling tools like scan_competitor_ai_presence or compare_entities which have different scopes.

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

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

The description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use parameters like _apiKey for Anthropic. While it doesn't state when not to use, the context is clear and it implies alternatives exist among siblings.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it routes to 5,743 tools across 1,500 verified sources, fills arguments automatically, returns stable pipeworx:// citation URIs, and works on every tier in one fast call. This meaningfully enriches the annotation-only safety profile without contradicting it.

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

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

The description is long but densely informative, with the most critical routing guidance ('PREFER OVER WEB SEARCH') front-loaded. The examples and alternative-routing statements each earn their place, though some phrases like 'works on every tier' and 'even if web search could also answer it' are slightly 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 broad routing tool with no output schema, the description covers the key contextual needs: domains covered, query phrasing patterns, concrete examples, fallback/alternative tools, expected behavior (citations, argument filling), and scope. An agent has enough information to decide when to call this tool and what to expect from it.

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

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

Input schema coverage is 100% and already documents the question field plus all aliases. The description adds illustrative query types and examples, but does not clarify parameter behavior beyond what the schema provides. Baseline 3 is appropriate since the schema carries the semantic weight.

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 clear verb+resource: routes a natural-language question to the right specialized tool and returns a structured answer with citations. It explicitly differentiates itself from siblings like ask_pipeworx_grounded and deep_research by naming them and explaining when to step up.

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 strong when-to-use guidance: prefer over web search for factual/current/historical data, use for common question phrasings like 'what is', 'look up', 'find', and includes concrete examples. It also names exclusions and alternatives: ask_pipeworx_grounded for hallucination-resistant single 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 read-only, open-world, idempotent annotations, the description adds meaningful behavioral context: candidate routing improvements are enabled live only when under test, no candidate is active right now, and this is a full working router rather than a thin fallback. This materially changes how an agent should interpret results and prevents misconceptions about the tool being incomplete.

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 information-dense and front-loaded with the beta relationship to ask_pipeworx. Some specifics, such as the exact 5,743-tool count and the retirement date, are slightly beyond what is strictly needed, but they support the 'currently identical' claim; overall it is a bit wordy but every sentence earns its place.

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

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

It covers the tool's identity, current active-candidate status, behavior relative to ask_pipeworx, and usage instruction. However, with no output schema, the promise of "same response shape" is only a pointer to the sibling; an agent without prior knowledge of ask_pipeworx's response would still lack concrete return-value detail.

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

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

The input schema covers 100% of parameters, including a description for `question` and each alias, so the description adds little semantic value about inputs. It mentions "same arguments" but does not explain argument nuances, making the schema the primary source of parameter meaning.

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

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

The description immediately identifies this as the beta variant of ask_pipeworx and states it is a universal router with the same 5,743 tools, arguments, and response shape. It clearly distinguishes it from the stable ask_pipeworx by framing it as the experimental edge, so an agent knows exactly what resource it targets.

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 tells the agent to use it "exactly like ask_pipeworx when you want the newest routing" and explains that results are compared against the stable router to guide merges. The beta framing and direct alternative naming give clear context for when to choose this tool over the stable sibling.

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

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

Annotations declare readOnly and idempotent hints, but the description adds substantial behavioral context: it explains the refusal contract, enumerates all refusal_reason values, discloses that extraction is limited to the tool result, and notes the extra LLM call cost. This goes well beyond what the 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 dense but well-organized: it front-loads the core purpose, then provides the return/refusal contract, usage guidance, and cost tradeoff. Every sentence contributes actionable information, and the structure makes the key distinctions easy to scan.

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

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

There is no output schema, so the description fully compensates by specifying the success return shape and the refusal shape with exact reason strings. It also covers when to choose the alternative tool and what behavioral guarantees to expect, making the definition complete for an agent selecting and invoking the tool.

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

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

Schema description coverage is 100%, and the schema already documents that all six parameters are aliases for the natural-language question. The description adds no additional parameter meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and clearly identifies the tool's resource and action: it routes like ask_pipeworx but then extracts an answer using only the tool result. It differentiates itself from the sibling ask_pipeworx by emphasizing grounded, evidence-backed answers versus casual lookups.

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

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

Explicitly states when to use this tool: whenever an answer will be quoted, cited, or acted on, and when the agent must not invent facts, with concrete domains like financial verdicts and legal claims. It also names the alternative ('prefer ask_pipeworx for casual lookups') and explains the cost tradeoff of one extra LLM call.

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, open-world, idempotent behavior. The description goes far beyond, detailing safety short-circuits (low-confidence match, closed markets), tradeability warnings (wide spreads), resolution-rule risk (void settlements), and fallback behavior for news sources. No contradictions with annotations; the description adds substantial behavioral context for safe invocation.

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

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

The description is front-loaded with the core purpose and usage, then organized into logical sections (classifiers, fan-out examples, response shapes, resolver contract, etc.). It is comprehensive but somewhat verbose; some details could be condensed without losing clarity. Overall well-structured 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 (multiple data sources, resolution logic, safety checks), the description is remarkably thorough. It covers input types, execution flow, output structure, error/short-circuit conditions, risk details, and even performance guidance (include_raw). No output schema exists, but the description fully compensates by explaining return shapes and fields. The contextual completeness is exemplary.

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 100% of parameters with descriptions. The description adds value by explaining the semantics of the depth enum ('quick = 2-3 evidence sources, thorough = full fan-out'), the market parameter input types (slug/URL/question text), and include_raw behavior with size implications. This enriches the schema beyond basic type info.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and verb (research), and the extensive detail on classifiers, fan-out, and response shapes leaves no ambiguity. Although sibling tools address related tasks (e.g., polymarket_edges, ask_pipeworx), the description implicitly distinguishes by focusing on bet-specific research with a structured evidence pipeline.

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 provides use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains the depth parameter and when to use quick vs thorough. However, it lacks explicit guidance on when not to use this tool or alternatives to consider, which would strengthen the dimension.

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 flag readOnly=false and destructive=false, so the description's 'Create' is consistent. However, idempotentHint=true contradicts the implication that each call creates a distinct task. The description adds return value info but lacks deeper behavioral context like rate limits or authentication requirements beyond the API key parameter.

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

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

Two sentences, front-loaded with purpose, then inputs and outputs. Every sentence is valuable 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 an output schema present, the description sufficiently covers inputs and outputs. However, the mention of a non-existent 'assignee' parameter creates a gap, and the description does not explain the idempotency hint or the openWorldHint.

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

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

Schema coverage is 100%, so baseline is 3. However, the description mentions 'assignee' as an optional parameter, but the schema does not include any assignee property. This discrepancy undermines clarity and could mislead an agent. The description adds no additional meaning beyond the schema's own parameter descriptions.

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

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

The description clearly states the verb 'Create' and resource 'task in a ClickUp list', specifies required inputs, and distinguishes from sibling tools like clickup_get_task and clickup_list_tasks.

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

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

While it doesn't explicitly state when to use or not to use, the context is clear: it's for creating a new task. The sibling list contains no other creation tools for tasks, so ambiguity is low.

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. Description adds value by specifying exact fields returned, confirming safe read behavior.

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

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

Two sentences, front-loaded with key information, no redundant text.

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?

Output schema exists, parameters fully documented, description lists returned fields. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. Description only adds example for task_id, no extra semantics beyond schema.

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

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

Description clearly states it fetches full task details and lists specific fields (name, description, status, etc.). It distinguishes from sibling tools like clickup_list_tasks, and includes resource identifier format.

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 basic guidance to provide task ID, but no explicit when-to-use vs alternatives. Acceptable given clear name and context from siblings.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns 'folder ID, name, and list count', providing expected outputs. No contradiction with annotations.

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

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

Two sentences, no wasted words. Purpose is stated first, followed by usage and return info. Efficient and well-structured.

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

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

Given the simplicity of the tool (2 params, no nested objects, read-only), the description covers purpose, parameter guidance, and return fields. Annotations provide additional behavioral context. Output schema exists but description already mentions key return fields.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds an example value for space_id ('789'), but this is minimal extra meaning. Baseline of 3 is appropriate.

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

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

The description clearly states 'List all folders in a ClickUp space,' specifying a concrete verb ('List') and resource ('folders'). This differentiates from sibling tools like 'clickup_list_spaces' and 'clickup_list_tasks', which list different 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?

It instructs to 'Provide space ID (e.g., "789")', giving a clear usage hint. While it doesn't explicitly state when not to use it, the purpose is unambiguous and distinct from other tools, making selection straightforward.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to repeat safety info. However, it adds no additional behavioral context beyond what the annotations and schema provide, such as rate limits or permissions.

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 sentence that front-loads the verb, resource, and scope, followed by return data. No extraneous information, every word serves a 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?

For a simple list tool with two parameters and an output schema, the description provides sufficient information: it lists all spaces, specifies the return fields, and is self-contained. No gaps given the tool's low 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%, with both parameters (_apiKey and team_id) already documented. The description does not add any parameter-specific meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

Description clearly states the tool lists all spaces in a ClickUp workspace, specifying the verb 'List' and resource 'spaces', and mentions return fields (ID, name, status). It distinguishes itself from sibling tools like clickup_list_folders and clickup_list_tasks by focusing on a different resource.

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

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

The description implies the tool is for listing spaces but provides no explicit guidance on when to use it versus alternatives or when not to use it. However, the sibling list contains no other spaces tool, so context reduces ambiguity.

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 (readOnlyHint, idempotentHint, destructiveHint) already declare the tool is safe and idempotent. Description adds value by listing returned fields and confirming it returns all tasks. No contradictions.

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

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

Two sentences, no wasted words, front-loaded with purpose and output. Ideal 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?

Output schema exists and description briefly mentions return fields. For a list tool, the description sufficiently covers core functionality, though pagination or ordering details could be mentioned.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. Description only mentions list_id with an example, adding marginal value over 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?

Title and description clearly specify listing tasks in a ClickUp list, with explicit return fields (ID, name, status, etc.) and required parameter list_id. Differentiates from siblings like clickup_get_task and clickup_create_task.

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?

Description states 'Provide list ID' but does not explicitly guide when to use this tool vs alternatives (e.g., for bulk retrieval vs single task). Usage context is implied but not formally stated.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds that results are sorted by primary metric, handles off-calendar fiscal years, and returns citation URIs. This adds useful context beyond annotations.

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

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

Description is moderately long but front-loaded with example queries and packed with useful information. Every sentence earns its place. Could be slightly more concise but effective.

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

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

For a tool with 2 parameters and no output schema, the description explains output format (paired data + URIs), ordering, and entity-specific data fields. It 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 describes both parameters with 100% coverage. Description adds entity-specific details: type='company' pulls financials (revenue, net income, cash, debt) from EDGAR, type='drug' pulls adverse events, approvals, trials. Also clarifies values format (tickers/CIKs vs drug names) and bounds (2-5 items).

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 does side-by-side comparison of 2-5 companies or drugs. It specifies data sources for each type (SEC EDGAR for companies, FAERS/fda/trials for drugs) and distinguishes from single-entity lookups like entity_profile.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example phrasings. It could be improved by mentioning when not to use it (e.g., single entity queries) but is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial context beyond those: account/paid-tier requirements, parallel routing to 5,743 tools, gaps[] for unanswered facets, contradictions[], hop fields, fetchable citation_uri guarantees, semantic excerpting, and latency expectations. It clearly explains the tool's safety and execution profile without contradicting the annotations.

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

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

The description is long but information-dense; nearly every sentence earns its place by adding operational detail (account requirements, latency, citation fetchability, excerpting behavior). It is front-loaded with the most critical caveat (account required) and the primary alternative. Some depth-level detail is somewhat redundant with the schema, but not to a distracting degree.

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 behavior, and it does: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, and citation_uri semantics. It also covers preconditions, latency, and exclusions. An agent has enough context to decide when to call this tool and roughly what to expect back.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it clarifies that 'question' should be natural language and that broad/multi-part questions are appropriate, and it elaborates how depth levels affect hops, gap recovery, contradiction scanning, and latency. This is genuine added value, though the schema already carries the core parameter 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 names a specific verb-resource pair: 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources' in one call. It explicitly differentiates itself from open-web search and from sibling tools like ask_pipeworx, 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 gives explicit when-to-use guidance: use for broad/multi-part structured-data questions, use ask_pipeworx for single lookups and for breaking/current-news topics. It also names a fallback when not signed in ('use ask_pipeworx instead'), leaving no ambiguity about tool 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=true, idempotentHint=true, and destructiveHint=false, signaling safe read-only behavior. The description goes beyond by detailing the return format: 'full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This adds valuable behavioral context about efficiency and immediate usability.

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

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

The description is four sentences, front-loaded with the primary action ('Find tools by describing the data or task'), and efficiently conveys purpose, domain coverage, return value, and usage order. Every sentence adds value with no redundancy.

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

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

Despite lacking an output schema, the description sufficiently explains that the tool returns tool names, descriptions, and full schemas with examples. It covers all key aspects: purpose, domain scope, return format, and behavioral cues, making it complete for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100%, and the schema already describes all parameters (including aliases) with clear descriptions. The description reiterates that 'query' accepts a natural language description and mentions aliases, but adds no new semantic information beyond what is in the input schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and explains that it returns top-N relevant tools with full schemas. This explicitly distinguishes it from sibling tools like 'search_within' or 'resolve_entity' by framing it as a discovery tool.

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

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

The description provides explicit usage guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also enumerates scenarios where this tool is appropriate (browsing, searching, looking up, discovering) and implies it should be used before other tools for situational awareness.

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 with readOnly/idempotent annotations already present, the description adds valuable behavioral detail: parallel fan-out across sources, soft-failure for the PatentsView sunset, empty sections meaning genuine 'no data', and a resolved:false path with an explanatory note for private companies. No contradiction with annotations; this is the kind of disclosure that lets an agent set correct expectations.

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

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

The description is long, but the complexity of a multi-source fan-out tool justifies the length, and the opening sentence front-loads the core purpose. Some repetition through example phrasings keeps it dense but not wasteful.

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

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

With no output schema to lean on, the description carries the full burden and delivers: it enumerates every returned section, defines success and failure semantics, and notes expected edge cases like FDA products for small-molecule-only companies. For a complex tool with many sources, an agent has almost everything needed to call and interpret it correctly.

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

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

Schema coverage is 100%, so the baseline is met; the description goes further by giving concrete value examples, clarifying that 'company' and 'ticker' are interchangeable, and describing name resolution via SEC EDGAR. This reduces ambiguity around the 'value' parameter beyond the schema's own descriptions.

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

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

The description opens with a clear, specific verb-plus-resource statement: it produces a 'full cross-source profile of a US public company' and maps several user phrasings to the tool. It distinguishes itself from chaining single-pack lookups, though it does not name sibling tools like deep_research or compare_entities directly, so differentiation is implicit rather than explicit.

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

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

It explicitly tells the agent to 'ALWAYS PREFER' this tool over chaining single-source lookups when the user wants a holistic company view, and it explains acceptable input shapes. It handles the private-company case, but it does not explicitly carve out when to choose a named sibling such as deep_research or resolve_entity.

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 confirms the destructive nature (delete) which aligns with annotations (destructiveHint=true). However, it does not add behavioral details beyond what annotations already provide, so it neither enhances nor contradicts.

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 extremely concise with two sentences. The first sentence states the core action, and the second provides use cases and related tools. No unnecessary words.

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

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

Given the tool's simplicity (1 required parameter, no output schema, annotations present), the description fully covers purpose, usage context, and related tools. It is complete for effective agent 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?

The schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description only mentions 'by key' without adding new semantics, meeting 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 states the action ('Delete') and the resource ('a previously stored memory by key'). It distinguishes itself from sibling tools like 'remember' and 'recall' by specifying the operation type and the method of identification (by key).

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

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

The description provides explicit guidance on when to use the tool: when context is stale, task is done, or clearing sensitive data. It also mentions pairing with 'remember' and 'recall', but lacks explicit when-not-to-use or alternatives beyond these siblings.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral details: fetching the page, extracting title/description/key links, and emitting standard markdown. It also notes the output is a single text blob. No contradictions.

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

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

The description is front-loaded with the main purpose and consists of four informative sentences. It is concise without being overly terse, making it efficient for an AI agent to parse.

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

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

Given the tool has two parameters, no output schema, and annotations covering safety, the description provides sufficient context: it explains the output format, use cases, and parameter constraints. It is 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?

Schema coverage is 100%, so the description adds value beyond schema by providing examples for the 'url' parameter and specifying default/max for 'max_links'. This improves parameter understanding.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL. It specifies the actions (fetches, extracts, emits) and the output format, making the purpose unambiguous. While not explicitly differentiating from siblings, the unique functionality ensures distinctiveness.

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 lists concrete use cases (getting a site indexed, drafting llms.txt, auditing competitors). It provides clear context for when to use the tool. Although it does not mention when not to use or alternatives, the usage guidance is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return field details and parameter hint, but does not disclose additional behavioral traits beyond that.

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

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

Two concise sentences with no fluff; front-loaded with purpose and followed by usage guidance.

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 tool simplicity (one optional param, no output schema) and comprehensive annotations, the description fully covers purpose, usage, and return fields.

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

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

Schema covers 100% of the single parameter. Description implies default behavior ('active') and parameter offers 'include_inactive'; baseline of 3 applies.

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

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

Description clearly states 'List the caller's active subscriptions' and enumerates return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises using this tool 'to review what you're monitoring before adding more or to find an id to cancel', providing clear context but not explicitly naming alternatives.

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

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

The description reveals several behavioral traits not present in annotations: the return of a claim_token when filing without an account, the later use of that token to check status, a rate limit of 5 per identifier per day, and that it is free and does not count against tool-call quota. This goes well beyond the generic false annotation values.

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 each sentence earns its place, starting with the core purpose and then flowing through usage rules, examples, claim_token flow, and operational details. The structure is front-loaded and scannable, though the note about roadmap signaling is somewhat tangential.

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 tool with no output schema, the description is highly complete: it specifies content expectations, categorization, exclusions, the claim_token lifecycle, rate limits, and cost/quota impact. It covers both initial filing and later follow-up, leaving no major operational 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?

The input schema already has 100% coverage with per-parameter descriptions, so the baseline is 3. The description adds meaningful usage semantics for the claim_token parameter by showing the exact invocation pattern (pipeworx_feedback({claim_token:'pwfb_…'})) and explains that passing only the token reads the reply. It also guides context structure with examples, adding value beyond the schema.

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

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

The description opens with the specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist' and elaborates with concrete categories (bug, feature, data_gap, praise). It clearly distinguishes itself from sibling ask/discover tools by stating it is feedback for the Pipeworx connection itself.

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

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

It provides explicit when-to-use guidance for each feedback type and concrete when-not-to-use guidance: tools from a different MCP server should be filed with that server instead. It also offers a fallback rule ('Not sure? Pipeworx tool names are the ones this connection lists.') and clarifies the tool is free and rate-limited.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds context: data source (CF analytics-engine), no PII, caching (5min-1h), output structure (pack, tool, count). No contradictions.

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

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

The description is concise, front-loaded with purpose, then use cases, then technical details. Every sentence adds value with no redundancy.

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

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

Given one optional parameter, comprehensive annotations, and no output schema, the description fully covers input, output, caching, source, and privacy. No gaps identified.

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

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

Schema coverage is 100% with a well-described enum. Description reinforces window selection but does not add new meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states it returns top tools, top packs, and total call volume, with specific verb 'returns' and resource 'what other AI agents are calling on Pipeworx'. It distinguishes from siblings like ask_pipeworx and discover_tools by focusing on trending aggregation.

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

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

Three explicit use cases are listed, along with guidance on window selection ('shorter windows surface what's hot; longer windows show steady-state demand'). This provides clear context for when to use the tool.

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

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

The description explains the internal logic: monotonicity checks, partition_sum checks, Jaccard similarity, placeholder filtering, and fill check against CLOB depth. It covers edge cases like skipped_low_similarity and partition filter. Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, and the description reinforces these with concrete details. No contradiction.

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

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

The description is well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core functionality. However, it is somewhat verbose, with many details that could be condensed. Still, every sentence adds value, and the structure aids readability.

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

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

Despite no output schema, the description thoroughly explains the response fields (opportunities[], partition_check, etc.) and the logic behind them. It covers the main use cases, edge cases, and practical trade considerations. The complexity of the tool is well-addressed, making it complete for an agent to understand and use correctly.

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

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

Schema coverage is 100%, but the description adds significant context beyond the schema. It explains that 'event' accepts a slug or full URL, while 'topic' expects a seed question. It details the behavior for each parameter including the scanning logic and internal filters. The description provides practical usage advice that the schema alone does not.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and explains each. The verb 'Find' with specific resource 'arbitrage opportunities' and the mention of techniques make the purpose specific. It differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly states when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It provides guidance on what to pass and the type of input. It also mentions an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk', helping the agent choose correctly.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes beyond by disclosing caching behavior (1h KV-level, keyed on knobs), the '24h-move warning', and the logic behind each model family (e.g., 'Fed bets surface here, excluded from ranking'). No contradictions with annotations.

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

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

The description is long but well-structured with clear sections and enumerated lists. Every sentence adds value, explaining models, segments, knobs, and response structure. Slightly verbose but justified by the tool's complexity; no redundancy.

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

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

For a tool with 9 parameters and no output schema, the description comprehensively explains the response structure (by_segment segments, fed_candidates, _diagnostics) and why segments might be empty. It covers caching, model details, and tradeable-edge knobs. Fully addresses user needs for selecting and invoking the tool.

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

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

Schema coverage is 100%, and the description adds rich meaning beyond schema descriptions. For example, it explains that min_edge_pp is 'evaluated NET of slippage', min_liquidity applies to at least one top_leg for partition_overround, and min_partition_leg_kelly targets per-leg Kelly. Each parameter's practical use is clarified.

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: scanning Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings like polymarket_arbitrage by detailing the Pipeworx integration and the three specific segments (model-driven, structural arbitrage, concentrated longshot).

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 brands the tool for 'what should I bet on today' and explains the knobs (e.g., min_liquidity, max_spread_pp) for filtering tradeable edges. It lacks explicit when-not-to-use guidance or comparisons with sibling tools (e.g., polymarket_arbitrage), but the detailed usage context makes it adequate.

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

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

Annotations declare readOnlyHint and idempotentHint, which the description does not contradict. The description adds behavioral details (60-day snapshot TTL, decay from daily closes not intraday, response structure) that go beyond the annotations.

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

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

The description is long but structured with clear sections (RESPONSE, LIMITS). Every sentence provides useful information, though some redundancy could be trimmed. It remains compact for the amount of detail.

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

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

For a tool with two parameters and no output schema, the description fully covers the response format (tracked, expired, snapshot_dates), limits (60-day TTL), and source of data. It is comprehensive and leaves little ambiguity.

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 describes both parameters with 100% coverage. The description adds context: default values, clamp range for days, and meaning of 'window' (snapshot family). This adds modest value beyond the schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry from daily polymarket_edges snapshots', answering a specific question about edge longevity. This distinguishes it from sibling tools like 'polymarket_edges' which likely provide raw edge data.

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

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

The description implies the tool is used for checking edge existence and decay trends, but does not explicitly state when to use this versus alternatives like 'polymarket_edges' or 'polymarket_arbitrage'. No exclusions or contextual guidance are given.

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

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

Annotations (readOnlyHint, idempotentHint, non-destructive) already indicate safety. The description adds extensive behavioral details: it walks the order book ladder, returns fills, slippage, verdict, forced directional risk, and explains the dominant loss mode (partial basket fills converting arb to unhedged position). 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 thorough but lengthy and dense; it uses formatting (bold, line breaks) to organize content but could benefit from more structured separation. Front-loading of core purpose is effective. Given the tool's complexity, the length is justified, but it still feels 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 no output schema, the description fully explains all return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) for both modes. It covers edge cases like thin legs and forced directional risk. The description is complete for the tool's complexity.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond schema: it explains the dual interpretation of size_usd (buy spend vs sell target and basket notional), clarifies side defaults per mode, and provides context for each parameter. The description enriches 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 it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' with two explicit modes (single-market and basket). It specifically distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by advising to use this tool before acting on their signals or trades above $500.

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

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

The description explicitly tells when to use this tool ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and provides context about the modes (single-market vs basket) with clear conditions. It warns about thin books and partial basket fills, giving strong usage guidance.

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

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

Annotations already declare readOnly, openWorld, and idempotent, so the safety profile is covered. The description goes far beyond by disclosing matching methodology (keyword/word-overlap, not a shared resolution source), pairing_unverified, temporal_alignment null semantics, skipped counters, and the unmodeled Kalshi fee schedule. No contradiction with the read-only/destructive 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 front-loaded: purpose, modes, response, then safety fields. Bold labels and enumerations keep it navigable, and nearly every sentence carries a distinct warning or field explanation. Some concepts recur in both prose and code enumerations (e.g., temporal_mismatch), so it is more verbose than strictly necessary.

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

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

With no output schema, the description carries the full burden of explaining return structure and semantics, and it does: leg-level prices, top_spreads_pp, safety flags, compatibility codes, skipped counters, fees note, and interpretation of null alignment. For a 3-parameter, 0-required tool, nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful mode semantics — topic auto-fetches mapped events, explicit parameters override those mappings, and both modes run the identical token-overlap matcher. This is useful but not a dramatic departure from the schema's own descriptions, so slightly 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 opening states the exact object — a cross-venue spread between Kalshi and Polymarket for the same resolving question — so an agent immediately knows what the tool computes. The two modes and response summary further narrow the resource and scope without ambiguity, and this clearly differentiates it from single-venue Polymarket tools.

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

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

The 'TWO MODES' section explicitly tells when to use topic shortcuts vs explicit kalshi_event_ticker + polymarket_event_slug pairings. The fees note provides a clear when-not: spread_pp is gross, not a net tradeable edge. It does not explicitly name sibling alternatives such as polymarket_arbitrage or polymarket_edges, so it falls just short of a 5.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds behavioral details: behavior when key is omitted (list all), scoping by identifier, and the pairing with remember/forget. No contradiction.

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

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

The description is concise (three sentences) and front-loaded with the core action. Every sentence adds value without redundancy.

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

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

The description covers tool purpose, usage modes, scoping, and related tools. While it doesn't describe return value format explicitly, the context is sufficient for a simple tool with no output schema.

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

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

Schema coverage is 100% for the single parameter. The description adds semantic meaning beyond the schema: clarifies the effect of omitting the key (list all keys) versus providing it (retrieve single value).

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 with specific verbs ('retrieve', 'list') and resource ('saved values'). It distinguishes from siblings by mentioning 'remember' and 'forget' and explains the two modes (single key retrieval vs listing all keys).

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 good usage context: looking up prior context like ticker, address, notes. It mentions scoping and pairing with remember/forget. It lacks explicit when-not-to-use or alternatives, but the context is clear enough.

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

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

Description contradicts annotations: readOnlyHint=true implies no state modification, but description says mark_read:true flags events as read, modifying state. This is a serious inconsistency, so score 1 per rubric.

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?

Efficiently structured: first sentence states purpose, then return details, filtering options, mark_read behavior, and alternative access. Every sentence adds value with 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?

Despite no output schema, description details return fields (source, citation_uri, raw payload) and covers all five optional parameters' usage. Also mentions alternative access point, making it sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. Description adds extra meaning beyond schema with an example (type 'sec_8k') and explains the effect of mark_read on subsequent calls, justifying a 4.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying the verb and resource. It distinguishes from siblings like list_subscriptions or subscribe/unsubscribe by focusing on alerts, not subscription management.

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

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

Provides explicit guidance on filtering by type and ISO timestamp, explains the mark_read parameter for selective consumption, and mentions polling suitability and an alternative direct URL for scripts/dashboards, which helps the agent decide when to use this tool.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: parallel fan-out to multiple sources, fallback logic, soft-fail for patents, and return structure (changes[] grouped by source, total_changes, citation URIs). No contradictions with annotations.

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

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

The description is a single dense paragraph but every sentence adds value. It could benefit from more structure (e.g., bullet points) but is not excessively long and front-loads the purpose. Slight deduction for lack of formatting.

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 moderate complexity, no output schema, and excellent annotation coverage, the description is highly complete. It specifies input parameter meanings, sources, fallback, return structure, and sibling differentiation. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining the 'since' parameter accepts ISO dates or relative shorthand with examples, clarifies 'value' accepts ticker or CIK, and reinforces that 'type' is currently only 'company'. This extra context justifies a 4.

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

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

The description clearly states the tool returns a change feed for a company, including recent filings, news, and patents. It distinguishes from the sibling entity_profile tool by specifying that recent_changes is for dynamic changes over a window, while entity_profile is for static profiles.

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 query examples ('What's new with X', 'latest on Y') and explicitly tells when to use entity_profile instead. It also explains fallback behavior (GDELT→GNews) and the soft-fail for patents.

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

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

Description adds value beyond annotations: explains key-value storage, scoping by identifier, and session persistence details. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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, no wasted words. Purpose front-loaded, then usage, then behavior. Efficient and clear.

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

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

Given two required parameters with full schema coverage and no output schema, description fully covers purpose, usage, storage behavior, and interaction with sibling tools. No gaps.

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

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

Input schema provides 100% coverage with descriptions for key and value. Description adds examples and context but does not enhance parameter semantics beyond schema; baseline score appropriate.

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

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

Clearly states the tool saves data for reuse across conversations/sessions, with specific verb 'save' and resource 'data'. Distinguishes from siblings recall and forget by naming them and explaining the pairing.

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?

Specifies when to use: when discovering something worth carrying forward. Provides context on persistence (24 hours for anonymous) and mentions complementary tools. Lacks explicit 'when not to use' but still strong 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, the description discloses substantial behavior: internal cascading through multiple lookup endpoints, graceful degradation when LEI/FIGI sources are unavailable, explicit unresolved fields, ambiguous match handling via figi_candidates, and source labelling of identifiers. No contradiction with readOnly/idempotent annotations exists.

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

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

The description is dense and heavily front-loaded with examples and the primary usage directive. Every clause adds meaningful edge-case or behavior information, though the long single-block structure with many parentheticals reduces readability slightly.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly: CIK, ticker, company_name, LEI, ownership, FIGI, figi_candidates, unresolved, RxCUI, ingredient, brand, and citation. It also covers multi-source behavior, edge cases, and failure modes, making it fully actionable.

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 fully, so the baseline is 3. The description adds significant value beyond the schema by explaining what each type returns, expanding accepted company inputs to include ISIN, describing the ambiguous-name behavior, and clarifying the entity-name-only requirement for value.

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 precise verb and resource: resolving user-spoken names into canonical/official identifiers required by other tools. It clearly differentiates this from siblings by framing it as the identity lookup step and enumerating the two entity types and identifier sources.

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

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

The description gives an explicit trigger: "Use FIRST whenever you have a name but need an ID," supported by many natural-language query examples. It does not name specific alternative tools or provide explicit when-not-to-use exclusions, 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?

Description adds behavioral context beyond annotations: it reveals the tool calls ai_visibility_check internally per entity, aggregates results into a ranked list with score/confidence/signal density. No contradiction with readOnly/ idempotent hints.

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

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

Three efficient sentences: function, mechanism, use case + output. Front-loaded and no wasted words.

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

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

Even without output schema, the description specifies return fields (ranked list, score, confidence, signal density). Parameters fully explained. Annotations cover safety and idempotence. Complete for a tool with moderate complexity.

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

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

Schema coverage is 100%, baseline 3. Description adds significant value: explains 'entities' first entry is subject, 'context' applied to all probes, 'models' support with API key requirement. This enriches schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using strong verbs like 'probes', 'ranks', 'surfaces'. It distinguishes itself from sibling 'ai_visibility_check' by emphasizing multi-entity comparison.

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

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

Explicit use case 'competitive AI-marketing audits' and an example question. Implicitly contrasts with single-entity check (ai_visibility_check), but does not explicitly state when not to use (e.g., for single entity only).

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. Description adds behavioral details: composite one-call, fans out across APIs, partial failures with timing (bundlephobia can take 5-30s), and graceful degradation (sources_failed lists timeouts). Return structure is also described.

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

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

Description is a single paragraph but front-loads the purpose and APIs. Each sentence serves a purpose, but it could be slightly more structured with bullet points for returns. Efficient overall, earning a 4.

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

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

Given complexity (external APIs, complex return), no output schema, the description nearly covers everything: return fields, ecosystem scope, partial failure behavior, timing, and sources. Combined with excellent annotations and full schema coverage, it is highly complete.

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

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

Schema coverage is 100% with both parameters described. Description adds minimal extra value, only confirming version defaults to latest. Baseline 3 is appropriate as the schema already provides clear 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 performs a composite check for adding an npm package, using deps.dev and bundlephobia. It specifies the verb 'scan' and resource 'dependency', and distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on npm package evaluation.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also provides when-not-to-use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives clear usage context and 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 goes well beyond annotations by detailing that passages carry character offsets and similarity scores, describing the embedding model (BGE-base-en), chunking method (500-char overlapping windows), and a hard character cap (200K) with truncation and flagging. These details provide rich behavioral context without contradicting any annotations.

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

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

The description is concise at about five sentences, with the core purpose front-loaded. Every sentence adds essential information—purpose, use case, technical details, and limits—without any redundant or superfluous 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?

Given no output schema, the description adequately explains return values (top-N passages with offsets and scores) and internal mechanics. It covers all necessary aspects for a tool with 3 parameters, though it could briefly mention behavior on empty results or edge cases.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing real-world example queries, specifying the exact character limit for 'text', and stating the default and range for 'limit' (1-20, default 5), which enhances understanding beyond the schema descriptions.

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record,' specifying the verb (search), resource (a fetched record), and distinguishing it from siblings by noting it is used when a record is too large for the prompt. It also pairs with a specific sibling tool (ask_pipeworx_grounded), further clarifying its unique role.

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

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

The description explicitly advises to use this tool when the record is too big for the prompt, saving context, and provides a pairing suggestion with ask_pipeworx_grounded. However, it does not explicitly state when not to use it or contrast with other search-like tools among the 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 show readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds that an OAuth account is required (not anonymous), returns a subscription ID, explains delivery channel behavior (feed always on, email/SMS optional with constraints), and mentions rate limits (10/day SMS cap). No contradictions with annotations.

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

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

The description is long but efficient, with front-loaded purpose and return value. Every sentence adds value, covering types, delivery, and prerequisites. Slightly dense but not wasteful.

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

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

Given the complexity (3 parameters, nested objects, enums, no output schema), the description is thorough. It explains all subscription types and their required/optional fields, all delivery channels with constraints, prerequisites, and what the tool returns (subscription ID). No gaps identified.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value: it provides concrete examples for each type's params object (e.g., {ticker:"AAPL", items?} for sec_8k), explains the delivery object fields in detail (including webhook signing secret and auto-disable after failures), and clarifies constraints like phone verification. This goes well beyond the schema description.

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

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

The description clearly states it creates a proactive monitoring subscription and returns the subscription ID. It lists specific subscription types (sec_8k, polymarket_edge, etc.) and delivery channels, which distinguishes it 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 detailed when-to-use guidance by enumerating supported types and their specific parameters, plus prerequisites (Pipeworx OAuth account, phone verification for SMS). It implies that anonymous or BYO users cannot persist subscriptions. However, it does not explicitly contrast with sibling tools like list_subscriptions or recent_alerts.

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

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

Annotations already mark the tool as read-only, idempotent, non-destructive. The description adds valuable behavioral details: it returns category-bucketed example questions with exact tool+argument shapes, and explains that omitting topic gives a cross-category spread. No contradictions.

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

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

The description is moderately long but front-loaded with common queries. Every sentence adds value, though it could be slightly more concise. Still efficient.

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

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

Given the tool's simplicity (one optional param, no output schema), the description fully covers purpose, usage, and parameter semantics. It explains return values and provides complete guidance for the agent.

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

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

Schema coverage is 100% for the single optional parameter. The description adds meaning by listing specific topic values (finance, pharma, etc.) and explaining the effect of omitting the parameter.

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

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

The description clearly states the tool returns category-bucketed example questions for Pipeworx, with specific verb 'suggest questions' and resource 'what can I ask Pipeworx'. It distinguishes from siblings by positioning itself as the onboarding entry point.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', providing clear context. However, it doesn't explicitly exclude alternatives, though the sibling list makes it implicit.

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

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

Description adds significant behavioral context beyond annotations: deactivation (not deletion), ownership enforcement, and historical availability. No contradictions.

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

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

Two sentences with immediate action, ownership constraint, and outcome. Zero wasted words.

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

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

For a single-parameter, no-output-schema tool, description fully explains purpose, constraints, and side effects. Linked to sibling tool 'recent_alerts' for completeness.

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

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

Schema coverage is 100%, and description only reiterates that id is returned by subscribe. No additional semantic value beyond what schema provides.

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

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

Clear verb 'Cancel' and resource 'subscription' with specific scope. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement and behavioral outcome (deactivation). Does not explicitly state when not to use or list alternatives, but context is clear enough.

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

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

Even with strong annotations (readOnly, idempotent, openWorld), the description adds essential behavioral nuance: the critical distinction between 'could_not_verify' (verification did not happen, not evidence) and 'unsupported' (no source covers it). It also discloses the fallback pipeline and tolerance override semantics, going well 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 dense but well organized, front-loading trigger phrases and clearly separating the fast path, fallback, return values, and caller warnings. A few clauses are run-on, but every sentence adds substantive value, so it earns a strong score.

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 (verdicts, actual value, citation, reasoning) and the error/edge-case semantics of could_not_verify and unsupported. It also covers routing and the efficiency benefit, making it 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 coverage is 100%, so the baseline is 3, but the description adds meaningful parameter context: tolerance_pct overrides the wording-implied tolerance, is capped at 5, and can be set to 1–2 for hallucination detection. This guidance is not present in the schema alone.

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 natural-language claim verification against authoritative sources, with explicit trigger phrases and a specific verb-resource pairing. It distinguishes itself from sibling research tools by focusing on confirming/refuting factual claims and returning verdict categories.

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

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

It explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also separates company-financial claims from other claims and describes the routing. It does not name alternative sibling tools, but the context and fallback behavior give clear usage guidance.

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