Figma

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds clarity on default model (Workers AI Llama-3.3-70b, free), the BYO key requirement for Anthropic, and the return format (per-model + combined view). No contradictions with annotations. It doesn't discuss rate limits or potential costs, but the transparency is adequate.

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

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

The description is two sentences with no filler. The first sentence states the core purpose and outcome, the second adds key details (default model, BYO key, return format, usage scenarios). Every sentence earns its place.

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

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

Despite having no output schema, the description explicitly states the return structure (per-model fields + combined view). It covers all four parameters and their semantics. Given the tool's moderate complexity and the richness of annotations, the description is fully sufficient for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaningful context beyond the schema: defines 'entity' as brand/business/product/person/topic, clarifies model options and the _apiKey requirement, and explains the optional 'context' parameter for disambiguation. This adds value without redundancy.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility on a 0-100 scale. It uses specific verbs ('probe', 'score'), identifies the resource ('LLMs'), and distinguishes from sibling tools focused on general Q&A (ask_pipeworx) or research (deep_research).

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

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

The description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly state when not to use the tool, but the listed scenarios provide clear context. The absence of alternative recommendations keeps it from a perfect score.

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

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

Even though annotations already indicate read-only, idempotent, open-world, non-destructive behavior, the description adds meaningful execution context: it routes to one of 5,710 tools, automatically fills arguments, returns a structured answer with stable pipeworx:// citation URIs, works on every tier, and makes a single fast call. No annotation contradiction exists.

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

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

The description is dense but purposeful: it front-loads the key preference instruction, then lists domains, examples, and escalation paths. It is longer than minimal, but every sentence contributes to selection or invocation. The example list is helpful though slightly long.

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

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

With no output schema, the description still explains the return shape (structured answer with citation URIs) and gives enough context for correct use: trigger phrasing, source domains, alternatives, and examples. An agent can confidently select and invoke this tool without needing additional information.

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 parameter semantics are fully covered by the schema. The description repeats the natural-language question concept and provides examples, but it does not add extra meaning beyond the structured schema. 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 states a specific function: ask a natural-language question and receive a structured answer routed from thousands of verified sources. It clearly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point and naming when alternatives are preferable.

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

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

The description gives explicit when-to-use guidance: prefer over web search for authoritative/factual data, start here for most questions, and step up to ask_pipeworx_grounded or deep_research only for specific needs. It also covers breaking-news behavior and the 'what is', 'look up', 'find' trigger phrasing, making selection unambiguous.

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

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

The description goes beyond the readOnly/idempotent annotations by explaining the beta behavior: candidate routing improvements are only live when under test, none is currently active, and it currently matches ask_pipeworx exactly. The 'Falls back to nothing — this IS a full working router' note is useful behavioral disclosure.

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

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

Every sentence earns its place: beta identity, current candidate status, usage instruction, and fallback behavior. It is dense but not padded, and the core identity is front-loaded before the state 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?

For a tool with no output schema, the description compensates by referencing the same response shape as ask_pipeworx and explaining the current equivalence to the stable router. Combined with full schema coverage and read-only/idempotent annotations, an agent has enough context 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%, so the schema already documents the parameters. The description adds only that the tool uses 'same arguments' as ask_pipeworx, which does not materially expand on what the input schema provides.

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

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

The description defines ask_pipeworx_beta as a beta version of ask_pipeworx: an identical universal router with the same 5,710 tools, arguments, and response shape. This is specific and clearly distinguishes it from ask_pipeworx and ask_pipeworx_grounded by describing the experimental routing edge.

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

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

It gives an explicit trigger condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router to decide merges, but it stops short of stating when not to use it or listing alternative tools explicitly.

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 readOnly/openWorld/idempotent safety signals, and the description adds substantial behavioral context beyond them: the tool is hallucination-resistant, uses only tool-result content, returns an explicit refusal with enumerated refusal_reason values, and incurs an extra LLM call. This is exactly the kind of non-obvious behavior an agent needs to know. No contradiction with annotations exists.

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

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

Every sentence earns its place: mode definition, routing mechanics, success/refusal return shapes, use-cases, and cost-based sibling comparison. The most important differentiator is front-loaded in the first sentence, and the detailed return contract is compactly structured. Minor conceptual repetition around 'grounded'/'only what the tool result contains' is acceptable given the stakes.

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

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

For a tool with no output schema, the description fully compensates by documenting both the success payload (answer, evidence, confidence, source, fetched_at, refusal_reason:null) and the refusal payload with the full refusal_reason enum. It also covers routing scale, aliasing to ask_pipeworx, cost trade-offs, and appropriate use cases, leaving no critical gap for correct invocation or expectation-setting.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases of the single natural-language 'question' parameter. The description itself does not need to restate parameter syntax. It doesn't add much beyond the schema, which matches the baseline expectation when the schema carries the full parameter burden.

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, differentiated purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It then clarifies it uses the same routing as ask_pipeworx but diverges by extracting answers only from fetched tool results, which clearly distinguishes it from its sibling. The verb 'EXTRACTS' plus the explicit return/refusal contract makes the resource and behavior unmistakable.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples. It also names the alternative and the condition for preferring it: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This fully routes the agent between siblings with no inference required.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds considerable behavioral context far beyond annotations: it details fan-out logic per classifier, resolution confidence handling, parent event extraction, news fallback mechanisms, safety short-circuits for low-confidence and closed markets, illiquidity warnings, and resolution-rule risk. Contradictions with annotations are absent.

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

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

