Stripe_connect

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

Annotations already declare readOnlyHint and idempotentHint. The description adds value by explaining that Workers AI is free while Anthropic requires a BYO key and direct payment, that the default model is Workers AI Llama-3.3-70b, and that it returns scores per model. This context is beyond annotations, though rate limits or error handling are not discussed.

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 efficient paragraph that front-loads the purpose, then smoothly covers parameters and use cases. Every sentence adds value with no redundancy.

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

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

The tool has no output schema, so the description must describe return values. It does so adequately ('per-model {score, confidence, signals, raw_response} + combined view'). For a probe tool with moderate complexity, this is complete enough, though it could clarify how confidence is derived.

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?

All four parameters have descriptions in the schema (100% coverage). The description adds meaning by clarifying the default model, how _apiKey is used (passed to Anthropic), and that context helps disambiguate. It effectively supplements the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/entity and returns a visibility score (0-100) per model. It specifies what is returned (per-model and combined view). This distinguishes it from siblings like entity_profile or scan_competitor_ai_presence, which have different scopes.

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

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

The description gives use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains parameter behavior (default model, need for _apiKey for Anthropic). However, it does not explicitly state when not to use this tool or compare it to sibling alternatives like entity_profile.

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

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

The description reveals behavioral traits beyond the annotations: it routes to internal tools, returns stable pipeworx:// citations, works on every tier, and is a fast default entry point. While annotations already cover read-only and idempotency, the description adds valuable context about routing and output format, though it does not discuss error handling or rate limits.

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

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

The description is long but every sentence earns its place. It front-loads the most important directive ('PREFER OVER WEB SEARCH'), then efficiently covers use cases, examples, alternatives, and context. The structure flows logically from key decision to examples to step-up options, making it scannable and actionable.

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 (routing to thousands of sources) and lack of output schema, the description provides sufficient context: it explains the output format (structured answer with citation URIs), confirms it works on every tier, and specifies when to escalate to grounded or deep research. The examples cover a wide range of use cases, making it complete for an agent to select and invoke the tool correctly.

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

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

The input schema already covers all 6 parameters with descriptions and 100% coverage, but the description enhances semantics by providing example questions and explicit trigger phrases ('what is', 'look up', 'find'). This helps the agent formulate effective queries, going beyond the schema's alias 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 that the tool routes questions to 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It explicitly distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, making its unique role unmistakable.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and explicitly lists trigger phrases and example questions. It provides clear alternative selection criteria, telling the agent to use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions, leaving no ambiguity about when to use this tool.

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

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

The description adds that candidate routing improvements are enabled live only when under test, that none is currently active, and that results are compared against the stable router. These behavioral details go beyond the readOnly/idempotent annotations, providing useful context about its experimental nature 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?

Four sentences, each adding context (beta status, current state, usage, non-fallback reassurance). Slightly wordy but no filler; front-loaded with the key identification.

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 beta router, it explains the experimental edge, the current parity with ask_pipeworx, and the fact it is fully functional. Without an output schema, the description adequately directs the agent to treat it like ask_pipeworx.

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 documents all six parameters with 100% coverage, including aliases, so the description's mention of 'same arguments' adds little. Baseline score of 3 is appropriate.

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

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

The description clearly identifies this as a beta version of the ask_pipeworx universal router, stating it has the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by experimental routing improvements, though it does not explicitly contrast with other siblings like 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?

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that it is a full working router with no fallback. This gives a clear when-to-use trigger, though it does not discuss alternatives beyond ask_pipeworx.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses significant behavioral traits: it returns a structured object with evidence, can explicitly refuse with specific refusal_reason values, and costs an extra LLM call. It also explains the internal routing and extraction behavior, providing rich context 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?

Although the description is lengthy, every sentence carries essential information: purpose, mechanism, output/refusal format, and usage guidance. It is well-structured with a dash-separated list of refusal reasons, front-loads the main purpose, and contains no redundant filler.

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

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

Because there is no output schema, the description fully covers return values and error/refusal cases. It also explains the routing, the extra LLM call cost, and the intended usage context. The description is complete enough for an agent to invoke the tool correctly without external documentation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra parameter semantics beyond what the schema provides, as all six parameters are aliases for the 'question' field and are well-documented in the schema. The description's mention of 'fills arguments' is generic and not parameter-specific.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads that extracts answers only from tool results. It also explicitly distinguishes this from the sibling ask_pipeworx, giving both a specific verb+resource and differentiation.

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

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

Provides explicit guidance on when to use this tool: when the answer will be quoted, cited, or acted on and the agent must not invent facts. It also names the alternative (prefer ask_pipeworx for casual lookups) and notes the cost trade-off, offering clear decision criteria.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral context: fan-out logic per classifier, resolver contract with confidence/alternatives, parent_event extractor, news field error handling, safety short-circuits for low-confidence/closed markets, wide-spread warnings, and resolution-rule risk analysis. 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?

