Airtable

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

The description matches the annotations (readOnlyHint=false indicates write operation) and adds that it returns the created record ID and full data. However, it does not elaborate on idempotency (despite idempotentHint=true) or potential side effects, adding limited value beyond annotations.

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

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

The description consists of two concise sentences that succinctly state the tool's purpose and output. No redundant or irrelevant 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 the tool's simplicity (create record) and presence of output schema and annotations, the description covers the essential behavior and return value. It could optionally mention error handling or authentication details, but current completeness is adequate.

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 description coverage is 100%, so the schema already documents all parameters. The description only generically mentions 'specified field values' without adding syntax, format, or usage tips 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 explicitly states the tool adds a new record to an Airtable table with specified field values, clearly distinguishing it from sibling tools like airtable_get_record (read) and airtable_list_records (list).

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

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

The description implies usage when creating a new record but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It lacks 'when-to-use' or 'alternatives' context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description adds minimal extra transparency. It mentions 'all tables, field names, field types, and configurations', which is slightly more detail but not essential. No additional behavioral context like rate limits or authentication nuances is added.

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, followed by usage guidance. Every sentence adds value, no filler.

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

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

Given the output schema exists, the description need not explain return values. It sufficiently covers the tool's purpose, usage context, and output nature. All necessary information is present for an agent to use this 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?

Input schema has 100% coverage with descriptions for both baseId and _apiKey. The description does not add any further meaning to the parameters beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Get the structure of an Airtable base—all tables, field names, field types, and configurations', using a specific verb and resource. It effectively distinguishes from sibling tools like airtable_list_bases and airtable_get_record.

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 second sentence 'Use first to understand available data before querying or creating records' provides explicit guidance on when to use this tool as a preliminary step. It does not mention when not to use, but the advice is clear and useful.

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 nature. The description adds useful detail about return values (all field values and metadata like timestamps), which goes beyond the annotations without contradicting them.

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

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

Two sentences that are front-loaded with the action and inputs, followed by output details. No redundant information or unnecessary words.

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

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

Given an output schema exists, the description appropriately focuses on the tool's purpose and key inputs. It covers the essential aspects (base, table, record ID, returns fields and metadata) without missing critical details. Could mention error handling but not required.

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

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

Schema description coverage is 100%, so the description adds minimal new information beyond the schema. It mentions the record ID format (recXXXXXXXXXXXX) but does not explain other parameters. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Fetch', the resource 'a single Airtable record', and specifies the key identifiers (record ID, base, table). It distinguishes from siblings like airtable_list_records (which retrieves multiple records) and airtable_create_record.

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 usage when you have a specific record ID, but does not explicitly state when to use this tool versus alternatives (e.g., listing records with airtable_list_records). No direct comparison or exclusions are provided.

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

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

Annotations already indicate readOnly and idempotent. The description adds that the token must be provided and the output includes base IDs, names, and workspace info, which is useful context beyond annotations.

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

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

Two sentences that efficiently convey action, condition, output, and purpose. No superfluous words. Front-loaded with essential information.

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

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

For a simple list tool with rich annotations and a single parameter, the description provides all necessary context: what it does, what it returns, and why to use it. An output schema exists, so return values are detailed separately.

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

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

Schema coverage is 100% with one parameter. The description mentions '_apiKey' as token but adds no additional meaning beyond the schema description ('Airtable personal access token'). Baseline 3 is appropriate.

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

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

The description clearly states it lists all accessible Airtable bases, with verb 'list' and resource 'bases'. It distinguishes from sibling tools by explaining the output (IDs, names, workspace info) is used to discover baseId values needed by other Airtable tools.

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

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

The description explicitly states the use case: 'discover baseId values needed by other airtable tools', implying it's a prerequisite. It does not mention when not to use or alternative tools, but among siblings it's the only base-listing tool, so guidance is sufficient.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds value by specifying what is returned (record IDs, field values, metadata), which clarifies the output 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 a single, front-loaded sentence that is 20 words. Every part is informative: the action, the resource, the optional filtering, and the return content. No fluff.

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

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

Given that the tool has a read-only annotation, a full input schema with descriptions, and an output schema (not shown but present), the description completes the picture by summarizing the action and return. No additional context is necessary.

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

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

The input schema has 100% coverage with descriptions for all parameters. The description goes beyond the schema by providing an example usage of filterByFormula, which adds practical context. For a schema with full coverage, this is 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 description clearly states the verb 'Fetch', the resource 'records from an Airtable table', and the optional filtering capability. It distinguishes itself from siblings like airtable_create_record (write) and airtable_get_record (single record) by being a list operation.

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

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

The description provides clear context on when to use the tool (fetching records with optional formula filtering) and gives a concrete example. It does not explicitly state when not to use or list alternatives, but the context is sufficient for an agent.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: default model is free (Workers AI), Anthropic requires a BYO key and direct payment, and _apiKey is passed straight through. This informs the agent about cost and dependency.

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 action, then explains optional parameters and use cases. Every sentence adds value: defines output, explains default vs paid, and gives examples. 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?

