Greenhouse

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral details: the default model (Workers AI Llama 3.3, free), the requirement for a user-provided API key to probe Anthropic (with direct payment to Anthropic), and the return structure (per-model score, confidence, signals, raw_response plus combined view). No contradictions with annotations.

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

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

The description is a compact three-sentence paragraph. The first sentence states the core purpose, the second adds functional details (default model and optional Anthropic), and the third provides use cases and return summary. Information is front-loaded and each sentence earns its place without redundancy.

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

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

The description covers the core functionality, parameters, default behavior, and return structure. Given the absence of an output schema, it compensates by describing the per-model and combined view. However, it could be improved by noting any rate limits or model availability constraints. Overall, 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 description coverage is 100%, so baseline is 3. The description enhances parameter understanding by specifying that 'workers-ai' is the default model and that '_apiKey' is only needed if probing Anthropic. It also clarifies that 'context' helps disambiguate. This adds value beyond the schema descriptions.

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

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

The description clearly states the verb 'Probe', the resource 'LLMs', and the outcome 'score visibility (0-100) per model'. It also specifies the default model and an optional provider (Anthropic), making the tool's function unambiguous. While not explicitly differentiating from every sibling, its focus on AI visibility scoring is distinct from tools like deep_research or 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 concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. This guides when to use the tool effectively. However, it does not explicitly mention when not to use it or offer alternatives among siblings, slightly reducing the score from perfect.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint:false) by explaining that the tool routes questions, fills arguments automatically, aggregates from multiple sources, and returns citations as stable pipeworx:// URIs. It also sets expectations about authority and structure, which is valuable context the annotations alone do not provide.

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

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

The opening is strong and front-loads the key directive, but the description becomes repetitive and somewhat rambling toward the end, especially around deep_research and breaking news. The long list of domains and trigger phrases is useful, yet the trailing guidance could have been tighter without losing meaning.

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 responsibly states what the return will look like: a structured answer with stable citation URIs. It covers the tool's scope, routing behavior, and usage signals, and provides examples. It does not detail every edge case, but for a single-parameter query tool, it is sufficiently complete for an agent to call it correctly.

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

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

Schema coverage is 100% — every parameter (question, q, text, input, query, prompt) is documented as an alias for the natural-language question. The description does not add parameter-specific semantics beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific function: it routes natural-language questions to one of 5,798 tools across 1,517 verified sources and returns structured answers with citation URIs. It explicitly distinguishes itself from alternatives like deep_research and web search by listing its domains (SEC filings, FDA data, FRED/BLS, patents, real estate, etc.), making it easy for an agent to identify this as the go-to factual lookup tool.

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

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

The description is explicit about when to prefer this tool over web search, provides trigger phrases like 'what is', 'look up', 'find', and 'get the latest', and gives concrete examples. It also names an alternative for broader research ('use deep_research') and clarifies that breaking news is already handled, giving clear routing 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 cover safety (readOnly, idempotent, non-destructive), so the description adds value by disclosing temporal behavior: no candidate is active as of 2026-07-26, so it currently 'matches ask_pipeworx exactly,' and behavior will shift when a candidate goes live. 'Falls back to nothing — this IS a full working router' preempts the misconception that beta means partial functionality, and the note that results feed merge decisions is honest about experiment participation.

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 front-loaded sentences: core identity and behavior are in the first sentence, with usage and caveats following. Some redundancy exists (the no-candidate-active statement partly restates 'whenever one is under test'), and the precise retirement date 2026-07-26 will become stale.

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 covers what the router does, its current state, usage, and relationship to the stable version. The response shape is handled by reference ('same response shape' as ask_pipeworx), which is acceptable but leaves an agent without output details unless the sibling schema is inspected.

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 (question plus five aliases) documented in the schema, so the structured data carries the load. The description adds nothing beyond 'same arguments' as the stable sibling, so the baseline 3 is appropriate.

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

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

The description opens by identifying the tool as the 'Beta version of ask_pipeworx' and a 'universal router' over 5,798 tools, with 'same arguments, same response shape.' This states a clear resource and function and differentiates it from the stable sibling through the experimental candidate-routing framing, so an agent can distinguish it from ask_pipeworx and ask_pipeworx_grounded.

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?

'Use it exactly like ask_pipeworx when you want the newest routing' gives an explicit activation condition, and the contrast with 'the stable router' implies ask_pipeworx is the production alternative. It stops short of stating a firm when-not-to-use rule, such as preferring the stable version for high-stakes or production-critical queries.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses refusal behavior, exact success and refusal response shapes, the extra LLM call cost, and the guarantee that only source-contained data is used. This gives agents a strong mental model of expected behavior.

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

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

The description is dense but well-structured: behavior first, output contract second, usage guidance third. Every sentence adds functional value, and the critical use-case guidance is front-loaded before the cost trade-off.

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 grounded-answer tool with no output schema, the description fully covers what the agent needs: routing behavior, success and refusal formats, refusal reason enum, cost implications, and when to prefer the sibling. No critical operational detail is missing.

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

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