Description is long but well-structured, front-loaded with purpose and usage, then diving into detailed sections (classifiers, fan-out examples, response shapes, resolver contract, parent_event, news, safety, cancellation rules). Every sentence adds value for an AI agent, though slightly verbose for a single tool description.

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

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

Given the tool's complexity (multiple classifiers, data sources, edge cases, response shapes), the description is remarkably complete. It covers input types, resolution behavior, evidence sources per category, response key fields, error states (low confidence, closed markets, wide spreads), cancellation rules, and parent event extraction. No output schema exists but response shapes are clearly 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 enum descriptions. Description adds meaning: explains market input flexibility (slug, URL, question text), depth parameter defaults and behavior (quick vs thorough), and include_raw purpose (summarized vs full payloads). Examples and fan-out details further enrich parameter understanding.

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

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

Description explicitly states it researches Polymarket bets by pulling Pipeworx data, with specific input formats (slug, URL, question text). It clearly distinguishes from sibling tools like ask_pipeworx by focusing on betting edge and market resolution. The use cases 'should I bet on X', 'what does the data say about Y', and 'is there edge in Z' provide clear purpose.

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

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

Description gives explicit when-to-use scenarios and includes critical guidelines: inspect market_match_confidence before trusting analysis, check cancellation_rule for sports/esports bets, and notes blocking paths for low-confidence and closed markets. It explains resolution contract behavior and safety short-circuits, guiding proper tool invocation.

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

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

Description adds significant behavioral context beyond annotations: parallel execution, correct handling of off-calendar fiscal years, sorted results by primary metric, return of paired data + citation URIs. 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?

Description is moderately long but efficiently packed with essential information. Front-loaded with example queries. Slightly verbose but earns its length.

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

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

Given no output schema, description explains return values (paired data + citation URIs, sorted by primary metric). Covers both entity types thoroughly. Annotations confirm safety. Complete for this tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining what data each type pulls and providing examples (tickers for company, names for drug). Adds extra context beyond schema.

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

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

Description clearly states side-by-side comparison of 2-5 companies or drugs in one call, with specific example queries and data sources (SEC EDGAR/XBRL for companies, FAERS for drugs). Distinguishes from sequential single-pack lookups.

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

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

Explicitly instructs to prefer this tool over sequential single-pack lookups when comparing entities. Provides concrete use cases ('which is bigger / better') and quantifies benefit (replaces 8-15 sequential lookups).

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, yet the description adds substantial context: account requirement, paid plan for thorough, latency expectations (15-60s, up to 90s), gap recovery, contradictions scan, guaranteed fetchable citation_uri, and semantic excerpting. No contradiction with annotations; this is rich behavioral disclosure.

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

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

The description is lengthy but front-loaded with critical info (account requirement and alternative). Minor redundancy exists, such as citation_uri being described twice, and some repetition around findings packet contents. Still, for a tool with this complexity, it is well-structured and nearly every sentence earns its place.

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

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

With no output schema, the description fully defines the return structure: findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers auth, latency, limitations, and alternatives, making it exceptionally 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%, but the description adds meaningful detail beyond the schema: it explains what each depth value does (quick=3, standard=5 with gap recovery, thorough=8 paid with lead chasing) and clarifies that 'question' accepts broad/multi-part natural language. This elevates 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 states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explains the decomposition and parallel routing. It explicitly distinguishes itself from open-web search and from siblings like ask_pipeworx, leaving no ambiguity about what the tool does.

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

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

Provides explicit when-to-use vs alternatives: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also clarifies depth trade-offs, meeting and exceeding the 'clear context, no exclusions' bar.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's safe. The description adds value by detailing the return behavior: 'Returns the 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.' 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 two sentences long, front-loaded with the purpose: 'Find tools by describing the data or task.' Every sentence adds necessary information (use cases, return format, call instruction). No waste, highly 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 annotations (safe, idempotent) and absence of output schema, the description completely covers what the tool returns (top-N tools with schemas and examples) and its role as a discovery tool. It addresses the agent's need to know the output format and readiness to call results directly.

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 explains the query parameter as 'Natural language description of what you want to do' and lists examples, but this largely mirrors the schema's description. It does not add significant new meaning beyond what the schema provides. Aliases are already documented in the schema. Score reflects adequate but not exceptional value.

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

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

The description clearly states the verb 'Find' and the resource 'tools', and explicitly lists numerous example domains (SEC filings, financials, etc.). It distinguishes this tool from siblings by positioning it as the first call to discover available tools, contrasting with sibling tools that perform specific tasks.

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

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

The description specifies 'Use when you need to browse, search, look up, or discover what tools exist for...' and explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' While it doesn't explicitly state when not to use, the context is clear and provides strong guidance.

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

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