The tool has 4 parameters (high schema coverage) and no output schema. The description explicitly states the return format: 'per-model {score, confidence, signals, raw_response} + a combined view.' This is sufficient for an agent to understand what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining 'entity' as brand/product/topic, 'models' as list with supported values and default, '_apiKey' as optional with condition, and 'context' for disambiguation. This adds value without repeating 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 uses specific verbs and resources: 'probe one or more LLMs for what they know about a business/brand/product/topic and score visibility (0-100) per model.' It clearly distinguishes this tool from siblings like compare_entities or scan_competitor_ai_presence by focusing on AI visibility scoring.

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

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

The description provides clear context for usage: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the _apiKey parameter. However, it does not explicitly state when not to use this tool or mention alternatives among siblings.

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

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

Behavior is described clearly: the tool routes questions to appropriate sub-tools, fills arguments, returns structured answers, and provides stable citation URIs. Since the annotations already show readOnly/idempotent/noDestructive, the description adds useful operational detail that the annotations alone do not express, exactly as needed.

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

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

The description is front-loaded and every main idea has a clear purpose. It is, however, slightly long due to multiple example queries that partially repeat the intent list. Even so, it remains well structured and does not waste the reader's attention.

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 router with no output schema, the description covers when to call it, what it does internally, and what the response looks like (structured answer with citations). The annotations cover safety and side behavior, and the description is complete enough for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, with all parameters being aliases for the same natural-language query and fully documented in the schema. The description does not add extra value here beyond that baseline, so 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 states a specific, broad function: route factual questions across a network of 5,596 tools from 1,465 verified sources and return structured answers with citations. It goes beyond the name and conveys a distinct aggregator/search role, making it easy to tell apart from more specialized tools.

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

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

The description gives strong usage rules: prefer over web search, use for any factual question about real-world entities, trigger phrases like 'what is' or 'look up', concrete examples, and a decisive default: start here unless a specialized sibling is clearly a better fit. This provides explicit when-to-use guidance without requiring the agent to infer it.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds valuable context about the tool being a live experimental edge, that routing improvements may be toggled on/off, and that no candidate is active right now. This goes beyond the structured fields in a useful way.

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 'beta version of ask_pipeworx' and quickly confirms no candidate is active. It is mostly efficient, though phrases like 'same 5,596 tools, same arguments, same response shape' and 'this IS a full working router' 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?

Given the tool is a beta wrapper over ask_pipeworx, the description adequately covers behavior by referencing the same tools, arguments, and response shape. It wisely points to a well-known sibling rather than repeating the entire stable router contract.

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 six parameters, all aliases of the required 'question' parameter. The description adds no parameter-specific guidance, but with the schema carrying the full load, a mid score is appropriate.

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

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

The description clearly identifies this as the beta version of a universal router with the same 5,596 tools and arguments as ask_pipeworx. It explicitly distinguishes the tool from its stable sibling and the grounded variant by pointing to the experimental routing/candidate-improvement nature.

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

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

The description states when to use it—'Use it exactly like ask_pipeworx when you want the newest routing'—and notes that with no active candidate it currently matches ask_pipeworx. It implies the stable router is the alternative but does not give a hard when-not-to-use instruction.

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 the readOnly/openWorld/idempotent annotations by detailing the success response structure, the refusal reason enum, and the behavioral constraint of extracting answers 'using ONLY what the tool result contains.' It also discloses the extra LLM call cost, which annotations cannot convey.

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

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

Front-loaded and information-dense, with every sentence providing useful routing or behavior context. It is slightly longer than strictly necessary, but the length is justified by the complexity of explaining the refusal semantics and the cost tradeoff.

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

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

For a complex tool with no output schema, the description supplies both return shape and error/refusal semantics, and the routing logic. Combined with the 100% schema coverage and the non-destructive annotations, an agent has all necessary information to invoke 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 description coverage is 100% and all parameters are aliases of the same natural-language 'question' field. The description adds no param-specific meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with a concrete scope and a distinct behavior from its sibling ask_pipeworx. It states the specific verb ('extract') and resource ('tool result'), and differentiates by emphasizing evidence-based extraction and explicit refusals.

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 cases are given: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also states when NOT to use it: 'prefer ask_pipeworx for casual lookups,' effectively naming the alternative and the selection condition.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, confirming safe, non-destructive behavior. The description goes far beyond annotations, detailing edge cases: low-confidence resolutions short-circuit with status, closed/dead markets return status, wide-spread markets carry tradeability note, and cancellation rules. 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 very long (multiple paragraphs) and covers extensive detail. It is well-structured with sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.), but could be more concise. Some redundancy exists, e.g., the fan-out examples are repeated in different contexts.

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 response fields (result.market, result.analysis, result.evidence), resolver contract (market_match_confidence, alternatives), parent event extractor, news fields with fallback details, and safety mechanisms (short-circuit, blocking routes). All edge cases and user concerns are addressed.

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 meaning beyond the schema. It clarifies that 'market' can be a slug, URL, or question text; 'depth' (quick vs thorough) is explained with default; 'include_raw' includes size implications and when to use. The examples provide concrete usage context.

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 input types (slug, URL, question text) and outputs (evidence packet + comparison). The scope is well-defined, and the tool is distinct from siblings like polymarket_edges or polymarket_arbitrage.

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

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