Schema coverage is 100%, so the sole meaningful parameter ('question' with aliases) is already fully documented. The description adds no parameter-specific guidance, but the schema carries the burden sufficiently, making the baseline 3 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 this is a hallucination-resistant, grounded answer mode that extracts answers using only tool result content. It distinguishes itself from ask_pipeworx by naming the exact routing behavior and the strict evidence-based output contract.

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

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

Description explicitly says when to use: when answers will be quoted, cited, or acted on and facts must not be invented. It also gives the alternative ask_pipeworx and a cost-based preference rule, so an agent can select between siblings confidently.

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

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

Annotations indicate readOnlyHint, idempotentHint, openWorldHint, no destruction. The description adds extensive behavioral details beyond annotations: market resolution and confidence levels, fan-out logic per category, response shapes with warnings (e.g., 24h move warning), resolver contract, parent event extraction, news fallback mechanisms, safety low-confidence blocking, closed market handling, wide-spread illiquidity notes, and resolution rule risk parsing. 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 very long and densely packed with details. While every sentence provides value, it could benefit from better structuring (e.g., headings or bullet points). It is not concise, but it is well-ordered and front-loaded with core purpose.

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

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

Despite no output schema, the description thoroughly documents return shapes (result.market, result.analysis, result.evidence, resolver contract, parent event, news fields). Parameters are fully described. Annotations cover safety. All critical aspects for correct invocation and interpretation are addressed.

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

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

Schema coverage is 100%, baseline 3. The description adds significant meaning beyond schema: explains depth options ('quick' vs 'thorough' fan-out), market input variants (slug, URL, question text), and include_raw behavior (summary vs full payloads, size estimates). Each parameter's context is 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 it researches a Polymarket bet by pulling Pipeworx data. It specifies multiple input formats (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by its unique data-fan-out and resolution behavior.

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

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

The description explicitly states when to use: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It provides example scenarios and classifier categories. However, it does not explicitly state when not to use, though the sibling tools list provides 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 readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. 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 front-loaded with common queries and key guidance, then provides detailed parameter behavior. Each sentence adds value, though slightly verbose. Could be trimmed without losing meaning.

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 covers what the tool does, when to use, parameter details, data sources, sorting, and return format (paired data + URIs). It is complete for its complexity level.

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 meaning beyond schema by explaining what each enum value retrieves (company vs drug), and for 'values' provides examples and constraints (tickers/CIKs for company, names for drug, 2-5 items). This exceeds baseline.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific example queries and data sources for each type. It distinguishes from sequential lookups and sibling tools like entity_profile by emphasizing efficiency.

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

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

Explicitly provides when to use (comparison queries like 'X vs Y', 'which is bigger') and advises preferring over sequential single-pack lookups. However, it does not explicitly exclude single-entity queries (which would be served by entity_profile), leaving slight ambiguity.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the auth/paid-plan requirement, parallel decomposition, gaps[] with never-invented guarantee, stable and fetchable citation_uri, contradictions[] for standard/thorough, semantic excerpting, and expected latency. These are meaningful behavioral traits not captured by annotations.

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

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

Despite being long, the description is front-loaded with the most critical constraints (account requirement, alternative tool) before core mechanics, and every sentence adds a distinct fact: access, scope, routing, return format, gap handling, contradictions, latency. There is no filler; the density is justified by the tool's complexity.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so in detail: findings packet contents, hop field, citation_uri, gaps[], contradictions[], and latency. Combined with the rich annotations and complete parameter schema, no critical calling information is missing.

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

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

Schema coverage is 100%, so the schema already documents question and depth. The description adds operational meaning beyond the schema: 'thorough' requires a paid plan, depth choices affect hop behavior and latency, and multi-step questions resolve in one call. It improves parameter understanding without being redundant.

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 concrete operation—grounded multi-source research over Pipeworx's 1517 structured data sources in one call—and immediately distinguishes itself from open-web search and ask_pipeworx for single lookups. 'NOT open-web search' and 'For a single lookup use ask_pipeworx instead' make sibling differentiation explicit.

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

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

It gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and when-not-to ('For a single lookup use ask_pipeworx instead'), plus an auth-based fallback to ask_pipeworx for unsigned users. This leaves no ambiguity about selecting the tool.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false. The description adds that the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This provides useful behavioral context about output readiness and no side effects, consistent with annotations.

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

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

The description is relatively long but well-structured. It starts with purpose, lists domains, explains output, and gives usage instruction. Every sentence adds value. Minor redundancy could be trimmed, but overall 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 presence of annotations and full schema, the description explains the core functionality and output format adequately. It does not cover default limit or ranking details, but for a discovery tool this is sufficient. Output schema is missing but not critical here.

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

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