The description is lengthy but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and is front-loaded with the core purpose. While every sentence adds value, some details (like specific FRED series) could be deferred to a documentation page, making it slightly verbose for a tool 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 complexity (multiple classifiers, fan-out to diverse sources, resolution confidence, parent events, news fallbacks, resolution rules) and the lack of an output schema, the description provides exhaustive context. It covers all major behavioral aspects, edge cases, and response fields, ensuring an agent can use the tool correctly without guesswork.

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 three parameters. The tool description enriches parameter understanding by clarifying input format variations for 'market', explaining the trade-off for 'depth', and the effect of 'include_raw' on response size. Examples in the schema also aid interpretation.

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

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

The description starts with a clear verb+resource statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies accepted input formats (slug, URL, question text) and delivers a distinct output (evidence packet + comparison). This is further differentiated from sibling tools by providing specific use cases and classifier categories.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also covers many conditional paths (low-confidence matches, closed markets, wide spreads, resolution rules) that inform appropriate use. However, it does not explicitly mention when not to use or provide direct alternatives among sibling tools.

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

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

Annotations (readOnlyHint, openWorldHint, idempotent) indicate safe, non-destructive behavior. The description adds significant behavioral context: specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and that it replaces 8–15 sequential lookups. 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 reasonably concise given the detail needed. It front-loads common use cases and then explains data sourcing. A few minor redundancies (e.g., repeating 'largest/most/biggest' after sorting mention) but overall well-structured.

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

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

Despite no output schema, the description fully explains what data is returned for each entity type (financials for companies, adverse events/approvals/trials for drugs), sorting behavior, and citation URIs. The tool is well-defined for an AI agent to understand inputs and outputs.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description provides additional context (e.g., tickers/CIKs for company, names for drug, max 5 items), but this largely mirrors schema semantics. Baseline 3 is appropriate as the description adds marginal value beyond the schema.

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

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

The description specifies the tool's purpose: side-by-side comparison of 2–5 entities (companies or drugs). It lists common use cases ('compare X and Y', 'which is bigger', 'rank these companies') and explicitly distinguishes from sequential single-entity lookups, making it clear when this tool should be preferred over siblings like 'entity_profile'.

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

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

The description provides clear usage guidance: use for comparisons, head-to-head, ranking. It explicitly states 'ALWAYS PREFER over sequential single-pack lookups'. While it doesn't explicitly list when not to use (e.g., for single entities), the context implies that entity_profile is for single lookups. The guidance is adequate but could be more explicit about alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral context: parallel decomposition across 5,710 tools, never-invented gaps[], contradictions[], hop fields, resolvable citation_uri, semantic excerpting, latency envelopes, and the paid requirement for 'thorough'. No contradictions with annotations.

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

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

The description is long but well-organized: account gate, core function, routing guidance, depth calibration, output semantics, and latency all appear in a sensible order. However, the sentence 'If you are not signed in, use ask_pipeworx instead — it works on every tier' appears twice, and the alternative-tool guidance is partially repeated, adding minor redundancy.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: findings packet, verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field, and citation_uri. Authentication, depth behavior, latency, and exclusions are all covered, so an agent has everything needed 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%, but the description goes well beyond the schema by explaining the behavioral consequences of each depth value: quick = single iteration and mostly unfilled gaps, standard = gap-recovery plus contradictions[], thorough = paid and iterative lead-chasing. It also adds latency expectations and clarifies that the 'question' parameter can be broad and multi-part.

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

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

The description names a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1494 STRUCTURED data sources... in ONE call', and explicitly says this is NOT open-web search. It clearly differentiates itself from siblings like ask_pipeworx, ask_pipeworx_beta, and bet_research with concrete routing examples.

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?

Usage guidance is explicit and actionable: 'Best for broad/multi-part questions over structured data' with examples, plus explicit when-not cases: single lookup → ask_pipeworx, general/current/open-web → ask_pipeworx_beta or ask_pipeworx, crypto/prediction/bets → bet_research. It also specifies the account requirement and the fallback to ask_pipeworx when not signed in.

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

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

Description adds value beyond annotations by explaining return format (top-N tools with full input schemas, curated examples, ready to call directly). Annotations already declare readOnly and idempotent, but description enriches behavioral understanding.

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

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

Single paragraph, front-loaded with core purpose, covers key points without excessive verbosity. Could be slightly more structured but is effective.

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

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