Explicit when-to-use guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Examples of classifiers and fan-outs further clarify contexts. However, no explicit when-not-to-use or alternative tools are mentioned, though the description implicitly suggests its primary role.

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) are present, and the description adds substantial behavioral context: it's a single parallel call, returns paired data with citation URIs, and details data sources per entity type. 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 moderately concise, front-loaded with example queries. Every sentence contributes value, though it could be slightly tighter (e.g., the explanation of fiscal year handling is useful but verbose).

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

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

Given the tool's complexity (two entity types, multiple data sources), the description covers the key aspects: input constraints, data sources, sort behavior, and output format (paired data with URIs). Lacks details on response structure but sufficient for most agents.

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 meaning beyond schema by explaining the behavior of each type ('company' pulls financial data, 'drug' pulls FAERS counts) and giving concrete examples for values.

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

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

The description uses specific verbs like 'compare', 'side-by-side comparison', and lists example queries, clearly distinguishing it from sequential lookups. It identifies the resource (companies/drugs) and the scope (2-5 entities).

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries. However, it doesn't specify when NOT to use it (e.g., if only one entity needed).

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, and idempotent annotations, it discloses the parallel decomposition mechanism, the findings-packet structure, gaps[] behavior for unanswered facets, contradiction scanning, semantically selected excerpts, latency expectations, and the paid tier boundary. It also explicitly states that findings are never invented.

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 almost every sentence stores operational value and crucial account/tier/behavioral constraints are front-loaded. It could still be easier to scan with sectioned paragraphs or shorter sentences, so it is not a perfect max-conciseness 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?

There is no output schema, so the description fully carries the burden of explaining return values—and it does: findings packet, confidence, source, fetched_at, citations, gaps, contradictions, and latency. It also covers auth constraints, alternatives, and tool limitations well enough for correct selection and invocation.

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

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

The schema already covers both parameters, but the description adds real semantic value below the depth enum: quick as single-hop, standard as default with gap recovery and contradictions, thorough as six facets with an extra iterative hop. The question parameter is also described as natural language, with decomposition as the intended behavior. This exceeds the baseline for a fully schema-documented tool.

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

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

The description states a specific verb and resource: grounded multi-source research across Pipeworx's structured data sources that decomposes a question, routes to multiple tools, and returns a findings packet. It also explicitly distances itself from open-web search and from ask_pipeworx, so sibling confusion is minimal.

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

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

It gives explicit when-to-use guidance (broad or multi-part questions over structured data) and explicit when-not-to-use guidance (single lookups, breaking and colloquial current topics). It also names ask_pipeworx as the alternative and adds account/tier conditions for switching.

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=true, idempotent=true, destructive=false. The description adds valuable behavioral context: it returns top-N relevant tools with names, descriptions, full schemas, and curated examples, and notes that each result is ready to call without a second lookup. 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 paragraph but front-loads the purpose and key usage. It is dense yet clear, with no redundant sentences. Could be slightly more structured with bullet points, but it is well-written and efficient for its length.

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

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

Given no output schema, the description adequately describes the return value (names, descriptions, schemas with examples). It covers when to use, what domains it covers, and that results are callable directly. The long list of example domains adds completeness. The description is sufficient for a discovery tool with these context signals.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minor value by confirming that 'task', 'q', 'search', and 'description' are aliases for 'query', which the schema already indicates. The 'limit' parameter's default and max are also stated in the schema. No significant additional 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's purpose: 'Find tools by describing the data or task.' It specifies the action (find/browse/search/discover) and resource (tools). It also distinguishes from siblings by explicitly noting to call this FIRST when you need to see the option set, implying it is not for executing specific tasks like its siblings.

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

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

The description provides clear when-to-use scenarios: 'Use when you need to browse, search, look up, or discover what tools exist for: [list].' It also advises to 'Call this FIRST when you have many tools available and want to see the option set.' It does not explicitly state when not to use it, but the guidance is strong enough to infer exclusion criteria.

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

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

Annotations already declare read-only and non-destructive. The description adds valuable context: fans out across multiple sources, returns specific fields, includes caveat about patents sunsetting (soft-fails), and mentions fallback for news. 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?

Relatively long but well-structured, starting with example queries, then purpose, then details. Every sentence adds value. Could be slightly tighter, but complexity justifies length.

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

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

No output schema, so the description must explain returns. It covers all major return categories (CIK, filings, fundamentals, patents, news, LEI) with caveats. Lacks details on error handling, but complete for a profile tool.

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

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