Schema coverage is 100% with all parameters described. The description mentions 'query' and 'limit' but does not add significant meaning beyond the schema. It clarifies that 'query' accepts natural language and lists aliases, which is helpful but not essential. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and explains that it returns top-N relevant tools with full schemas, ready to call. It distinguishes itself from sibling tools by instructing to call it 'FIRST when you have many tools available and want to see the option set,' which sets it apart from specific tools like greenhouse or polymarket tools.

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

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

The description provides explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist for:' followed by a list of domains. It also says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This implies when not to use (when you need one answer), although it does not name specific alternatives.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavior beyond that: it fans out across many sources, soft-fails on the USPTO sunset, treats empty sections as real 'no data' rather than bugs, and returns a non-bare failure for private companies. 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 it is dense and front-loaded with wide-ranging examples and a semicolon-separated list of output sections. Some repetition exists around accepted value types, but the information is organized enough to remain scannable despite its length.

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

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

There is no output schema, so the description carries the burden of explaining what the agent can expect. It enumerates every major return section, explains source failure handling, covers resolved/unresolved inputs, and specifies the accepted value shapes. This is complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context by explaining that 'company' and 'ticker' are interchangeable, that value can be a ticker, CIK, or name, and that names resolve via SEC EDGAR's company-name match. This goes beyond the schema's plain property 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 states a specific verb and resource: it builds a 'full cross-source profile of a US public company in ONE parallel call.' It includes concrete natural-language triggers and distinguishes itself from chaining single-pack SEC/XBRL/news lookups for a holistic view.

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

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

It explicitly tells the agent when to prefer this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies that a private company is not a failure but returns resolved:false, which helps set expectations for edge cases.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds only minor context about clearing sensitive data, not significantly beyond annotations.

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

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

Two sentences with no wasted words, front-loaded with the core purpose.

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

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

For a simple tool with one parameter, no output schema, and annotations provided, the description covers purpose, usage, and pairing, making it complete.

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

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

Schema coverage is 100%, so the schema documents the parameter well. The description does not add further semantics to the parameter 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 verb 'delete' and the resource 'memory by key'. It distinguishes from siblings by mentioning 'previously stored memory' and pairing with 'remember' and 'recall'.

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

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

Explicitly lists when to use: 'when context is stale, the task is done, or clear sensitive data'. It also pairs with related tools, giving clear context for use.

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

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

Openly describes the fetch-extract-emit workflow. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) align perfectly; description adds context about the process without contradiction. For a non-destructive read tool, this is complete.

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 zero redundancy: first defines function, second explains mechanism/output, third lists use cases. Perfectly front-loaded with the core action.

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

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

Covers purpose, mechanism, output format, and use cases. Lacks detail on error handling or edge cases (e.g., unparseable pages), but the tool is simple and annotations cover safety. Given no output schema, description sufficiently characterizes the single text blob output.

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

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

Schema covers both parameters completely, and the description adds value by explaining 'Full URL' and specifying default (25) and max (50) for max_links. This enhances schema's descriptive comments.

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

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

Clearly states it generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt'. Completely differentiates from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on visibility scanning.

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

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

Explicitly lists three use cases (client site indexing, personal project drafting, competitor auditing). However, doesn't specify when not to use it or mention alternatives among siblings, though the unique purpose makes alternatives less critical.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the return content (resume, contact info, application history, interviews, notes), which is beyond what annotations provide.

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

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

A single, well-structured sentence that front-loads the main action and lists key return components. No wasted words.

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

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

Given the output schema exists and annotations cover safety and idempotency, the description is complete enough for this simple 2-parameter tool. It summarizes the main return fields adequately.

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

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

Schema description coverage is 100% for both parameters (id and _apiKey). The description does not add additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description uses 'Get full candidate profile by ID' with a specific verb and resource, and lists returned data types. It distinguishes from siblings like greenhouse_list_candidates and greenhouse_get_job.

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

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