Completeness is high given no output schema: description explains return value in detail including that each result is ready to call directly. Covers all relevant aspects for agent invocation.

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

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

Parameters are 100% described in schema, including aliases. Description mentions aliases but adds no new semantic meaning beyond schema. 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?

Description clearly states purpose: find tools by describing task. Lists specific domains (SEC filings, FDA, etc.) and distinguishes from siblings which are specific 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?

Explicitly says 'Use when you need to browse... discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear when-to-use guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: parallel fan-out across multiple sources, soft-fail for patents, and specific return fields. 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 fairly long but every sentence is informative. It is front-loaded with example queries. Could benefit from bullet points for return fields, but overall efficient and clear.

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

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

Despite no output schema, the description thoroughly explains all returned components (cik, filings with URIs, fundamentals sorted, patents soft-fail, news fallback, LEI). It covers error handling and prerequisites, making it complete for a 2-param tool.

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

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

Schema coverage is 100%, so baseline 3. The description adds nuance: names not supported (use resolve_entity), value can be ticker or zero-padded CIK, and type is currently only 'company'. This extra context justifies a 4.

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

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

The description clearly states it returns a full cross-source profile of a US public company, lists example queries like 'Tell me about X' and 'company profile for Microsoft', and details the output fields (cik, filings, fundamentals, patents, news, LEI). It distinguishes itself from siblings like resolve_entity.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also delegates to resolve_entity when only a name is given, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about sensitive data clearing and pairing with other tools, but does not cover edge cases like deleting a nonexistent key. 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 two sentences long, front-loaded with the action, and contains no unnecessary words. Every sentence adds value.

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

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

For a simple destructive tool with clear annotations and a single parameter, the description is fully complete: it states purpose, usage scenarios, and relationships to sibling tools. No output schema needed.

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

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

Schema coverage is 100% with the key parameter described as 'Memory key to delete'. The description does not add additional semantics beyond what the schema provides, resulting in a baseline score of 3.

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

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

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

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

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

The description provides clear when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also explicitly pairs with related tools remember and recall.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it fetches and extracts title/description/links, aligning with annotations and providing useful context about the extraction process.

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 covers purpose and output, second lists use cases. No fluff, front-loaded with core information, and every word serves a purpose.

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

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

Given only 2 parameters, no output schema, and no nested objects, the description sufficiently covers input, process, and output. It also includes practical usage scenarios, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds examples (e.g., specific landing page) and mentions default (25) and max (50) for max_links, enhancing understanding beyond the schema.

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

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

Description clearly states the tool generates a 'production-ready llms.txt file' for AI crawlers, specifying the process (fetches, extracts, emits) and output format. It distinguishes itself from siblings like deep_research or entity_profile by focusing on a specific web-standard file generation for AI indexing.

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 use cases: getting a client's site indexed, drafting llms.txt, or auditing competitor views. Does not explicitly state when not to use or provide alternatives, but the context is clear and covers common scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds context about the compact nature and returned fields but does not provide additional behavioral insights beyond what annotations convey. Since annotations are strong, the description's contribution is moderate.

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

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

The description is concise, consisting of two sentences. The first enumerates returned fields efficiently, and the second provides a clear use case. No redundant or extra information is present.

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

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

For a simple read-only tool with only two parameters and no output schema, the description fully explains what the tool returns (list of fields) and its intended use (understanding file structure). No additional information 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?

Schema coverage is 100%, and both parameters are well-described in the schema. The description mentions the file key and implicitly relates to depth by mentioning 'compact summary' and 'without fetching full node tree', but it does not explicitly clarify how the depth parameter affects the output or when to adjust it.

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

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

The description clearly identifies the tool's action (get a compact summary), specifies the resource (Figma design file by file key), and lists the exact fields returned (name, last modified, etc.). It also distinguishes from sibling tools like get_file_nodes by noting it avoids fetching the full node tree.

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 this tool ('to understand the structure... without fetching the full node tree'), implying it is appropriate for high-level overviews. However, it does not explicitly mention when not to use it or provide direct alternatives beyond the implicit contrast with full node tree retrieval.

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, and destructiveHint. The description adds the return format (map of node ids to URLs) but does not elaborate beyond that. No contradiction with annotations.

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

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

Two sentences with no extraneous information. The first sentence defines the core action, the second clarifies usage and output formats. 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 4-parameter tool with no output schema, the description explains the return type and format options. However, it could be more explicit about the map structure and the comma-separated format for node IDs (though captured in schema). Adequate 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 description coverage is 100%, so the schema already fully documents parameters. The description adds a brief mention of output formats (PNG, SVG, JPG) but does not provide meaningful additional semantics beyond what the schema offers.

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 renders images of specific Figma nodes and returns a map of node IDs to image URLs. It uses a specific verb ('Render') and resource ('images of specific nodes'), and the mention of 'visual previews' distinguishes it from sibling tools like get_file_nodes that retrieve node data.

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

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