Schema coverage is 100%, with descriptions for both parameters. The description reaffirms the name limitation and gives examples, but doesn't add new meaning beyond the 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?

The description clearly states it produces a full cross-source profile of a US public company, with specific examples like 'tell me about X' and 'company profile for Microsoft'. It distinguishes from siblings like resolve_entity and compare_entities.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view.' Also specifies when not to use: if only have a name, use resolve_entity first. Provides clear context.

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

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

Annotations provide destructiveHint=true and idempotentHint=true. The description adds context about why to delete (stale context, done tasks, sensitive data), which is beyond the annotations. No contradiction noted.

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

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

Two sentences with no waste. The first sentence states the core action, and the second provides usage context and sibling relationships. Front-loaded and efficient.

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

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

For a simple tool with one parameter and clear annotations, the description is complete enough. It covers purpose, usage, and relationships to remember/recall. No output schema exists, so no need to explain return values.

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 description for the 'key' parameter. The description does not add extra meaning beyond the schema's 'Memory key to delete', so baseline of 3 is appropriate.

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

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

The description clearly states the tool deletes a memory by key, using the verb 'Delete' and the resource 'memory'. It distinguishes from siblings by mentioning 'Pair with remember and recall', clarifying its role in the memory triad.

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 usage scenarios: when context is stale, task is done, or to clear sensitive data. Does not explicitly state when not to use, but the positive guidance is clear and sufficient for most cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint=true, and destructiveHint=false. The description adds valuable context: fetching the page, extracting title/description/links, emitting markdown format, and output placement. No contradictions. Could mention error handling or rate limits.

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

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

Three sentences: purpose, process, use cases. Front-loaded with main action, no unnecessary words. Each sentence serves a distinct role.

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 parameters, no output schema, and rich annotations, the description covers key aspects: what it generates, how it works, and output format. Could include caveat about URL accessibility or size limits, but sufficient for typical use.

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

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

Schema coverage is 100% with clear descriptions for both parameters (url, max_links). The description does not add parameter-level details beyond what schema provides, so baseline score of 3 is appropriate. Contextual framing (e.g., 'maximum number of link entries') adds minimal 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?

States specific verb 'generate', resource 'llms.txt file', and target audience 'AI crawlers (ChatGPT, Claude, Perplexity)'. Clearly differentiates from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on a specific file format generation.

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

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

Explicitly lists three concrete use cases: indexing client sites, drafting for own project, auditing competitors. Does not explicitly state when not to use or mention alternatives, but the context is clear and actionable.

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 safety (readOnly, idempotent). Description adds value by specifying return fields and caller scoping, beyond what annotations provide.

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

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

Two concise sentences with no wasted words, front-loaded with core action.

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

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

Given the simple tool (1 optional param, no output schema, strong annotations), description is fully complete: what, returns, when to use, and parameter behavior.

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

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

Schema coverage is 100% and the parameter description in schema is adequate. Description adds no new semantics beyond noting default behavior, so baseline 3.

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

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

Description clearly states it lists active subscriptions and enumerates returned fields. It distinguishes itself from siblings like subscribe/unsubscribe, though not explicitly naming them.

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

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

Description recommends using the tool to review monitoring before adding more or to find an id to cancel, providing clear usage context. It implicitly contrasts with subscribe/unsubscribe.

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

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

Annotations only provide basic hints (readOnly=false, etc.), so the description carries the burden. It discloses key behavioral traits: filing without an account returns a claim_token that can be used later to check resolution, the team reads digests daily, and the tool is rate-limited to 5 per identifier per day and free. These details go far beyond the annotations and help the agent set expectations about the tool's side effects and return behavior.

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

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

The description is moderately long but every sentence serves a distinct purpose: scope definition, use cases, exclusions, token mechanics, rate limits, and impact. It is front-loaded with the core purpose and then logically expands into guidelines and behavioral details. There is no redundancy or filler, making it an efficient and well-structured description.

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

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

Given the tool's moderate complexity (4 parameters, nested object, no required fields, no output schema), the description covers all necessary context: what to report, how to scope it, how to claim and check feedback, and operational constraints. It even addresses what happens without an account and how the token flow works. The absence of an output schema is compensated by explaining the claim_token mechanism, making the description sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The input schema already has 100% description coverage for all four parameters, so the baseline is 3. The description adds meaningful extra semantics: it provides a concrete usage example for claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructs the user on how to write the message ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This enriching context lifts the score above baseline, though it does not systematically elaborate on every 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates distinct feedback categories (bug, feature/data_gap, praise) and clearly differentiates this tool from siblings by stating it is ONLY for tools served by this Pipeworx connection, not for other MCP servers. This leaves no ambiguity about what the tool does.

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

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

The description explicitly states when to use the tool ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well') and when not to use it ('if the tool came from a different MCP server... file it with that server instead'). It even provides a disambiguation heuristic: 'Not sure? Pipeworx tool names are the ones this connection lists.' This is a textbook example of clear usage guidance with alternatives.

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

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