The description clearly implies when to use (to retrieve a specific candidate's full profile by ID), but does not explicitly mention when not to use or suggest alternatives like greenhouse_list_candidates for searching.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to reiterate safety. It adds value by specifying the return content, but does not disclose additional behavioral traits such as rate limits or auth details beyond the schema.

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 sentence that is front-loaded with the main action, using active verb and concise wording. No superfluous content.

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

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

For a simple read tool with complete annotations and an output schema, the description adequately covers the purpose and return values. No gaps in context for an agent to understand and 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?

The input schema has 100% coverage with clear descriptions for both parameters (id and _apiKey). The description does not add further 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 clearly states the verb 'Get' and resource 'job', and specifies the returned fields (description, requirements, hiring team, linked applications). It distinguishes from sibling 'greenhouse_list_jobs' which lists jobs rather than retrieving details.

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

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

The description implies usage when a specific job ID is available and full details are needed, but does not explicitly state when to use it versus alternatives like 'greenhouse_list_jobs' or other tools. No exclusions or context are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds value by detailing returned fields (names, status, dates), which helps the agent understand output without deep schema inspection. No contradictions.

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

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

Two sentences clearly state purpose and key features. Could be slightly more structured but is efficient and front-loaded.

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

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

Given the presence of an output schema (mentioned), the description adequately covers what the tool does and what data it returns. Filtering is mentioned, but pagination is implied via schema. No critical gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameters by providing examples for status ('screening', 'interview'), which adds clarity beyond the schema's generic descriptions. However, it does not elaborate on page or per_page usage.

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 lists job applications, returns specific fields (applicant names, job IDs, status, dates), and supports filtering. It clearly distinguishes from siblings like greenhouse_list_candidates and greenhouse_list_jobs.

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 mentions filtering by job or stage, but does not explicitly explain when to use this tool vs. other list tools (e.g., list_candidates) or provide exclusions. Context implies it's for applications, but lacks direct guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by stating the tool returns specific fields (names, IDs, etc.) and suggests an alternative for more detail. No contradictions.

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

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

Two sentences: first states purpose and return values, second provides actionable guidance. No filler 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?

Given that the tool has an output schema and 100% parameter coverage, the description succinctly covers what the tool returns and how to get more details. Pagination parameters are documented in the schema. The description is complete for a paginated list tool with good annotations.

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

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

Schema coverage is 100% with descriptions for all three parameters (page, _apiKey, per_page). The description does not add new meaning beyond the schema, meeting the baseline for high coverage.

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

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

The description clearly states 'Search candidates in your ATS' with a specific verb and resource. It lists returned fields (names, IDs, email addresses, application status) and distinguishes from sibling tool greenhouse_get_candidate.

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 recommends greenhouse_get_candidate for full profile details, indicating when not to use this tool. It provides a clear alternative within the same family, though it lacks explicit guidance on when to use this vs. other list tools like greenhouse_list_applications.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by specifying the returned fields (titles, IDs, etc.), which gives the agent a concrete expectation of the output. 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 sentences, each adding essential information: the first states the purpose and scope, the second lists key output fields and directs to the detail tool. No redundant or extra words.

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

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

Given the tool is a simple read-only list operation with an output schema, the description covers the main behavior and distinguishes from the detail sibling. It lacks explicit mention of pagination (e.g., 'use page and per_page to paginate') but the schema already covers parameters, making this a minor gap.

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

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

Schema coverage is 100%, and the schema descriptions for 'status', 'page', 'per_page', and '_apiKey' are clear. The description does not add new parameter-level detail beyond the schema; it only mentions the tool browses 'open and closed' postings, which aligns with the status parameter but adds no syntax or format guidance.

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

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

The description clearly states the tool browses open and closed job postings and enumerates returned fields (titles, IDs, departments, statuses, posting dates). It explicitly distinguishes from the sibling tool greenhouse_get_job, which retrieves full details and candidate pipeline.

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

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

The description directs users to greenhouse_get_job for 'full details and candidate pipeline,' implying this tool is for high-level listing. It provides clear context on when to use the listing tool vs. the detail tool, though it does not explicitly state when not to use it or mention alternatives beyond the single sibling.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. Description adds that it returns specific fields and that the include_inactive parameter affects results, offering extra behavioral detail beyond annotations.

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

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

Two sentences, front-loaded with core purpose, 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?

With only one optional parameter, no output schema, and comprehensive annotations, the description fully covers what the agent needs: purpose, return fields, usage advice, and parameter behavior.

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

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

Schema covers all parameters (100% coverage) with descriptions. The tool description does not add additional parameter meaning beyond what the schema provides, maintaining the baseline.

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

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

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

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

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

Explicitly advises when to use: to review existing subscriptions before adding more or to find an ID to cancel, providing clear context.

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

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

The description goes far beyond annotations by disclosing the claim_token mechanism, rate limiting (5 per identifier per day), that it's free and doesn't count against quota, and how the team processes feedback. It also clarifies the two-step flow: file without an account to get a token, then pass that token back later to check status.

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

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

The description is longer than typical but every sentence contributes: usage conditions, exclusions, token mechanics, rate limits, and guidance on what to include. It's front-loaded with the core purpose and then layers details logically. Slightly verbose in places (e.g., restating the exclusion), but overall tight for the amount of behavior it must convey.

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

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

For a feedback tool with 4 parameters and no output schema, the description explains the entire lifecycle: what happens on filing (claim_token returned), how to retrieve resolution status, and what the team does with the feedback. It also covers edge cases (different server, no account, rate limit) making it self-contained for an agent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful extras: it explains the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), clarifies the intent of each type value, and tells the user to 'be specific' and not paste end-user prompts. This enriches parameter understanding beyond the 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from siblings like ask_pipeworx by emphasizing that it's for reporting issues about Pipeworx tools specifically, and even names the alternative for non-Pipeworx tools.

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

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