The description says 'Use to get visual previews...', implying when to use, but does not explicitly exclude alternatives or name sibling tools. However, the context of the design file and the distinction from data retrieval tools is clear enough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the return format detail but no additional behavioral traits beyond annotations. The description adds some value but is not heavily burdened due to rich 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 specifies return format and typical usage. Every word earns its place; no wasted content. Highly concise and well-structured.

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

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

Given the tool's simplicity, good annotations, and full schema coverage, the description covers purpose, return format, and usage. No output schema exists, but the description outlines the return structure. Complete enough for effective use.

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

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

Schema coverage is 100% with parameter descriptions. The description adds no new semantic meaning beyond what's in schema; it simply reiterates 'by their node ids'. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves specific nodes from a Figma design file by ID, and specifies the return format (compact map of id to name/type). It distinguishes from siblings like get_file (whole file) or get_file_images.

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

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

The description advises using the tool to 'inspect particular frames, components, or layers,' implying use cases. It does not explicitly exclude alternatives or contrast with siblings, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description's job is lighter. The description adds value by listing the actual fields returned (id, email, handle, avatar). No behavioral details beyond the annotations are needed, and there is no contradiction.

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

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

Two efficient sentences: the first states the action and result, the second gives usage context. No unnecessary words; front-loaded with key 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?

Despite no output schema, the description lists the returned fields (id, email, handle, avatar). The tool is simple and has no parameters, so this covers what an agent needs to know. Complete for the given 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?

With 0 parameters, the baseline is 4. The input schema has no properties, so the description correctly adds no further parameter info. This is appropriate for a parameterless 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 clearly states the action 'Get the signed-in Figma user' and lists the specific fields returned (id, email, handle, avatar image URL). It also provides a use case: 'identify whose Figma account is connected.' This distinguishes it from siblings which are unrelated to user identity.

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

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

The description includes a clear usage context: 'Use to identify whose Figma account is connected.' It implicitly tells when to use this tool (when you need current user info) but does not explicitly state when not to use it or mention alternatives. Since it's a simple read with no parameters, the guidance 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 mark the tool as read-only, idempotent, non-destructive. Description adds value by listing returned fields (id, message, author handle, created time, resolved time). 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?

Two concise sentences with no wasted words. Each sentence serves a purpose: defining the action and stating return fields and usage.

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, well-annotated tool with one parameter, the description is complete. It specifies the resource, action, return fields, and usage context. No output schema needed given the explicit listing.

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 a clear description for file_key. The tool description does not add additional parameter information beyond what the schema provides, so baseline score 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?

Clearly states verb 'List' and resource 'comments on a Figma design file'. Distinguishes from sibling tools like get_file and get_file_nodes by targeting comments specifically.

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

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