Annotations already provide safety hints (readOnly, idempotent, not destructive). Description adds significant detail: self-aggregating from analytics engine, no PII, cached 5min-1h, and what data is returned. This greatly exceeds annotation coverage.

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

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

Description is front-loaded with the core purpose, then lists use cases, then adds behavioral notes. Every sentence adds value with no repetition or fluff.

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

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

Given the tool's simplicity (1 optional param, no output schema, rich annotations), the description fully covers what an agent needs: what it returns, when to use it, caching behavior, and data source. Nothing is missing.

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

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

Schema has 100% coverage with enum descriptions. Description adds contextual meaning: shorter windows for 'hot right now', longer for 'steady-state demand'. This adds value beyond the schema's enum listing.

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 what the tool returns (top tools, top packs, call volume) and provides three specific use cases. No sibling tool duplicates this functionality, making the purpose distinct.

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 lists three scenarios for using the tool (discovering hot data, confirming canonical tool, aligning use case). Does not explicitly mention when not to use it, but the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent with a read-only analysis tool. Description adds rich behavioral details: monotonicity checks, partition filter, semantic anchor, fill check with live CLOB depth. No contradictions.

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

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

Description is verbose but well-structured: front-loaded with purpose, then mode details, then technical filters, response, and fill check. Every sentence adds value, though some redundancy exists (e.g., 'Cross-event mode catches...' repeats earlier point). Still, clarity benefits from thoroughness.

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 and two parameters, the description covers input modes, behavioral details, response structure, and trade execution criteria. References sibling for custom sizing. No gaps identified; agent has enough context to select and invoke correctly.

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

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

Schema coverage is 100% but description adds substantial meaning: explains event slug format with examples, topic as seed question, and details on modes. Goes well beyond baseline 3 by providing practical usage context and constraints.

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

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

Description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes three modes (no args, event, topic) with specific verbs and resources. No ambiguity with sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Explicit guidance: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. Also warns when not to trade (realizable_edge_pp ≤ 0) and references polymarket_fill_risk for custom sizing. Covers when to use and when not to use.

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

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

The description adds substantial behavioral context beyond annotations. It details model families, cache behavior (cached 1h), edge calculation (net of slippage), and output structure (by_segment, diagnostics). It describes the Fed signal limitation and knob effects. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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 verbose and contains multiple paragraphs of technical detail (model formulas, knob explanations). While informative, it lacks conciseness; an agent may need to parse dense text. Front-loading is present (first sentence states purpose), but subsequent details could be streamlined.

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 covers return structure (by_segment, diagnostics), cache behavior, and edge attributes (edge_pp_net, kelly_fraction, liquidity, spread, volume). It explains why Fed bets are excluded (unreliable signal) and how knobs affect results. This is comprehensive for a complex tool with 9 parameters.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. It explains the purpose of knobs (e.g., 'Tradeable-edge filter' for max_spread_pp and min_liquidity), provides example values (e.g., 5000 for min_liquidity), and clarifies interactions (e.g., min_partition_leg_kelly applies to partition arbs where min_kelly doesn't).

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

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

The description uses specific verbs ('scan', 'return') and resources ('Polymarket markets', 'opportunities where Pipeworx data disagrees with market price'). It clearly distinguishes from siblings by describing unique model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) not present in siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description explicitly states the tool is for discovering betting opportunities ('what should I bet on today') and provides context for when to use it (e.g., to avoid paging hundreds of markets). It implies exclusions (Fed bets are excluded from ranking due to unreliable signal) but does not explicitly mention alternatives. While clear, it lacks explicit when-not guidance.

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

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

Annotations indicate read-only and idempotent behavior, which the description consistently supports. The description adds significant behavioral details: data comes from daily snapshots, gaps occur when polymarket_edges doesn't run, decay is computed from daily closes, and limits like 60-day TTL. This exceeds annotation content.

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 but then becomes dense with response structure details. While informative, it could be more concise by separating response format into an output schema or a separate note. Currently, it reads as one long block, reducing scannability.

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

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

Given the absence of an output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and their semantics. It also covers limits (history depth, decay computation). This provides sufficient context for an agent to understand the tool's behavior and output.

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

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

Schema coverage is 100%, with both parameters described. The description adds some context (defaults, valid values for window) but does not provide substantial meaning beyond the schema. Baseline is 3 for full schema coverage.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific analytical question ('how long has this edge existed and is it shrinking?'), distinguishing it from sibling tools like 'polymarket_edges' (likely raw data) or 'polymarket_arbitrage' (specific strategy analysis).

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

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

The description implies when to use this tool (for analyzing edge persistence and decay trends) but does not explicitly state when not to use it or list alternative tools. It provides context about history depth and snapshot TTL, which helps set expectations. The purpose is well-defined, but clearer exclusion criteria would improve score.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safety. The description adds behavioral detail: it walks the order book ladder, returns fill quality metrics, and warns about directional risk from partial fills. 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 verbose but well-structured: it starts with the core requirement, then details each mode with return fields, and ends with usage guidance. Every sentence adds value, and the structure supports quick scanning. The length is justified by the tool's complexity.

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

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