Provides explicit when-to-use guidance for each feedback type (bug, feature, data_gap, praise) and a clear exclusion: 'if the tool came from a different MCP server... we cannot fix it... file it with that server instead.' It also offers a fallback for uncertainty ('Not sure? Pipeworx tool names are the ones this connection lists').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds key behavioral details: data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h per window), and aggregation logic, going well beyond annotations.

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

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

Two sentences plus concise bullet points, front-loaded with main purpose, no redundant 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?

Despite no output schema, description explains return content (top tools, packs, call volume), use cases, data source, cache, and privacy constraints. Fully sufficient for an agent to invoke correctly with one optional param.

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

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

Schema coverage is 100% with one enum parameter. Description adds caching time per window (5min-1h), which supplements schema's duration advice. Baseline is 3 due to full schema coverage; extra cache detail justifies 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?

Clearly states the verb 'Returns' and resource: top tools, top packs, total call volume. Distinguishes from siblings like 'discover_tools' by focusing on trending usage by AI agents, making purpose unambiguous.

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

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

Explicitly lists three use cases (e.g., discovering hot data sources, confirming canonical tool choice) that guide when to use. Does not specify when not to use or alternatives, but context is clear and valuable.

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

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

The description extensively discloses behavioral traits beyond annotations: details internal algorithms (Jaccard similarity filter, placeholder partition filter, fill check with order book depth), realizable edge computation, and response structure. No contradiction with annotations (all read-only hints consistent).

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

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

The description is relatively long but every sentence adds value; it is front-loaded with the core purpose and explains modes in detail. Could be slightly more structured (e.g., bullet points for modes), but remains clear and not verbose.

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

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

Despite missing output schema, the description thoroughly explains the response structure (opportunities[], partition_check, fill check with realizable edge and thin_legs). Combined with 100% parameter coverage and detailed annotations, the description is fully sufficient for an agent to understand inputs, behavior, 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?

With 100% schema description coverage, baseline is 3. The description adds significant meaning by explaining the difference between event and topic modes, giving example slugs, and describing cross-event scanning behavior. This exceeds the baseline.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity and partition-sum checks, and distinguishes itself from sibling tools like polymarket_edges or polymarket_fill_risk. It specifies three modes (trending scan, event, topic) with clear verbs.

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

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

The description provides explicit guidance on when to use each parameter (no args for trending, event for specific market, topic for cross-event) and directs users to polymarket_fill_risk for custom sizing. However, it lacks explicit when-not-to-use scenarios beyond the fill check warning.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds extensive behavioral detail: explains the five model families (crypto_price, news_momentum, etc.), edge calculation (net of slippage, Kelly fractions), tradeable-edge knobs, diagnostics, and Fed bets exclusion. 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 lengthy but well-structured: high-level purpose first, then segments, knobs, response structure. Every sentence adds necessary detail for a complex tool. Could be slightly more concise without losing key information, but the structure is logical and front-loaded.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It details the three response segments, diagnostics, caching, and knob interactions. Even explains why min_kelly doesn't filter partition arbs. No output schema is needed because the response structure is fully described.

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

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

Schema coverage is 100% with all parameters described in the input schema. The description adds value by explaining how parameters interact (e.g., tradeable-edge knobs, min_kelly vs min_partition_leg_kelly) and the context for their use, which goes beyond the schema's per-parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also specifies the use case ('what should I bet on today') and differentiates from sibling tools by detailing the response segments and models.

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

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

The description provides context for when to use this tool (discovering opportunities without paging markets) and mentions caching behavior. However, it does not explicitly exclude alternatives or give guidance on when not to use it versus sibling Polymarket tools, though the detailed segment descriptions indirectly aid selection.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds rich behavioral details: it reads from snapshots, returns three categories of data, explains computation of trend and decay, and notes that snapshot dates are only present when data runs. 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 well-structured, starting with the core purpose, then detailing response fields, and ending with limitations. It includes a helpful example sentence. While slightly long, 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, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) with field details. All parameters are covered, and limitations are stated. The tool's complexity is fully addressed.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the purpose of each parameter ('lookback', 'snapshot family') and providing defaults and constraints that go beyond the schema descriptions.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' and answers a specific question about edge age and shrinkage. It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on persistence over time.

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 context with the example of fresh vs. old wide edges. It also mentions limitations like TTL and data generation conditions. However, it does not explicitly advise when not to use it or compare directly to 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds rich behavioral detail: it walks the order book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdicts (clean|degraded|cannot_fill), and in basket mode returns theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs[], max_clean_notional_usd, forced_directional_risk. It warns about partial fill risks. No contradiction with annotations.

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

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

The description is relatively long but well-structured with sections for single-market and basket modes, using bullet-like formatting. Information is front-loaded with the core purpose. While every sentence adds value, it could be slightly more concise by moving some details to an examples section.

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 (dual mode, 4 params, no output schema, high-risk application), the description provides thorough coverage: it explains both modes fully, lists return fields, warns about thin legs and directional risk, and ties to sibling tools. It addresses the 'dominant loss mode in real arb-bot P&L'. No gaps remain.

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

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