Annotations already convey read-only, idempotent, non-destructive behavior. The description adds valuable context: fans out across multiple sources, explains USPTO PatentsView API sunset (soft-fails), and describes return structure (e.g., URIs for filings). No contradictions with annotations.

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

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

The description is relatively long but every sentence adds value: trigger examples, data sources, return fields, and constraints. It's front-loaded with usage examples. Could be slightly more concise, but efficiently packs essential information.

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

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

No output schema is provided, so the description must explain return values. It does so adequately, listing all key fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI). The coverage of edge cases (USPTO sunset, name resolution requirement) adds 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 examples ('AAPL', '0000320193'), clarifies that 'type' currently only supports 'company', and explicitly states that names are not supported, adding meaning beyond the schema descriptions.

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

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

The description clearly states the tool returns a full cross-source profile of a US public company, listing specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and fields. It distinguishes from sibling tools like resolve_entity by naming when to use that 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?

Provides explicit trigger phrases ('Tell me about X', 'research Acme', etc.) and instructs to prefer this tool over chaining single-pack lookups. Also directs to use resolve_entity first if only a name is available, offering clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructive and idempotent behavior. Description adds context on appropriate usage (clearing stale or sensitive data), complementing 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, no wasted words, front-loaded 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?

Simple tool with one parameter and no output schema. Description covers purpose, usage guidance, and relationship to sibling tools. Fully adequate.

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

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

Schema has 100% coverage with description 'Memory key to delete'. Description does not add additional 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?

Clearly states 'Delete a previously stored memory by key' with specific verb and resource. Distinguishes from siblings like remember and recall by focusing on deletion.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with remember and recall.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as true/false. The description adds process details (fetches page, extracts title/description/key links, outputs markdown) and the output format. However, it does not disclose potential limitations like page size constraints or error handling, which would be needed without 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 long, front-loaded with the primary purpose, and contains no redundant information. Every sentence adds value, making it highly concise and well-structured.

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

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

Despite lacking an output schema, the description clearly states the output format ('single text blob ready to drop at site-root/llms.txt'). It also describes the process and use cases, ensuring completeness for a relatively simple tool with 2 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?

Input schema has 100% description coverage for both parameters (url and max_links). The description does not add any additional semantic information beyond what the schema already provides, hence baseline score of 3.

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

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

The description explicitly states 'Generate a production-ready llms.txt file for any URL', clearly identifying the verb, resource, and target. It also explains the tool's purpose for AI crawlers, effectively distinguishing it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description lists specific use cases: getting a client's site indexed, drafting for own project, auditing competitors. This provides clear context for when to use the tool, though it does not explicitly mention when not to use or alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by listing the return fields, which is beyond the annotations.

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

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

Two sentences, zero waste. First sentence states purpose and returns, second gives usage guidance. Front-loaded and efficient.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage context. It is complete and self-sufficient.

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 only parameter 'include_inactive' is well described in the schema. The description implies it lists active subscriptions, but adds no extra meaning 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 it lists the caller's active subscriptions and specifies the return fields. It does not explicitly differentiate from sibling 'stripe_list_subscriptions', but the context implies a different system.

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 this to review what you're monitoring before adding more or to find an id to cancel.' It does not mention alternatives or exclusions.

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

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

Annotations provide no safety hints (readOnlyHint, destructiveHint all false), so description carries the burden. It discloses the rate limit (5 per identifier per day), that it's free and doesn't count against quota, the claim_token workflow for follow-up, and that the team reads digests daily. This gives agents a clear model of side effects and usage constraints.

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 every sentence earns its place. It is front-loaded with the core purpose, then exclusions, then usage mechanics and constraints. No filler or redundancy; the length is justified by the tool's complexity.

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

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

Given the tool's complexity (4 optional params, nested object, no output schema), the description is complete. It explains the return token and how to use it later, defines feedback categories, and provides clear guidance on scope and content. Agents have enough information to invoke it correctly without further documentation.

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

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