With no output schema, the description must cover return values, and it does: it lists fields like top_of_book, vwap_fill_price, slippage_pp, verdict, etc., for both modes. It also explains the verdict categories and warns about thin legs and directional risk. An agent has enough context to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value: it explains the dual purpose of size_usd (buy spend vs sell proceeds for single-market; settlement notional for basket), clarifies the side default (auto for basket), and distinguishes market vs event parameters. This goes beyond the schema to explain behavior.

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 checks 'realizable-vs-theoretical edge against live CLOB order-book depth' and differentiates between single-market and basket modes. It explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, stating when to use this tool before them.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns about risks of partial basket fills, giving enough context for when to use. It does not explicitly list exclusions for small trades but implies a threshold.

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

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

Annotations indicate readOnlyHint and idempotentHint, which the description does not contradict. The description adds rich behavioral context: it explains safety fields (compatibility_warning, temporal_alignment, skipped counters), the meaning of top_spreads_pp, and when spreads are meaningless. This exceeds annotation coverage.

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

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

The description is informative but somewhat lengthy. It is well-structured: purpose first, then modes, then response details, then safety fields. Every sentence adds value, but a slight trimming could improve conciseness. Still above average.

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

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

Given the absence of an output schema, the description explains the response fields (leg-by-leg prices, top_spreads_pp, safety fields) sufficiently for an agent to interpret results. It covers edge cases (temporal alignment, mismatched bet shapes). However, a few specifics like the exact JSON structure are omitted, which could be inferred.

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 each parameter has a description. The topic parameter's enum values are explicitly listed in the description, and the override behavior of kalshi_event_ticker and polymarket_event_slug is clarified. Examples in schema complement the 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 specifies a concrete verb-resource pair ('cross-venue spread') and clearly distinguishes from sibling tools like polymarket_arbitrage by focusing on the Kalshi-Polymarket comparison. It explicitly states two modes and the goal of identifying price differences.

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

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

The description provides explicit when-to-use guidance (e.g., to find spreads, for macro topics or custom pairs) and when-not-to-use warnings (e.g., compatibility_warning cases, temporal misalignment). It even cautions that most pre-mapped topics are not tradeable, setting realistic expectations.

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. Description adds scoping details (by identifier), which is useful context beyond annotations.

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

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

Two sentences: first states action, second provides guidelines and pairing. 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?

Complete for a read tool with good annotations: explains return behavior, scoping, and relationship to siblings.

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

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

Schema covers 100% of parameters, but description adds clarity on omitting key to list all, enhancing understanding beyond schema.

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

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

Clearly states it retrieves a saved value or lists all keys, distinguishes from siblings remember and forget.

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

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

Explicitly describes when to use: recall previously stored context, with examples like ticker or notes, and mentions pairing with remember and forget.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds details: mark_read side-effect (flags events read), returned fields, polling suitability, and alternative endpoint. No contradictions. Adds value beyond annotations.

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

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

Three sentences, each essential: purpose and return fields, filtering, mark_read effect, alternative access. Front-loaded, 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?

Returns structure described, filtering and read-state behavior explained, alternative endpoint mentioned. Lacks description of unread_only parameter, but otherwise complete for a medium-complexity 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%; description adds context for type (example value), since (fired_at >=), and mark_read effect. However, limit and unread_only are not described beyond schema. Baseline 3 with minimal added 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?

Clearly states the tool pulls fired events from subscription feed, returns specific fields (source, citation_uri, raw event payload), and describes filtering options. Differentiates from sibling tools which cover Airtable, research, subscriptions, etc., none of which overlap with 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?

Provides clear context for usage: filter by type and/or since, manage read state with mark_read, polling is appropriate, alternative HTTP endpoint available. No explicit 'when not to use' guidance, but no direct sibling tools, so implicit usage is sufficient.

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

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

Discloses fan-out behavior to multiple sources, fallback logic for GDELT->GNews, soft-fail for USPTO, and return format with grouped changes and citation URIs, going beyond annotations.

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

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

Dense but efficient single paragraph front-loads purpose and examples; all sentences contribute value, though could be slightly restructured for easier scanning.

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?

Comprehensive for a complex tool without output schema; covers multiple data sources, error handling, and return structure, leaving no major gaps.

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

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

Schema descriptions are clear; description adds examples of relative shorthand for 'since' and explains sources, enhancing understanding beyond 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?

Description clearly states it provides a change feed for a company over a specified window, aggregating from multiple sources. Distinguishes from sibling tool 'entity_profile' by specifying when to use each.

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

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

Explicitly provides example queries showing when to use, and directs to 'entity_profile' for static profile, clarifying when NOT to use this tool.

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

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

Discloses key-value scoping, persistence details (auth vs anonymous), and idempotency hints. No contradiction with annotations; annotations only hint at idempotent and non-destructive, and description aligns.

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 concise sentences. First sentence states core purpose, second adds usage guidance, third provides behavioral detail. No wasted words.

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

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