Schema description coverage is 100% (all 4 parameters have descriptions). The tool description adds significant meaning: for size_usd it clarifies interpretation as 'max spend on buys, target proceeds on sells' in single-market and 'settlement notional (shares per leg)' in basket. It explains side defaults (auto for basket based on partition sum). This goes well beyond schema descriptions.

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

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

The description clearly states the tool does a 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between single-market and basket modes, and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool before acting on those 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?

The description explicitly instructs to 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround not capturable, partial basket fills convert arb to directional risk). It provides mode selection guidance (single-market vs basket) but does not explicitly state when NOT to use the tool, leaving a minor gap.

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 readOnly/idempotent annotations, the description discloses substantial behavioral traits: compatibility warnings can be non-empty even when matched_pairs>0, matching is keyword/word-overlap rather than a shared resolution source, unknown legs are never paired, and temporal_alignment null does not mean aligned. It also details the Kalshi fee limitation, clarifying that spreads are gross and not a net tradeable edge. There is no contradiction with the annotations.

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

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

The description is long but well-structured: modes, response contents, safety fields, codes, skipped counters, and the fee caveat are clearly segmented. Each section earns its place given the complexity of the tool, though the sheer volume of caveats makes it heavier than a minimal 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?

Since there is no output schema, the description carries full responsibility for return semantics, and it covers leg prices, top_spreads_pp flags, compatibility codes, skipped-unclassified behavior, temporal alignment, and the fees note. An agent has enough information to interpret results and anticipate warnings.

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

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

The input schema already covers all three parameters at 100%, so the baseline is 3. The description adds meaning by grouping `topic` versus explicit `kalshi_event_ticker` + `polymarket_event_slug` into two modes and by stating that both modes run the identical token-overlap matcher. It also clarifies that explicit custom pairing expects both venue identifiers, which is useful beyond the schema field 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 opening sentence identifies the exact deliverable: a cross-venue spread between Kalshi and Polymarket for the same resolving question. It also differentiates this from Polymarket-only siblings by emphasizing the cross-venue comparison and by naming the two input modes. The purpose is specific and actionable.

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 usage guidance for both invocation modes: `topic` for pre-mapped macro shortcuts and explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings. It also warns that pre-mapped topics often return compatibility warnings and that pre-mapped is not the same as tradeable. It does not contrast against sibling tools such as polymarket_arbitrage, but the mode-level conditions are 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. Description adds scoping details and behavior of omitting 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?

Four sentences, well-structured: action first, then purpose, scoping, pairing. Front-loaded and concise, no wasted words.

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

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

Given tool simplicity and good annotations, description covers usage, scoping, behavior when omitting key, and relationship with siblings. No missing elements.

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 description on key parameter. Tool description adds contextual examples (ticker, address, research notes) and pairs with other tools, providing meaning beyond schema.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, with specific verb+resource and distinguishes from siblings 'remember' and 'forget'.

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

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

Explicitly says when to use (look up stored context) and provides alternatives: 'remember' to save, 'forget' to delete. Scoping to identifier further clarifies usage context.

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

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

The description states that setting mark_read:true flags events as read, which modifies state, but annotations declare readOnlyHint=true. This is a direct contradiction, making the description misleading about the tool's mutability.

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 deliver the core purpose, parameters, behavior, and an alternative. While front-loaded, the inclusion of an HTTP URL adds slight overhead but remains relatively concise.

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 covers return fields (source, citation_uri, raw payload) and filtering options. However, the contradiction with annotations undermines completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the effect of mark_read and giving an example for type, which goes beyond the schema's 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 'Pull fired events from your subscription feed' with a specific verb and resource, and distinguishes itself from sibling tools like list_subscriptions by focusing on fired events and mentioning polling and an HTTP alternative.

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 context on when to use filtering by type and since, and notes that polling works fine. It also mentions an alternative endpoint for scripts/dashboards, giving clear usage guidance.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description details the fan-out behavior, fallback logic (GDELT → GNews on rate limits), and soft-failure for USPTO. 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 somewhat long but front-loads the purpose with examples and then provides necessary details. Every sentence adds value, though it could be slightly more concise.

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 specifies the return format (structured changes grouped by source, total_changes count, citation URIs). The high complexity of multiple sources and fallback is fully covered.

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

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

Schema coverage is 100%, but the description adds significant value: explains `since` accepts ISO dates or relative shorthand with examples, clarifies `value` can be ticker or CIK, and notes `type` only supports 'company'.

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 a change feed for a company using multiple sources (SEC EDGAR, GDELT/GNews, USPTO). It provides natural language examples and distinguishes from the sibling tool entity_profile by specifying when to use each.

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

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

The description explicitly advises when to use this tool vs. entity_profile ('Use entity_profile instead when you want the static profile...'). It also gives guidance on the `since` parameter with examples and recommended defaults like '30d'.

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?