Provides clear usage context: 'Use to review feedback and discussion on a design.' No explicit alternatives or when-not-to-use, but the sibling set lacks direct comment-focused 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 convey readOnly, idempotent, and non-destructive behavior. The description adds value by listing the returned fields and the scope (caller's subscriptions), which goes 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 two sentences, front-loaded with the purpose, and every part contributes meaning. No excessive wording.

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

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

Given the simple tool with one optional boolean parameter, rich annotations, and no output schema, the description fully covers the tool's functionality, use case, and 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 clear description of the single parameter. The description does not add any additional meaning beyond the schema, 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 explicitly states 'List the caller's active subscriptions' with a specific verb and resource, and it distinguishes itself from siblings like subscribe and unsubscribe by clarifying its role.

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

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

The description provides clear guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel,' which tells when to use the tool and relates to sibling tools.

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

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

Beyond annotations, description discloses claim_token workflow, rate-limiting (5/day), quota-free execution, and the team's daily digest reading. This is rich behavioral context that annotations do not provide, making the tool's side effects and constraints clear.

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?

Though lengthy, every sentence is information-dense and the description is front-loaded with the core purpose. No filler or redundancy; each clause serves a practical purpose for correct tool usage.

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

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

The description explains return behavior (claim_token and later status check), rate limits, and scope boundaries. Despite no output schema, an agent has sufficient context to execute and interpret results correctly.

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

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

Schema already covers 100% of parameters with descriptions, but the description adds extra meaning: claim_token should be passed alone, message should reference Pipeworx tools/packs and not user prompts, and context is optional. This elevates understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies categories (bug, feature/data_gap, praise) and explicitly limits scope to Pipeworx tools, distinguishing it from sibling research tools.

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

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

Provides explicit when-to-use (bug, feature/data_gap, praise) and when-not-to-use ('if the tool came from a different MCP server... file it with that server instead'). Also guides on identifying Pipeworx tools and formatting feedback appropriately.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds that data is derived from CF analytics-engine, no PII, cached 5min-1h. No contradictions, and the added behavioral details are valuable.

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

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

Four sentences, front-loaded with purpose, then use cases, then data details. No fluff, every sentence adds value.

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

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

Despite no output schema, description clarifies return structure (top tools, packs, volume), caching, and data source. For a simple 1-param optional tool, this is fully complete.

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

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

Schema coverage is 100% with enum values described. Description adds context on window trade-offs (shorter for hot, longer for steady-state). Adds meaning beyond the schema's basic enum 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?

Clearly states that the tool returns top tools, top packs, and total call volume on Pipeworx, with a specific verb-resource combo. Distinguishes from siblings like ask_pipeworx or discover_tools by focusing on trending usage data.

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

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

Provides three explicit use cases (discovering hot sources, confirming canonical tool, aligning use case with demand). Lacks explicit when-not-to-use or alternatives, but the use cases are specific enough for good 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, idempotent, non-destructive. Description adds rich behavioral context: response includes opportunities array, partition check details, fill check logic, Jaccard similarity filter, and placeholder filter. 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?

Thorough and well-structured, but slightly long. Front-loads core purpose and breaks down modes clearly. Every sentence adds value, but could be tightened slightly.

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

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

Given the tool's complexity (3 modes, multiple sub-checks, no output schema), the description is fully complete. Covers semantic anchor, partition filter, fill check, and references related tools.

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 good descriptions. The description adds nuance: event accepts slug or full URL, topic is a seed question, and explains each mode's behavior in detail, significantly enhancing understanding.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: 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.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant behavioral context: caching at KV level, model families, edge calculation details, slippage assumptions, diagnostic feedback. 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 front-loads the core purpose, but it is overly verbose with detailed model family explanations and response structure. Could be trimmed by ~30% without losing essential guidance for an AI agent.

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

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

Despite no output schema, the description thoroughly explains the return structure (by_segment, fed_candidates, diagnostics), all parameters are documented, and caching behavior is disclosed. It covers everything needed for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial meaning beyond schema for parameters like min_partition_leg_kelly, slippage_pp, and category_filter, explaining their interplay and use cases. Only a few parameters (e.g., limit) are not further enriched.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case ('what should I bet on today'). It distinguishes from siblings like polymarket_arbitrage by focusing on edge signals, not just 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?

The description implies usage for discovering betting opportunities but does not explicitly state when not to use this tool versus alternatives like polymarket_edge_tracker or polymarket_arbitrage. Usage is implied but lacks exclusions or comparative 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 declare readonly, idempotent, non-destructive. The description adds useful behavioral context: history bounded by 60-day TTL, decay from daily closes (not intraday), snapshot gaps when no scan occurred. This goes beyond annotations.

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

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

The description is relatively long but well-structured: purpose first, then output fields, then limitations. Every sentence adds value. It could be slightly more concise, but overall it is earned.

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 details the response structure (tracked, expired, snapshot_dates) and edge computation nuances. It also covers input, output, limitations, and data sources, making it fully informative.

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 restates parameter defaults and meaning but does not add new meaning beyond the schema descriptions. It is adequate but not exceptional.

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

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

The description clearly states the tool provides 'Edge persistence and decay telemetry' and answers a specific question about edge duration and trend. It uses specific verbs ('track', 'answers') and resource ('edge persistence/decay'). It distinguishes from sibling tool 'polymarket_edges' by focusing on time-series 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 by contrasting fresh vs old edges, but it does not explicitly state when not to use or mention alternative tools among siblings. Usage guidance is present but lacks exclusions or direct comparison.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive; the description adds rich behavioral details like ladder-walking logic, specific result fields (e.g., max_fillable_usd, thin_legs), and risk factors (forced_directional_risk). No contradiction with annotations.

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

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

The description is long but well-structured: it front-loads the overall purpose, then logically separates single-market and basket modes with clear formatting. Each sentence adds value, though some redundancy could be trimmed. It's not unnecessarily verbose given the complexity.

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

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

For a complex tool with two modes, no output schema, and no nested objects, the description is exceptionally complete: it explains the calculation logic, expected outputs, risk factors, and when to use it. The agent can fully understand the tool's behavior and invocation context.

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

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

Although schema description coverage is 100%, the description adds meaning beyond the schema: it explains that size_usd for basket is 'settlement notional — shares per leg, each paying $1 at resolution,' clarifies side auto-detection for baskets, and notes clamps (10–1,000,000). This enriches the bare schema definitions.

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

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

The description clearly defines the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' specifying two distinct modes (single-market and basket) and listing exact outputs like top_of_book, vwap_fill_price, and verdict. It differentiates from sibling tools by directly stating to use this before acting on polymarket_arbitrage or polymarket_edges signals.

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 the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also provides context on why theoretical overround may be uncapturable and warns about partial basket fills converting arb into directional risk.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond that: compatibility_warning and compatibility_codes behavior, skipped-pair categories, legacy of unclassified legs never being paired, temporal alignment, and the strong caveat that pre-mapped topics are often not tradeable. No contradiction with annotations.

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

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

The description is long but dense, with key concepts front-loaded: purpose, modes, response shape, safety fields, and caveats. Some sentences are overloaded and the inline code list is heavy, but virtually everything earns its place.

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

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

Given there is no output schema, the description carries full responsibility for explaining return values, and it does so well: leg-by-leg prices, top_spreads_pp, compatibility fields, skipped categories, and temporal alignment are all covered. It is sufficiently complete 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%, so the schema already documents all three parameters. The description meaningfully supplements this by explaining how topic maps to pre-fetched events, how explicit tickers/slugs override topic-mapped sides, and how the two modes interact. This goes beyond baseline but is not exhaustive in terms of edge-case parameter 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 computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, and it details two modes. It does not explicitly name a sibling alternative, so it slightly misses the highest bar for sibling differentiation, but the purpose is unambiguous.

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

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

The description explains when to use the pre-mapped topic mode versus explicit ticker/slug pairing, and warns that pre-mapped does not mean tradeable and compatibility fields should be read even when matched pairs exist. It lacks an explicit 'when not to use this tool' statement naming alternatives, so it is not a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds useful behavioral context: 'Scoped to your identifier' and explains behavior when key is omitted. 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?

Three concise sentences with no redundancy or wasted words. Front-loaded with the core action, then usage context, then scoping, then pairing. Every sentence earns its place.

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

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

No output schema exists, but the description mentions 'retrieve a value' and 'list all saved keys', which covers the basic return behavior. It also ties into the sibling tools. Could be improved by describing the output format (e.g., the value or an array of keys).

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 by explaining the effect of omitting the key (list all keys) and the purpose of the key (memory key to retrieve). It goes beyond the schema's basic description.

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

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

The description clearly states the verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It distinguishes from siblings 'remember' and 'forget' by naming them, making the tool's role in the triad explicit.

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

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

Provides explicit context for use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch'. Mentions scoping and pairing with remember/forget, but does not explicitly state when not to use it or alternatives among other siblings.

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

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

Annotations indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: returned fields, mark_read flagging behavior, and external access via URL. 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?

Four sentences, front-loaded with purpose, followed by return fields, filtering/state change, and external access. Every sentence adds value; no unnecessary words.

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

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

Given no output schema, the description explains return fields, filtering, and mark_read behavior. It covers core usage and mentions external access. However, it does not address pagination beyond limit (e.g., if a cursor is needed), but given the open world hint, this is acceptable.

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

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

Schema descriptions cover all 5 parameters. The description adds examples (type 'sec_8k'), clarifies the effect of mark_read, and mentions default limit (50) and range (1-200). This provides practical guidance beyond the schema.

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

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

The description clearly states the tool pulls fired events from a subscription feed, returning recent alerts with source, citation_uri, and raw payload. It distinguishes from sibling tools like list_subscriptions and subscribe by focusing on retrieving specific alert events.

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

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

The description explains how to filter by type and since timestamp, and how mark_read affects subsequent calls. It also mentions polling is fine and an alternative URL. However, it does not explicitly state when not to use or compare to other tools.

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

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

Discloses fan-out to multiple sources, fallback behavior (GDELT→GNews), soft-fail for USPTO, accepted date formats (ISO or relative), return format (structured changes with URIs). No contradiction with annotations (readOnlyHint, 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?

Well-structured and front-loaded with query examples. Slightly verbose but every sentence adds value; could be trimmed without losing key info.

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 explains return format (changes grouped by source, total_changes, URIs). Covers failure modes (rate-limiting, sunset API) and date handling, making it complete for a multi-source change feed 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 100% (baseline 3). Description adds practical usage examples for 'since' (e.g., '30d', '1m') and clarifies 'value' accepts ticker or CIK, enhancing beyond schema descriptions.

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

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

Description clearly states tool as a change feed for companies, enumerates data sources (SEC, GDELT/GNews, USPTO), and provides query examples. Explicitly distinguishes from sibling tool entity_profile.

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

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

Provides explicit when-to-use examples (e.g., 'What's new with X', 'latest on Y') and when-to-use-alternative directive for entity_profile. Also notes limitations like USPTO soft-fail and GDELT→GNews fallback.

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 important behavioral context beyond annotations: scoping by identifier, 24-hour retention for anonymous sessions, and persistent memory for authenticated users. Annotations already indicate idempotent and non-destructive, and description aligns. Minor gap: no mention of overwriting behavior on duplicate keys, but overall strong.

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

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

Four concise sentences, each meaningful. The core purpose is front-loaded, and every sentence adds value—usage guidance, examples, scope, retention, and pairing. 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?

For a simple 2-param tool with no output schema, the description is quite complete. It covers purpose, when to use, pairing, scoping, and retention. It does not mention error cases or return value, but those are minor given the simplicity.

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 param descriptions. The description reinforces key-value pair concept and gives typical key examples, adding value beyond the schema.

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

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

The description clearly states the tool saves data for reuse, with specific examples like 'resolved ticker' and 'user preference'. It distinguishes itself from sibling tools by referencing '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?

The description explicitly guides when to use the tool ('when you discover something worth carrying forward'), provides concrete examples, and mentions pairing with related tools (recall, forget). It also clarifies persistence behavior for different authentication states.

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 readOnlyHint and idempotentHint annotations, the description adds valuable behavioral context: graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), explicit handling of unresolved identifiers ('stated explicitly under `unresolved` rather than omitted'), and internal cascading lookups. No contradictions with annotations.

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

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

The description is long but well-structured, starting with relevant user queries and then detailing supported types, fallback behavior, and internal cascading. Almost every sentence earns its place by adding distinctive information. It is slightly dense and could benefit from bullet points, but there is no fluff.

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

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

For a tool with two parameters and no output schema, the description is remarkably complete. It explains what the tool returns (source-labeled identifiers, explicit unresolved list), covers both entity types, describes input variations, and positions the tool relative to other tools ('Use FIRST'). It also addresses edge cases like GLEIF/OpenFIGI unavailability.

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

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

Even though the schema provides 100% parameter descriptions, the tool description adds significant semantic depth: it specifies accepted input forms for company (ticker, CIK, ISIN, or name), explains the ISIN-to-LEI mapping and non-US issuer coverage, and clarifies drug inputs as brand or generic names. This goes well beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides specific trigger examples ('What's the ticker for…' / 'find the CIK for…') and lists supported entity types. The phrase 'Use FIRST whenever you have a name but need an ID' explicitly distinguishes it from sibling tools.

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

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

The description gives explicit when-to-use guidance with 'Use FIRST whenever you have a name but need an ID' and example user phrasings. However, it does not explicitly name alternative tools or state when not to use it (e.g., if the ID is already known), so it falls just short of a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld. The description adds process details: it probes each entity with ai_visibility_check, ranks, and surfaces results. No contradictions; provides useful behavioral context beyond annotations.

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

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

Three sentences with no wasted words. Front-loaded with the main action, followed by examples and return details. Every sentence earns its place.

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

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

Despite no output schema, the description summarizes the return structure (ranked list with score, confidence, signal density). It covers purpose, usage, parameters, and output. Lacks mention of potential size limits or error handling, but adequate for this tool's complexity.

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

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

Schema covers 100% of parameters with descriptions. The description adds value by explaining that the first entity in the array is treated as the 'subject' for narrative, which is not in the schema. This extra semantic enhances understanding.

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

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

The description uses specific verbs: 'Compare', 'Probes', 'ranks', 'surfaces', and identifies the resource as 'AI visibility across multiple entities'. It distinguishes from sibling tools by specifying the use of ai_visibility_check and the ranking/competitive comparison aspect.

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 a use case ('competitive AI-marketing audits') and provides an example question. It implicitly suggests using this tool over the sibling ai_visibility_check when comparing multiple entities, but does not explicitly mention when not to use it or list direct 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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral detail: fans out to external services, bundlephobia first measurement can take 5-30s, partial failures degrade gracefully with sources_failed reported. This enriches the agent's understanding beyond annotations.

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

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

The description is a single, well-structured paragraph. It front-loads the purpose, then covers use cases, limitations, and return value. While slightly verbose, every sentence earns its place. Minor improvement could be breaking into bullet points for return structure, but current form is still highly readable.

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

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

Given the tool's complexity (composite check, multiple services, partial failures), the description is remarkably complete. Without an output schema, it details the return structure explicitly. It also covers timing, failure modes, and ecosystem scope. No external documentation is needed for basic understanding.

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

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

Schema coverage is 100% with clear descriptions for both parameters (package name with scoped packages, version with default). The description adds no additional meaning beyond what the schema already provides.

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

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

The description explicitly states it's a composite check for npm packages, clearly distinguishing its purpose from sibling tools. It uses specific verbs ('check', 'fans out') and resources ('deps.dev', 'bundlephobia'). No sibling tool overlaps with this unique functionality.

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 ('is X safe / popular / small', 'what does adding lodash cost me'), notes ecosystem limitations (NPM only v1), and mentions alternative paths (PyPI/Maven etc. via deps.dev:version directly). It also warns about partial failures and timing.

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 the embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), and a cap of 200K chars with truncation and flagging. Adds significant context beyond the annotations, which are already non-destructive and idempotent.

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?

A single paragraph of about 100 words, front-loaded with the core action, then providing usage guidance, technical details, and a pairing suggestion. Every sentence earns its place with no redundancy.

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

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

Given no output schema, the description adequately explains the return format (top-N passages, character offsets, similarity scores). Also covers constraints (200K char cap) and integration with a sibling tool. No missing critical information.

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 value by explaining the character cap on the 'text' parameter and hinting at the output structure (passages with offsets and similarity scores). Does not duplicate 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?

Clearly states the tool performs semantic search inside a fetched record, using a natural-language query to return relevant passages. Differentiates from sibling tools like ask_pipeworx_grounded by specifying the input (text already pulled) and output (passages with offsets).

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

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

Explicitly tells when to use: when the record is too large for the prompt. Mentions pairing with ask_pipeworx_grounded for a grounded workflow. Does not explicitly state when not to use, but the context is clear.

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

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

The description fully discloses behavioral traits beyond annotations. It specifies that the tool requires authentication (OAuth), that subscriptions persist, and details type-specific parameters. It also explains delivery channel behavior (always-on feed, optional email/SMS/webhook with constraints like SMS cap and webhook auto-disable). No contradiction with annotations (idempotentHint=true is reasonable for a create-with-upsert pattern described).

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

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

The description is well-structured, with the primary purpose front-loaded. Each section (requirements, types, delivery) is clearly separated. While slightly verbose, every sentence adds necessary context. A minor reduction could be achieved by combining some type examples, but overall it is efficient.

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

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

Given the moderate complexity (3 parameters, nested objects, multiple types), the description covers all essential aspects: purpose, authentication constraints, type-specific parameters, delivery options with constraints, return value (subscription id), and operational notes (webhook recovery). No output schema exists, but the return value is clearly stated. The tool is fully understandable without external references.

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

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

The description adds extensive context beyond the input schema. For each subscription type, it provides concrete examples and explanations of parameters (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}'). It also details nested delivery object properties (e.g., webhook signing, email validation, SMS verification). Since schema coverage is 100%, the description significantly enriches parameter understanding.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly states the action (subscribe), the resource (alerts), and the return value. It distinguishes the tool from siblings like list_subscriptions and unsubscribe by its creation role.

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

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

The description explains the requirement for a Pipeworx OAuth account, implying that anonymous or BYO users should not use this tool. It also details delivery channel constraints (e.g., SMS cap, phone verification), which guide appropriate usage. However, it does not explicitly contrast with list_subscriptions or unsubscribe, leaving some inference to the 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context about return structure (category-bucketed questions with tool+argument shapes) and notes it's a read-only discovery tool. 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 fairly long but front-loaded with purpose and usage. Every sentence adds value (purpose, categories, argument hint, usage directive). Could trim some parenthetical examples, but overall well-structured.

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

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

Despite no output schema, the description fully explains what is returned (example questions with tool calls) and covers both invocation patterns (no args vs. topic). For a discovery tool with one simple parameter and comprehensive annotations, 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 coverage is 100% (one parameter 'topic' described in schema). The description adds meaning by listing specific values ('finance', 'pharma', etc.) and explaining behavior when omitted ('full spread') vs. provided ('focus'). This goes beyond basic 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 ('returns', 'draws from') and clearly identifies the resource ('onboarding entry point'). It distinguishes from siblings like 'ask_pipeworx' and 'discover_tools' by framing it as the initial exploration tool. The title 'What Can I Ask Pipeworx?' further reinforces purpose.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also provides guidance on optional 'topic' parameter to focus queries. This gives clear when-to-use and how-to-customize instructions.

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 non-read-only, idempotent, and non-destructive. Description adds ownership enforcement and clarifies that the row is deactivated not deleted, enhancing transparency beyond annotations.

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

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

Two concise sentences that front-load the action and efficiently add critical behavioral details without redundancy.

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

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

For a simple single-parameter tool with no output schema, the description fully covers purpose, restrictions, effect, and relationship to other tools like recent_alerts.

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 description for 'id'. The description adds that id is 'returned by subscribe', which provides helpful context beyond schema.

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

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

Clearly states the action ('cancel a subscription by id'), specifies the resource (subscription), and distinguishes from siblings like 'subscribe' and 'list_subscriptions' by detailing ownership enforcement and deactivation behavior.

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

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

Explicitly notes ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use. Does not list alternatives or when-not cases, but the context is sufficient.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral context: distinct verdict types (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify), the meaning of could_not_verify with verification_error structure, the distinction between unsupported and could_not_verify, and the requirement not to treat could_not_verify as evidence. No contradiction with annotations.

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

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

The description is long but dense and well-structured: trigger phrases, use case, routing, return values, and caller warnings. Every sentence adds substantive information. However, the opening is a list of example phrases rather than a crisp statement of purpose, which slightly delays the main point. Still, it remains efficient for the tool's complexity.

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

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

For a tool with 2 parameters, no output schema, and rich annotations, the description is highly complete. It covers the return verdicts, the two data paths (SEC EDGAR/XBRL and grounded pipeline), evidence with citations, the error semantics of could_not_verify, and the unsupported case. This gives the agent everything needed to interpret results correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning for tolerance_pct: explains it overrides implied wording tolerance, is capped at 5 by default, and advises setting 1-2 for hallucination detection. It also provides concrete claim examples for the claim parameter, going beyond the schema's one example.

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 verifies natural-language factual claims against authoritative sources, with explicit example phrases. It distinguishes from siblings by positioning itself as the consolidated claim-verification tool that replaces multiple sequential calls, and covers both structured financial and grounded general claims.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal routing (company-financial vs any other factual claim), providing clear context for when the tool is appropriate and indicating it is the unified replacement for a multi-step pipeline.

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