Despite no output schema, the description fully explains what the tool does, how to use it, and its behavior. For a simple key-value store, this is complete.

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

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

Schema already covers both parameters fully (100% coverage). Description adds usage examples and naming conventions, providing extra value beyond schema descriptions.

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

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

The description uses specific verbs ('Save data') and resources ('across this conversation or across sessions') with concrete examples (ticker, address, preference). It clearly distinguishes from sibling tools recall and forget.

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

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

Explicitly states when to use ('discover something worth carrying forward') and pairs with recall/forget. Provides clear context for invocation.

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, so the description doesn't need to rehash safety. It adds valuable behavioral context beyond annotations: the cascading lookup behavior, cross-source identity spine, source-labelled identifiers, explicit listing of unresolved identifiers, graceful degradation of LEI/FIGI enrichment, and the internal multi-endpoint cascade. A slight deduction because it doesn't detail edge cases like ambiguous name matches or rate limits.

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

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

The description is dense but front-loaded with concrete user utterances and a clear directive ('Use FIRST'). It packs a lot of detail into structured sections (SUPPORTED TYPES, LEI/FIGI enrichment). However, it's somewhat long and could be tightened; the final sentence about replacing manual lookups is repeated conceptually earlier. Overall, it earns its length but isn't perfectly lean.

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 (multi-source resolution, two entity types, multiple identifiers, enrichment fallbacks) and the absence of an output schema, the description is remarkably complete. It explains what identifiers are returned, which sources establish them, how unresolved IDs are handled, acceptable input formats, and graceful degradation. The only minor gap is not describing the exact output shape, but the description provides enough detail for an agent to understand the tool's capabilities and limitations.

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% (type and value are both described in the schema), so baseline is 3. The description adds significant semantic meaning: it explains what each type returns (company resolves to CIK/ticker/LEI/FIGI; drug to RxCUI/ingredient/brand), clarifies value formats (ticker, CIK, ISIN, brand/generic names), and provides a concrete example (ISIN 'CH0038863350'). This compensates for the schema's brief descriptions, earning a 4 rather than a 3.

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

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

The description uses a specific verb ('resolve') with clearly defined resources (names to canonical identifiers) and enumerates supported entity types (company, drug) with specific identifier outputs (CIK, ticker, LEI, FIGI, RxCUI). It distinguishes itself from siblings like entity_profile and compare_entities by emphasizing it's the lookup step for raw names to IDs.

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

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

The description explicitly states when to use this tool: 'Use FIRST whenever you have a name but need an ID.' It contrasts with manual multi-step lookups ('replaces 2-3 manual lookups') and clarifies that other tools require these IDs as input. It also explains unsupported scenarios (e.g., how ISINs resolve to legal entities) and graceful degradation when downstream services fail.

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

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

The description adds behavioral context beyond annotations, explaining that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. It also mentions the need for an _apiKey if using the anthropic model. 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?

Three well-structured sentences: purpose, usage example, output description. Front-loaded with the core action and efficiently written without waste.

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

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

Given the complexity (4 params, no output schema), the description adequately covers the process and return fields. It could mention the entity count limit (2-8) but that is already in the schema parameter description. Overall sufficient for the tool's purpose.

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 process (probing, ranking) and output fields (score, confidence, signal density), and clarifying that the first entity is the subject.

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, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It uses a specific verb ('scan' + 'compare') and distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (more generic).

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question. However, it does not explicitly state when not to use the tool or directly compare to alternatives like compare_entities, though 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?

The description goes beyond annotations (readOnlyHint, etc.) by disclosing behavioral traits: it fans out to two services, returns specific fields, notes that bundlephobia's first measurement can take 5-30s, and mentions graceful degradation with partial failures. 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 appropriately sized and well-structured: it front-loads the main purpose, then details return values, ecosystem notes, and failure behavior. Every sentence provides necessary information without redundancy.

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

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

Despite lacking an output schema, the description fully lists return fields (summary block, advisories, links, alternative versions) and covers edge cases like partial failures and timeouts. It provides sufficient information for the agent to understand the tool's behavior and return format.

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 the schema by clarifying that version defaults to latest and scoped packages are accepted. This provides helpful context 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 states the tool's purpose: a composite check for adding an npm package, with specific verbs ('fans out', 'returns') and resources (deps.dev, bundlephobia). It distinguishes itself by focusing on npm ecosystem and combining multiple checks in one call, differentiating from other scanning 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?

Explicit guidance is given on when to use: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'.' It also provides a when-not-to-use example: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' clarifying alternatives for other ecosystems.

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 provide readOnlyHint, idempotentHint, etc. The description adds valuable behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. This goes beyond what annotations offer.

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 efficient sentences that are front-loaded with the core action. No wasted words—every sentence adds value (purpose, use case, technical details).

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

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