Adds persistence details (scoped by identifier, 24-hour retention for anonymous) beyond annotations. No contradictions; annotations already declare idempotent and non-destructive.

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: purpose first, then usage, then persistence details. No wasted 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?

Fully explains storage mechanism, scoping, retention, and companion tools, making it complete despite lack of output schema and simple parameters.

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

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

Schema already covers both parameters (key, value) with descriptions. The description adds example values but no new semantic depth 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 verb ('save') and resource ('data as key-value pair'), with specific examples of what to store. Distinguishes from sibling tools by mentioning recall and forget.

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

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

Explicitly tells when to use ('when you discover something worth carrying forward') and pairs with related tools ('recall', 'forget'), providing clear guidance.

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

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

Beyond the read-only/idempotent annotations, the description discloses many behavioral traits: graceful degradation if GLEIF/OpenFIGI is unavailable, explicit unresolved identifiers instead of silent omission, source-labelled identifiers, candidate lists on ambiguous matches, and internal cascading through multiple lookup endpoints. This is rich, non-obvious behavior that an agent would not otherwise know.

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

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

The description is front-loaded with user phrasings and the central 'Use FIRST' directive, and almost every clause carries useful information. However, it is extremely dense, with long parenthetical chains and a few repetitive points that could be tightened without losing meaning. It is well-structured for the complexity but not maximally concise.

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

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