Schema coverage is 100% (every parameter has a description), so baseline is 3. The description adds value beyond schema by explaining how to use claim_token across calls (pass it back with no other args to read status) and what to avoid in message (don't paste end-user prompt). This raises it to 4.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly maps to feedback categories (bug, feature/data_gap, praise) and is distinct from sibling tools which are research or Stripe operations. The verb 'Tell' and resource 'Pipeworx Feedback' are specific.

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

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

The description gives explicit when-to-use guidance (tool returns wrong data, missing tool, praise) and when-not-to-use guidance (if the tool came from a different MCP server, file with that server instead). It also tells how to scope feedback to Pipeworx tools/packs, which is actionable and 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, and destructiveHint=false. The description adds transparency by stating the data source ('CF analytics-engine'), lack of PII, and caching behavior ('Cached 5min-1h depending on window'), which is valuable beyond the annotations.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by a bulleted list of use cases and a final sentence on technical details. Every sentence earns its place with zero redundancy.

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

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

Given the tool's simplicity (single optional parameter, no output schema) and rich annotations, the description fully covers what is returned (top tools, packs, volume), the window options, and caching behavior. Nothing essential 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% and includes a description for each parameter. The description enhances this by explaining the trade-off between window lengths ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), adding practical meaning.

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

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

The description clearly states the verb 'Returns' and specifies the exact resources ('top tools, top packs, and total call volume') with the time window parameter, distinguishing it from sibling tools like 'discover_tools' or 'ask_pipeworx'.

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

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

The description lists three concrete use cases (discovering hot data sources, confirming canonical tool choice, aligning use case with demand) and explains the effect of different windows, providing clear context for when to use this tool, though it 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?

The description discloses extensive behavioral details: monotonicity checks, partition-sum checks, similarity filtering, placeholder filtering, fill checking, and output structure. Annotations already indicate read-only and idempotent, and the description adds context 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?

The description is comprehensive but somewhat lengthy. It is well-organized and front-loaded with the main purpose. Minor trimming could improve conciseness, but overall it efficiently conveys necessary 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 the tool's complexity with two parameters and no output schema, the description is remarkably complete. It covers algorithm details, filters, response structure, fill check, and usage 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?

Input schema has 100% coverage with descriptions for both parameters. The description adds significant value by explaining parameter usage, examples (e.g., 'fed-decision-may-2026'), and behavior differences between event and topic modes.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: 'use this if you know the specific Polymarket event' for event mode, and 'use this if you want to scan related events across the platform' for topic mode. Includes recommendations for fill check and mentions polymarket_fill_risk for custom sizing.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds extensive behavioral context: caching details (1h KV-level keyed on all knobs), edge calculation methodology (Kelly fractions, slippage, liquidity filters), response structure with diagnostics (e.g., filter_skips for empty segments), and caveats like 'your edge may already be in the price' with 24h move warnings.

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 detailed and well-structured with sections (e.g., 'TRADEABLE-EDGE KNOBS', 'RESPONSE TOP-LEVEL'), but it is lengthy. While every sentence adds value, the length could be reduced without losing key information. The verbosity earns a score of 3.

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

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

Despite having no output schema, the description fully explains the response structure (by_segment, fed_candidates, _diagnostics), including edge cases like why a segment might be empty. It covers all relevant aspects for an agent to understand what the tool returns and how to interpret results, making it complete given 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?

All 9 parameters have descriptions in the schema (100% coverage). The description adds value by explaining parameter interactions, such as the difference between min_kelly and min_partition_leg_kelly, and how slippage_pp is subtracted from raw edge. However, the schema already does a good job, so the description is supplementary rather than essential.

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

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

The description uses specific verbs and resources: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from sibling tools like polymarket_arbitrage by detailing three distinct segments and caching behavior.

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

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

Explicitly states 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It describes when to use tradeable-edge knobs and mentions Fed bets are excluded from ranking. However, it does not explicitly state when not to use this tool versus specific siblings.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds extensive detail: it explains the return structure (tracked, expired, snapshot_dates), field meanings (trend, decay_pp_per_day, lifespan_days), and limitations (snapshot TTL, decay calculation). 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 well-structured and front-loaded with the key question. It is somewhat lengthy but each sentence adds value, covering purpose, parameters, response format, and limits efficiently.

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 absence of output schema, the description fully explains the return values (tracked array fields, expired array fields, snapshot_dates). It also covers edge cases (gaps, clamping) and limitations, making it complete for an AI 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?

Both parameters (days, window) are fully described in the schema. The description adds context by explaining their roles (lookback, snapshot family) and defaults/clamps, providing more than the schema alone.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses a specific verb ('answers') and resource ('edge persistence and decay telemetry'), and distinguishes from siblings like polymarket_edges by focusing on historical trend analysis.

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

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

The description implies when to use this tool (to analyze edge longevity) but does not explicitly state when not to use it or provide direct comparisons to sibling tools. However, it includes limitations (e.g., 60-day TTL) that guide appropriate usage.

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

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

Annotations indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: it explains that the tool walks the order book ladder, returns specific metrics like slippage and fill details, and warns about thin books and unhedged positions, all 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?

The description is well-structured with clear sections for single-market and basket modes, but it is verbose with multiple paragraphs and repetitive detail. While informative, it could be more concise to allow quicker parsing by an AI agent.

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

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

Given the lack of an output schema, the description thoroughly explains return values for both modes, including specific fields like vwap_fill_price and capture_ratio. It also covers usage context and risks. This makes the tool largely self-contained, though exact field names in the output are not listed.

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

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

Schema coverage is 100% with parameter descriptions. The description adds significant meaning by explaining default behaviors (e.g., side auto-detection in basket mode) and different interpretations of size_usd for single-market vs basket. This goes beyond the schema, justifying a score above the baseline of 3.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two distinct modes (single-market and basket). This specificity differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly instructs to 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns against using it for partial basket fills, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations indicate the tool is read-only, idempotent, and non-destructive. The description goes beyond annotations by explaining the conditions that trigger compatibility_warning (e.g., mismatched bet shapes, semantically unrelated events) and temporal_alignment, which directly impacts the validity of spreads.

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 (two modes, response fields, safety fields) but is somewhat lengthy (approx. 150 words). While every sentence adds value, a more concise version could still maintain clarity.

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

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

Given the tool's complexity (3 parameters, no enums, no output schema), the description fully covers the response structure (leg-by-leg prices, top spreads, compatibility_warning, temporal_alignment, skipped counters). It leaves no critical behavioral aspect unexplained.

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?

All three parameters are described with clear semantics in the input schema, and the description adds context by listing the exact shortcut values for 'topic' and how 'kalshi_event_ticker' and 'polymarket_event_slug' override the mapped sides. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It explicitly distinguishes two modes (topic shortcuts and explicit tickers) and differentiates from sibling tools like polymarket_arbitrage by focusing on the spread between venues.

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

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

The description provides detailed guidance on when to use each mode, including a warning that most pre-mapped topics return compatibility warnings and are not tradeable. It effectively sets expectations and helps the agent decide whether the tool will produce meaningful results.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scoping by identifier and pairing with remember/forget, which is useful context.

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

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

Three sentences, no wasted words. Front-loaded with core purpose, then usage context, then scope. Every sentence earns its place.

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

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

Given one optional parameter and no output schema, the description fully covers behavior, use cases, and relationships. No gaps.

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

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

Schema coverage is 100% with description for 'key'. Description adds meaning by explaining that omitting key lists all, which is not in the schema description.

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

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

The description clearly states the verb (retrieve/list), resource (saved values/keys), and distinguishes from sibling tools '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?

Provides explicit usage guidance: use for looking up context stored earlier, omit key to list all. Does not explicitly state when not to use, but context makes it 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 contradicts the readOnlyHint annotation by describing the mark_read parameter that flags events as read, implying a state change. Despite being transparent about the side effect, the contradiction forces a score of 1 per rules.

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

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

The description is concise with four sentences, front-loaded with the primary action, and each sentence adds necessary information without redundancy.

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

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

Given the tool has 5 optional parameters and no output schema, the description covers what is returned (source, citation_uri, raw payload), filtering options, mark_read side effect, and alternative access. It is largely complete but could clarify unread_only purpose more than the schema already does.

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 default limit (50), range (1-200), and the effect of mark_read for filtering future calls, which exceeds the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed with specific verb 'pull' and resource 'fired events from subscription feed'. It is specific enough, but does not explicitly distinguish from sibling tools like list_subscriptions, though the resource is different.

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 usage context: it returns recent alerts and mentions polling is fine, and an alternative for scripts/dashboards. However, it does not explicitly state when to use this tool vs alternatives like subscribe or list_subscriptions.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true. The description adds significant context: fan-out logic, fallback from GDELT to GNews, soft-fail for USPTO, date formats, and return structure. 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 dense but not overly long. It is front-loaded with user-facing examples. Could be slightly more structured, but all information is relevant and no sentences are wasted.

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

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

Despite lacking an output schema, the description explains the return structure (changes[] grouped by source, total_changes count, citation URIs) and covers all 3 required parameters with detailed semantics. Annotations provide additional safety traits, making the definition complete for an AI 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 covers 100% of parameters. Description adds meaning beyond schema: explains that 'type' only supports 'company', 'since' accepts ISO or relative shorthand with examples, and 'value' can be ticker or CIK. Provides typical usage guidance ('30d' or '1m').

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

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

The description clearly states the tool provides a change feed for a company over a time window, fanning out to SEC EDGAR, GDELT→GNews, and USPTO. It explicitly distinguishes from sibling entity_profile, which serves a different purpose (static 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 includes explicit query examples ('What's new with X', 'latest on Y') and provides a clear alternative ('Use entity_profile instead when you want the static profile'). It also gives typical values for the 'since' parameter.

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 idempotentHint=true and destructiveHint=false. The description adds that data is scoped by the agent's identifier, persistence differs by authentication (persistent vs. 24-hour), and the key-value pair nature. 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?

Extremely concise: three sentences. The first sentence states the core purpose, the second gives usage guidance, and the third adds behavioral details. Every sentence adds value with no redundancy.

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

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

With 100% schema coverage, no output schema needed, and simple tool, the description fully covers purpose, when to use, persistence behavior, and pairing with siblings. No gaps.

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

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

Schema covers both parameters with descriptions. The description enriches by providing typical key naming conventions ('subject_property', 'target_ticker') and explains the value as arbitrary text, adding practical context 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 ('Save') and resource ('data') with specific examples of what to store (resolved ticker, address, preference). It differentiates from sibling tools 'recall' and 'forget' by specifying the action of storing.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and gives concrete usage scenarios. Also mentions pairing with 'recall' to retrieve and 'forget' to delete, providing clear guidance on when and how to use this tool.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, and explicit handling of unresolved identifiers under an `unresolved` field. This is rich behavioral context that 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 description is long but well-structured with example phrases, a clear 'Use FIRST' directive, and a breakdown of supported types. Every section provides useful context, though some redundancy exists (e.g., repeated mention of fallback behavior) that could be trimmed slightly.

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

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

With no output schema, the description effectively communicates what the tool returns: canonical identifiers with source labels, `unresolved` reporting, and citations for drugs. It also covers input variations and degradation behavior, making it self-sufficient for the agent to use correctly.

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

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

Schema coverage is 100% and includes per-parameter descriptions. The description adds value by explaining the output identifiers produced for each type (CIK, LEI, FIGI for company; RxCUI for drug) and by noting accepted input formats, which goes beyond the schema's basic 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 description is explicit: it resolves user-spoken names to canonical identifiers, with concrete examples like tickers, CIKs, LEIs, and RxCUs. It clearly distinguishes from siblings by stating 'Use FIRST whenever you have a name but need an ID' and lists supported types (company, drug).

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 direct usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains when the tool is applicable (name→identifier) and notes graceful degradation of LEI/FIGI enrichment, helping the agent decide when to use it despite external service issues.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint false. Description adds that it probes each entity and ranks, and mentions output format. No contradictions; adds useful context beyond annotations.

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

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

Four concise sentences, front-loaded with verb 'Compare', then explains mechanism, use case, and output. 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?

Covers purpose, internal mechanism, and output format (ranked list with score, confidence, signal density). Could explicitly state descending sort order, but overall sufficient given schema coverage and no output schema.

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

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

Schema description coverage is 100%, so baseline is 3. Description only mentions 'your brand + N competitors' but doesn't detail parameters. Schema provides full parameter explanations, so description adds minimal extra meaning.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It differentiates from sibling ai_visibility_check (single entity) and compare_entities (generic) by specifying the domain and internal mechanism.

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 use case: competitive AI-marketing audits with example question 'does Claude know about us as well as our competitors?'. However, does not explicitly state when to avoid using it (e.g., for single entity use ai_visibility_check).

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?

Describes composite fan-out behavior, partial failure handling (graceful degradation, bundlephobia first measurement 5-30s, sources_failed list), and the return structure (summary, advisories, links, alternate versions). Annotations provide idempotentHint and readOnlyHint, and the description adds context beyond them 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?

The description is a single dense paragraph that front-loads the core purpose ('composite “should I add this npm package to my project” check') and then adds details. While not broken into sections, every sentence contributes value without redundancy.

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

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

Given the moderate complexity (2 parameters, no output schema), the description fully informs the agent about what the tool does, its inputs, behavior, and return structure (summary block, per-advisory detail, links, recent alternative versions). 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 covers both parameters (package and version) with descriptions. The description does not add additional parameter details beyond what the schema provides, so baseline 3 is appropriate. It mentions default version behavior and scoped packages, but this is already in 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 it is a composite check combining deps.dev and bundlephobia data to answer if an npm package is safe/popular/small. It distinguishes from sibling tools by specifying the exact ecosystem (NPM) and mentioning alternatives for other ecosystems.

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: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". Also notes NPM-only in v1 and directs to deps.dev:version for other ecosystems, giving clear guidance on alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds critical operational details: embedding model (BGE-base-en), similarity measure (cosine), chunking (500-char windows), character cap (200K with truncation flag), and output features (character offsets for verification). 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 information-dense but not overly long. It front-loads the core purpose, then usage guidance, then technical details. Every sentence adds value, though a slight trim could be possible.

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 fully compensates by explaining output format (passages, offsets, scores), limitations (200K char cap, truncation), and integration with sibling tools. It leaves no major questions for an AI agent to invoke correctly.

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

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

Schema descriptions cover all 3 parameters (100% coverage). The description adds valuable context: maximum text length for 'text', default and range for 'limit', and natural-language query examples for 'query'. This exceeds schema but doesn't add entirely new info.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and specifies inputs (text, query) and outputs (passages with offsets and scores). It distinguishes itself from siblings like 'ask_pipeworx_grounded' by explaining the pairing.

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

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

Explicitly says when to use it: 'when the record is too big to cram into the prompt' and how it saves context. It also directly names an alternative ('ask_pipeworx_grounded') and explains when to use each in concert.

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 no additional behavioral context beyond restating the purpose, thus providing no extra value over 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?

Single sentence, front-loaded with the key action, concise, and no extraneous text. Ideal for a straightforward tool.

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

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

Given the simplicity (one parameter, no nested objects, output schema present) and rich annotations, the description is adequately complete for an agent to use the tool correctly.

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

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

Schema coverage is 100% with a single parameter (_apiKey) fully described in the schema. The description does not reference parameters, but the baseline of 3 is appropriate since the schema handles the documentation.

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 the resource 'current Stripe account balance', which is specific and distinct from sibling tools like stripe_get_customer or stripe_list_charges.

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?

No explicit guidance on when to use this tool vs alternatives. However, the simplicity and uniqueness of the tool (only one parameter, retrieving a single value) reduces the need for extensive disambiguation.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false. The description adds no additional behavioral context beyond stating the action, so it does not enhance transparency.

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, efficient sentence with no wasted words. It is front-loaded and to the point.

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 existence and comprehensive annotations, the minimal description is sufficient for a simple get-by-ID tool. It lacks mention of edge cases but is complete enough for typical use.

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

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

Schema description coverage is 100%, with both parameters adequately documented. The description does not add meaning beyond the schema, meeting the baseline but not exceeding it.

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

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

The description 'Get a Stripe customer by ID' uses a specific verb and resource, clearly distinguishing it from sibling tools like stripe_list_customers or stripe_get_balance.

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?

No explicit guidance on when to use this tool vs alternatives (e.g., stripe_list_customers for multiple customers). The description implies usage when an ID is available, but lacks exclusions or context.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds that it returns specific fields and supports pagination, which is useful but not extensive. No contradiction.

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

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

Two concise sentences with front-loaded purpose. Every word is relevant and efficiently conveys key information without extraneous text.

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

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

Given the presence of output schema and clear annotations, the description covers purpose, filter, pagination, and return fields. Missing details like status meanings are likely in the output schema, making it complete enough for a list tool.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats information already in the schema (limit range, default; customer filter) without adding new semantic context. Adequate but not enhanced.

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 lists Stripe charges, specifies optional filter by customer ID, and mentions return fields. It distinguishes from sibling tools like stripe_list_customers and stripe_list_invoices by focusing on charges.

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 indicates when to use the tool (to list charges) and mentions optional filtering and pagination. It does not explicitly contrast with alternatives, but the context is clear for a simple list 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 declare readOnlyHint=true and destructiveHint=false, so the agent knows it's safe. The description adds pagination behavior, but this is also evident from the schema. No additional behavioral traits are disclosed beyond what annotations and schema provide.

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

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

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

Given the rich annotations, complete schema coverage, and presence of an output schema, the description is sufficiently complete. It covers the listing and pagination functionality. However, it could mention that it returns a list of customer objects, though the output schema likely covers this.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (limit, _apiKey, starting_after) with examples. The description adds no additional meaning 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 'List Stripe customers' with a specific verb and resource, and mentions pagination support, which distinguishes it from sibling tools like stripe_get_customer or other list 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 implies usage for listing customers with pagination but provides no explicit guidance on when to use this tool over alternatives like stripe_list_charges or stripe_list_invoices, nor does it mention 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 fully cover safety traits (read-only, idempotent, non-destructive). The description adds value by listing return fields (invoice ID, amount due, etc.), providing extra context beyond 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: first states action and filters, second lists return fields. No wasted 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?

With output schema present, the description's mention of return fields is optional but adds clarity. It covers all essential aspects: action, filters, required parameter (_apiKey implied), and output summary.

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 parameters are already well-documented. The description reiterates filtering by customer and status but does not add significant new meaning 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 'List Stripe invoices' with specific verb and resource. It also mentions optional filtering by customer ID and status, distinguishing it from sibling tools like stripe_list_charges.

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 through filtering options but does not explicitly state when to use this tool versus alternatives like stripe_list_charges or stripe_list_subscriptions. Context is clear but lacks exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description goes beyond these by detailing authentication via _apiKey, the optional filters, the limit range, and the exact return fields (subscription id, customer, price/plan items, status, current period). It does not mention pagination or rate limits, but still adds meaningful behavioral context.

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

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

Three sentences front-loaded with the primary action, followed by a compact listing of return fields and a concise user-facing summary. Every sentence contributes useful information without redundancy.

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

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

The description covers purpose, authentication, filters, limit, and return content. Since an output schema exists and annotations are strong, the description provides all necessary context for an agent to select and invoke the tool correctly.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by enumerating valid status values (active, canceled, past_due, trialing, unpaid), the limit range (1-100), and clarifying that _apiKey is a 'Stripe secret or restricted key.' This goes 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 specifies 'List subscriptions on a Stripe account via the Stripe API' with a clear verb+resource, and includes the user-facing goal 'Answers who is subscribed to a Stripe billing plan and on what terms.' It distinguishes itself from sibling tools by naming Stripe and the API endpoint.

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

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

Provides clear context: it operates on a Stripe account, requires an API key, and supports filters. However, it does not explicitly mention when to prefer this over sibling tools like list_subscriptions or stripe_list_invoices, so it falls short of full exclusions/alternatives.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, but description adds critical context: OAuth requirement, 10/day SMS cap, webhook auto-disable after 10 failures, and secret-once delivery. 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?

Somewhat lengthy but justified by complexity. Front-loaded with main purpose. Could trim minor redundancies, but every sentence adds essential information.

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

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

Given complexity (3 params, nested objects, 5 types, 3 delivery channels), description covers all preconditions, constraints, and return value. No output schema needed as subscription id is 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%, baseline 3. Description adds significant value by explaining type-specific parameters (e.g., SEC items codes, Polymarket topic, FRED series ID) and delivery channel details including webhook HMAC signing.

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

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

Description clearly states 'Create a proactive monitoring subscription' and specifies return of subscription id. Distinct from sibling tools like 'unsubscribe' and 'list_subscriptions'.

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

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

Provides explicit context: requires Pipeworx OAuth account, anonymous/BYO cannot persist. Details supported types and delivery channels. Does not explicitly state when to avoid using this tool, but gives sufficient guidance.

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

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

The description adds substantial behavioral context beyond the annotations. It explains that the tool returns 'category-bucketed example questions' and that each comes with the 'exact tool + argument shape that answers it, drawn from the live catalog of thousands of tools.' It also clarifies that it is the onboarding entry point, which aligns with readOnlyHint and idempotentHint 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?

The description is slightly verbose with parenthetical examples and multiple questions, but the key information is front-loaded. It could be trimmed slightly, but the structure is clear and each part earns its place.

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

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

Given the tool has only one optional parameter and no output schema, the description is fully complete. It explains what the tool returns, how to use it, and its role in the broader tool ecosystem. There are no gaps and no need for additional information.

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

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

The input schema has 100% coverage and the description adds significant meaning: it lists example topic values ('finance', 'pharma', etc.), explains the effect of omitting vs passing topic, and frames the parameter as 'focus area'. This goes beyond the schema's minimal description, providing rich semantic context for the agent.

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: it is the onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from sibling tools by explicitly mentioning meta-tools like ask_pipeworx, entity_profile, etc., and frames its role as a 'first-use' 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 explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', providing direct when-to-use guidance. It also explains two usage modes: no arguments for full spread, or pass `topic` to focus. This effectively tells the agent when and how to invoke 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 indicate mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). Description adds crucial context: ownership enforcement and that rows are deactivated not deleted, which complements annotations. No contradiction.

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

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

Two sentences, front-loaded with purpose, no filler words. Every sentence adds value: cancel, ownership, deactivation behavior and link to recent_alerts.

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 single required parameter, no output schema, and simple operation, description fully covers purpose, constraints, and side effects. Hints at related tool 'recent_alerts' for historical data.

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 for 'id' already present. Description adds no extra parameter meaning beyond 'by id', so baseline score of 3 is appropriate.

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

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

Description clearly states it cancels a subscription by id, uses specific verb 'Cancel' and resource 'subscription'. It distinguishes from siblings like 'subscribe' and 'list_subscriptions', and adds ownership and deactivation 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?

Explicitly states ownership enforcement, indicating you can only cancel your own subscriptions. Also mentions deactivation keeps historical events via recent_alerts, but lacks explicit when-not-to-use or alternative tool references.

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 annotations, the description discloses the full verdict taxonomy, the crucial distinction between could_not_verify (failure, not evidence) and unsupported (no source coverage), and the internal EDGAR vs. grounded pipeline routing. It also warns callers about misusing could_not_verify, which is valuable behavioral context.

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

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

The description is dense but well-structured: trigger phrases, use case, routing, return values, warnings. Every sentence provides necessary context, though it is longer than the ideal two-sentence style. The front-loading of trigger phrases helps quick scanning.

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

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

With no output schema, the description fully compensates by listing all six verdict values, the return of actual value with citation and reasoning, and the verification_error structure. It also covers the two-path routing and the performance benefit, leaving no major gaps for a caller.

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

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

The input schema provides 100% coverage with detailed descriptions for both parameters, so the tool description doesn't need to add parameter-level detail. The baseline of 3 is appropriate; the description itself adds no param semantics beyond what the schema already states.

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 exact natural-language trigger phrases ('fact check', 'verify the claim') and defines the resource as authoritative sources, making the tool's purpose unmistakable. It distinguishes itself from sibling research tools by focusing on verdict-based claim verification (confirmed/refuted/etc.) and explicitly replaces a 4–6 call 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?

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides routing rules for financial vs. other claims. However, it does not name specific sibling tools or state when not to use it, so it stops just short of a perfect score.

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