Despite no output schema, the description covers return format (top-N passages with character offsets and similarity scores) and technical constraints. With 3 params and no output schema, this is sufficiently complete for the 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. The description adds context beyond schema: examples for 'query', default value for 'limit', and max length for 'text'. This provides meaningful extra information.

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

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

The description clearly states 'Semantic search INSIDE a fetched record', using a specific verb and resource. It distinguishes from siblings like ask_pipeworx_grounded by explaining the pairing and different use case.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. Also provides a clear alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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 the idempotentHint=true annotation. 'Create a subscription' and 'Returns the new subscription id' imply each call creates a new resource, which is not idempotent. Annotations promise idempotency, creating confusion.

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 well-organized with front-loaded purpose, then requirements, types, and delivery details. Somewhat lengthy but justified by complexity; no wasted sentences.

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 covers return value, auth requirements, type-specific parameters, delivery channels with constraints, and idempotency contradiction aside, it provides all necessary context for a subscription creation 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 description goes beyond with concrete examples, structure, constraints (e.g., 10/day SMS cap), and additional details like webhook HMAC signing.

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 verb 'Create', the resource 'proactive monitoring subscription', and the return of a subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides clear context: requires Pipeworx OAuth account, lists supported types with examples, and mentions delivery options and constraints (phone verification, daily cap). Does not explicitly state when not to use or alternatives, but context is 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 already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the crucial detail that results are 'category-bucketed example questions... each with the exact tool + argument shape that answers it' and that they come from a live catalog of thousands of tools, enhancing understanding of the tool's dynamic behavior.

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

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

The description is a single paragraph that efficiently includes common user queries, purpose, output details, parameter usage, and advice. Every sentence adds value, and the structure front-loads the most important information about what the tool does and when to use it.

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 what it returns (category-bucketed example questions with tool + argument shape), how to use it (with or without topic), and its role as an onboarding entry point. No gaps remain for an agent to understand its function.

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

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

Schema coverage is 100% with one optional parameter described. The description adds the list of possible topic values ('finance, pharma, economics, real-estate, betting, weather, government, science, news') beyond the schema's generic description, and explains the behavior when omitted ('full spread'), providing significant added 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 clearly states the tool is an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It uses multiple user queries to signal its role and distinguishes itself from siblings like ask_pipeworx and entity_profile by being the first step for learning what Pipeworx can do.

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 first ('Use this FIRST when you do not yet know what Pipeworx can do for you') and how to call meta-tools. It also explains the optional topic parameter and the full spread without it, providing clear context for decision-making.

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 discloses soft-delete behavior ('deactivated not deleted') and that historical events remain available via 'recent_alerts', adding value beyond annotations. Ownership enforcement is also stated.

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

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

Two sentences with zero wasted words. Every sentence conveys essential information: action, ownership, id requirement, and behavioral outcome.

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 tool with no output schema and clear annotations, the description fully covers all necessary context: what, who (ownership), and effect (deactivation vs deletion).

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?

Only one parameter 'id' with full schema coverage. Description adds that the id is 'returned by subscribe', which provides useful context but does not significantly extend beyond the schema definition.

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

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

Description states 'Cancel a subscription by id' with a specific verb (cancel) and resource (subscription), clearly distinguishing it from siblings like 'subscribe' and 'list_subscriptions'. Ownership enforcement adds precise scope.

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

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

Ownership condition ('you can only cancel your own subscriptions') is clearly stated, but no explicit when-not-to-use or alternative tool references. The context is clear enough given sibling names.

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

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

Annotations already declare read-only, open-world, and non-destructive behavior, but the description adds significant disclosure: it explains the meaning of 'unsupported' (we looked, no source) and the critical warning that 'could_not_verify' means the check did not happen and carries verification_error{stage,detail}. This goes far beyond the annotations and helps callers interpret the tool's limitations.

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

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

The description is compact for its scope, front-loaded with trigger phrases and a clear use case. Every sentence serves a purpose: it covers triggers, scope, routing, return values, and two edge-case warnings, without redundancy. The organization is logical and 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?

Given the tool's complexity (two params, no output schema), the description fully covers what it does, when to use it, how it routes claims, what verdicts it returns, and what to do with ambiguous outcomes. It even explains how it replaces sequential calls, giving the agent a complete mental model.

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

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

Schema description coverage is 100%: both 'claim' and 'tolerance_pct' have detailed descriptions in the schema, including the default behavior and hallucination-detection use case. The tool description adds no extra parameter semantics beyond what is already structured.

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 concrete natural-language triggers ('Is it true that…', 'fact check', 'verify the claim that…') and a clear verb+resource: validate claims against authoritative sources. It distinguishes itself by describing a two-track pipeline (SEC EDGAR for financials, grounded pipeline for everything else) and notes it 'Replaces 4–6 sequential calls,' differentiating it from multi-step alternatives.

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 offers actionable guidance for the two claim types (company-financial vs. other) and warns that 'could_not_verify' should not be shown as evidence, preventing misuse.

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