With no output schema, the description carries the burden of explaining return behavior, and it does so thoroughly: identifier labels, unresolved fields, figi_candidates on ambiguity, RxNorm citation format, EDGAR fallback, and ISIN-to-LEI behavior. Both supported types and all accepted value forms are covered, and the graceful degradation note addresses failure modes. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is already 100%, and the description and value parameter description add crucial semantics: accepted input forms (ticker, CIK, ISIN, name, brand/generic drug name), the ENTITY NAME ONLY restriction, and a concrete warning against including security-class trailing words in bond issuer lookups. The type enum is also expanded with detailed behavior per type.

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 by giving concrete user phrasings ('What's the ticker for…' / 'find the CIK for…') and then states a precise verb-resource pair: resolve a user-spoken name to canonical/official identifiers that other tools require. It explicitly distinguishes two supported types (company and drug) with detailed cross-source identity coverage, making it clear this is an entity-identifier resolution tool rather than a profile, comparison, or research tool.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also clarifies when resolution should not assert an answer (ambiguous instrument names return figi_candidates) and when enrichment degrades gracefully. It does not name sibling alternatives or state explicit when-not-to-use conditions, so it falls short of a full 5, 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 indicate safe, read-only, idempotent behavior. The description adds value by detailing that it internally calls ai_visibility_check for each entity and returns a ranked list with specific fields, without contradicting annotations.

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

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

The description is three sentences, each earning its place: main action, process, and use case. It is front-loaded with the core purpose and avoids unnecessary details.

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

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

Despite lacking an output schema, the description covers return fields (score, confidence, signal density) and explains the internal mechanism. It could explicitly state sort order, but overall it is sufficiently complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description restates that the first entity is the subject (already in schema description) and does not add new semantic insight beyond what the 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 clearly states the verb 'Compare AI visibility' and the resource 'multiple entities', explicitly distinguishing from sibling ai_visibility_check by emphasizing side-by-side comparison and ranking.

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

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

The description provides a concrete use case (competitive AI-marketing audits) and an example question, making it clear when to use the tool. It implicitly distinguishes from single-entity checks but does not explicitly state when not to use it.

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

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

Annotations already provide readOnlyHint, idempotentHint, and openWorldHint, establishing safety. The description adds critical behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. This goes beyond annotations by explaining failure modes and latency.

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

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

The description is a single dense paragraph, front-loaded with purpose. Every sentence adds value: usage, return structure, ecosystem scope, failure handling. It is somewhat long but justified by the tool's complexity. Could be slightly more structured (e.g., bullet points) but still effective.

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

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

Despite lacking an output schema, the description enumerates all return fields: summary block, per-advisory detail, links, recent alternatives, and sources_failed. It covers ecosystem constraints, partial failure behavior, and latency considerations. This is a very complete description for a complex tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra context: package accepts scoped packages (e.g., '@types/node'), and version defaults to latest. This provides clarity beyond the schema's own descriptions, though the schema already does a good job.

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, specific verb phrase: 'Composite "should I add this npm package to my project" check in ONE call', which explicitly states the tool's purpose and resource. It distinguishes itself from sibling tools by focusing on npm dependency evaluation across multiple data sources, a unique combination among the listed siblings.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also clearly states boundaries: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', telling the agent when not to use this tool and what alternative exists.

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 are readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false. The description adds specifics: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. No contradiction.

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

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

Three to four sentences, no fluff, front-loaded with core purpose, then usage guidance, then technical details. 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, the description details what is returned (top-N passages with character offsets and similarity scores). It covers usage, embedding method, truncation behavior, and pairing with another tool. Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds extra context: 'pass the text you already pulled', 'natural-language query', and explains the limit parameter's role in returning top-N passages.

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

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

The description clearly states it performs semantic search inside a fetched record, specifying example texts (SEC 10-K, article) and what it returns (passages with offsets and scores). It distinguishes itself from siblings like ask_pipeworx_grounded by noting the pairing.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains it saves context. Also mentions pairing with ask_pipeworx_grounded, giving clear guidance on when to use this tool versus alternatives.

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

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

The description adds behavioral context beyond annotations: requires Pipeworx OAuth account, delivery limitations (sms 10/day cap, webhook auto-disabled after 10 failures), and webhook signing details. Annotations are readOnlyHint=false, idempotentHint=true, but the description's behavior is consistent.

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

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

The description is well-structured with clear sections and front-loaded purpose. It is somewhat lengthy but each sentence adds value. Could be slightly more concise without losing 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?

Given no output schema, the description explains the return value ('Returns the new subscription id'). It covers account requirements, all delivery channels with constraints, and type-specific parameter examples. Comprehensive for a subscription creation tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds extra meaning: specific examples for type, detailed constraints for delivery (phone verification, webhook security). This goes beyond the schema but is not essential since schema already covers basics.

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 'Create a proactive monitoring subscription' which is a specific verb+resource. It clearly distinguishes itself from sibling tools like 'unsubscribe' and 'list_subscriptions' by being the creation action. The description fully clarifies what the tool does.

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

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

The description provides clear guidance on when to use the tool: when needing a live-data event subscription. It lists supported types and gives examples. However, it does not explicitly state when not to use it or compare with alternatives like 'recent_alerts' for pulling events.

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?

Adds significant behavioral context beyond annotations: returns categorized examples with tool+argument shapes, uses live catalog, and explains default vs. focused behavior. 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?

Front-loaded with synonyms and examples, but slightly verbose with multiple introductory phrases. Each sentence adds value, but could be more compact.

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?

Fully explains what returns and how to use the parameter. No output schema, but description covers return structure adequately for a simple tool.

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

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

Schema coverage is 100%, and the description reiterates the parameter meaning without adding new details beyond the schema definition. Baseline score is appropriate.

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

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

The description uses specific verbs ('returns') and resources ('category-bucketed example questions') and clearly distinguishes itself as the onboarding entry point, advising to use it first.

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 call (first use, when unsure of capabilities) and how to pass arguments. Does not explicitly exclude use cases, but context is clear.

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

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

The description adds behavioral context beyond annotations: it explains that subscriptions are deactivated (not deleted) and that historical events remain accessible via 'recent_alerts'. This complements the idempotentHint and destructiveHint annotations without contradiction.

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

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

Two sentences, 26 words, no filler. The main action is front-loaded, and every sentence adds value.

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

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

For a simple one-parameter tool with no output schema, the description covers purpose, constraints, behavior, and consequences. It references a sibling tool for further context, making it 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?

With 100% schema coverage, the description adds no new information about the 'id' parameter beyond what the schema already states ('Subscription id (uuid) returned by subscribe'). The mention of 'by id' is redundant.

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

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

The description uses a specific verb 'Cancel' and clearly identifies the resource 'subscription by id'. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by outlining the action and effect. The ownership enforcement adds clarity.

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 that ownership is enforced and cancellation only works for own subscriptions. It does not explicitly list when not to use, but the tool's simplicity and lack of alternatives make the context 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?

Beyond annotations (readOnly, openWorld, idempotent), the description reveals routing logic (SEC EDGAR fast path vs. grounded pipeline), return semantics (verdict types, citation, reasoning), and critical error distinctions (could_not_verify vs. unsupported). This is rich behavioral context that is not present in annotations and does not contradict them.

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

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

The description is long but front-loaded with trigger phrases and logically organized. Each sentence contributes unique value (routing, verdicts, error states, consolidation benefits). Though dense, it is not bloated or repetitive.

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

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

Given the tool's complexity and lack of an output schema, the description enumerates verdict outcomes, explains the meaning of could_not_verify and unsupported, mentions citation and reasoning, and covers both processing paths. Alongside the annotations, it equips the agent with sufficient context 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?

With 100% schema coverage, the baseline is 3, but the description adds substantial meaning for tolerance_pct: explains it overrides implied wording, recommends 1-2% for hallucination detection, and clarifies default cap of 5%. This goes well beyond the schema's basic parameter descriptions.

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

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

The description identifies a specific verb and resource: 'natural-language claim verification against authoritative sources.' It distinguishes from siblings by focusing on 'fact check' / 'confirm or refute' triggers and noting it replaces a 4-6 step pipeline, setting it apart from general Q&A or 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?

It explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives trigger phrases and separates handling for company-financial vs. other claims, but does not name alternative tools or provide explicit '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.