Sf Recpark

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

Annotations indicate safe, read-only, idempotent behavior. The description adds value by detailing default model, cost implications for Anthropic, and return structure (per-model + combined view). No contradictions.

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

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

The description is two sentences, front-loaded with purpose, and includes all essential information without fluff. 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 no output schema, the description adequately explains return values (score, confidence, signals, raw_response per model plus combined view). It covers all needed context for a tool with 4 parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema: explains default model, that _apiKey is only needed with anthropic, and context helps disambiguate. This justifies a score above baseline.

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

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

The description clearly states the tool probes LLMs for visibility of a business/brand/product/topic and returns a score. It distinguishes itself from sibling tools like deep_research and scan_competitor_ai_presence by focusing on visibility scoring per model.

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

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

The description provides clear context for when to use (AI-marketing audits, pre-launch brand checks) and explains API key usage for Anthropic. It lacks explicit alternatives or when-not-to-use guidance, but the purpose is well-defined.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond annotations: it explains that the tool does not answer queries itself but routes them to a downstream tool, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. This gives the agent a clear mental model of the delegation behavior.

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

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

The description is overly long and repetitive. It contains duplicated phrases like 'START HERE for most questions — even if web search could also answer it', which appears both at the start and end. It also includes raw HTML tags like '</br>' and the second paragraph appears garbled/concatenated. The core message is buried in redundancy, so it fails the 'every sentence earns its place' test.

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

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

For a complex meta-router with no output schema, the description does explain the key behavior (routing, argument filling, citation URIs) and gives a broad domain list. However, it omits important operational details: what happens if no matching tool exists, whether results are always available, and how to distinguish this tool from ask_pipeworx_grounded/beta. These gaps matter given the tool's complexity 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%: all six parameters are documented as aliases for 'question'. The description does not add parameter-specific meaning, but it does provide example questions that implicitly show expected input format. This is the baseline acceptable score when the schema already covers semantics.

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

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

The description clearly states a specific verb and resource: 'Routes the question to the right one of 5,710 tools across 1494 verified sources' and 'returns the structured answer with stable citation URIs'. It strongly differentiates from web search. However, it does not explicitly distinguish itself from sibling tools like ask_pipeworx_grounded or ask_pipeworx_beta, so it falls just short of a 5.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and lists concrete trigger phrases and examples. It also gives a when-not-to-use signal via 'even if web search could also answer it', favoring this tool. But it does not mention alternatives among sibling tools or conditions to choose them, so it lacks full when/when-not/alternatives coverage.

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 important operational behavior beyond the annotations: the beta status, that no candidate is currently active, that it currently matches ask_pipeworx exactly, and that it is a full working router rather than a fallback stub. This gives the agent essential context for interpreting results and reliability expectations.

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

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

The description is front-loaded with the tool's identity and beta status, and each sentence contributes actionable context. The repeated emphasis on 'identical' and 'matches exactly' is slightly redundant, but the description remains efficient and readable.

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

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

The description covers current runtime state, relationship to the stable router, expected response shape, and usage intent. Given the simple all-alias schema and read-only/idempotent annotations, the agent has everything needed to invoke this tool correctly.

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

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

Schema description coverage is 100%, with all parameters documented as aliases for 'question', so the description does not need to explain parameter meaning. It adds a useful cross-reference to ask_pipeworx's arguments, but no additional semantic detail 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 identifies the tool as a beta version of ask_pipeworx, an identical universal router with the same 5,710 tools, arguments, and response shape. It distinguishes itself from ask_pipeworx by framing this as the experimental edge versus the stable router, so an agent can tell them apart.

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 to use it exactly like ask_pipeworx when you want the newest routing, and names ask_pipeworx as the stable comparison router. It does not explicitly state when not to use it, such as preferring the stable version for production-critical queries, so it falls just short of full when/when-not guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent hints, but the description adds rich behavior beyond them: the success return shape with verbatim evidence, the explicit refusal contract with five enumerated refusal_reason values, the grounding guarantee ('EXTRACTS the answer using ONLY what the tool result contains'), and the extra-LLM-call cost trait. 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?

Dense but every sentence earns its place: purpose, mechanism, success shape, refusal contract, use cases, cost tradeoff. The key differentiator ('Hallucination-resistant... Same routing as ask_pipeworx') is front-loaded, and the decision-relevant cost comparison closes the description. Logical flow from what → how → returns → when.

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 present, the description carries the full burden of explaining return values — and it does, enumerating both the success object (answer, evidence, confidence, source, fetched_at) and the refusal object with all refusal_reason values. Combined with explicit usage guidance and cost/behavior tradeoffs, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the input schema already documents all six parameters, including the question parameter's aliases (query, q, prompt, text, input). The description adds no parameter-specific semantics beyond the schema, which meets the baseline 3 for high-coverage schemas.

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

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

The description opens with a specific purpose — 'Hallucination-resistant answer mode for high-stakes reads' — and explains the full mechanism: routing through the tool corpus, fetching data, and extracting the answer only from tool results. It explicitly distinguishes itself from the sibling ask_pipeworx by naming it and its cost delta, so an agent can tell them apart without opening schemas.

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

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

Explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete domains (financial verdicts, legal claims, medical lookups, public statements). Explicit when-not-to-use: 'prefer ask_pipeworx for casual lookups,' naming the alternative and the reason (one extra LLM call).

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

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

The description goes far beyond the annotations, detailing resolution logic, fan-out behavior, response shapes, edge cases (closed markets, low confidence, wide spreads), and resolution-rule risk. All disclosed behaviors align with annotations (readOnlyHint, idempotentHint), and no contradictions are present.

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

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

The description is dense and verbose, containing extensive technical details and examples. While structured with sections and key terms, its length reduces conciseness. Every sentence adds value, but the overall size could be trimmed for agent efficiency.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly explains return values (result.market, result.analysis, result.evidence), resolver contract, parent_event extractor, news fields, and safety mechanisms. It covers all necessary context for correct agent invocation.

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

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

Schema coverage is 100%, and the description adds significant meaning: it explains that 'market' accepts slug, URL, or question text; 'depth' enum with default; 'include_raw' with usage guidance. This deepens understanding beyond the schema descriptions.

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

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

The description clearly states that the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and provides example use cases. However, it does not explicitly differentiate this tool from siblings like ask_pipeworx or polymarket_edges, limiting its distinctiveness.

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

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

The description explicitly states when to use the tool ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides extensive context on safety and blockers. It lacks explicit 'when not to use' statements, but the use cases are clearly implied.

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: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradictions with annotations.

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

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

The description is informative and well-structured with examples and key points. While slightly verbose with multiple example phrases, it remains efficient and front-loaded with the core purpose.

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

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

Without an output schema, the description explains return values (paired data + citation URIs) and sorting. It covers off-calendar handling and metrics. Omits exact structure of paired data but is sufficient for a comparison tool.

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

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

Schema coverage is 100% with descriptions, but the description adds valuable context: explains how to format values (tickers/CIKs for companies, drug names for drugs), what data each type retrieves, and the sorting behavior. This adds 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 the tool's purpose: compare 2-5 entities (companies or drugs) in a single call, with specific data sources and metrics. It uses specific verbs like 'compare' and 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 states 'ALWAYS PREFER over sequential single-pack lookups', providing clear when-to-use context. It also specifies limits (2-5 entities) and implies when not to use (single entity lookups, which have sibling tool 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?

Annotations already mark it read-only, open-world, idempotent, and non-destructive, and the description adds substantial context without contradicting them: it requires an account, has a paid tier, never invents answers, includes gaps[] and contradictions[], uses semantic excerpting, and reports latency expectations. This is far beyond what the annotations alone convey.

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

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

The description is long but front-loaded: the account requirement and alternative are first, followed by core behavior, output format, depth distinctions, and latency. However, it repeats the findings-packet definition and the ask_pipeworx alternative, and the depth explanations partially duplicate the schema, so it is not maximally tight.

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

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

With no output schema, the description must explain return values, and it does: findings[], gaps[], timings[], contradictions[], with fields like verbatim evidence, confidence, source, fetched_at, citation_uri, and hop. It also covers account tier constraints, data source scope, and runtime expectations, so nothing an agent needs to invoke it correctly is missing.

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

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

The input schema already documents both parameters thoroughly (100% coverage), so the baseline is 3. The description adds useful depth-specific context—thorough requires a paid plan, standard/thorough add a contradiction scan, quick does not—and ties time expectations to depth values. This is meaningful but not a complete re-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 opens with a concrete verb and resource: 'Grounded multi-source research across Pipeworx's 1494 STRUCTURED data sources' and states it decomposes questions and routes them to 5,710 tools in parallel. It explicitly distinguishes itself from open-web search and from ask_pipeworx for single lookups, making it clear what this tool is and what it isn't.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx instead.' Also gives an alternative based on auth state: 'If you are not signed in, use ask_pipeworx instead.' No ambiguity about when to choose this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing that results are ready-to-call with full schemas and that no second lookup is needed, beyond what annotations provide. 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?

Mostly concise with front-loaded purpose and usage. The list of example domains is somewhat verbose but adds helpful context. Every sentence serves a clear role, and the structure flows logically from purpose to behavior to usage.

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

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

Given no output schema, the description adequately explains the return value (top-N tools with names, descriptions, schemas). It covers parameters and usage but does not address error handling or pagination, which are acceptable gaps for a search tool.

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

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

Schema description coverage is 100%, so the description does not need to add much. It restates parameter purpose and aliases already documented in the schema. The examples in the description mirror those in the input schema, providing no additional semantic depth.

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 uses specific verb 'find' and resource 'tools', clearly distinguishing the tool as a discovery mechanism. It explicitly states it returns tool names, descriptions, and schemas for direct use, setting it apart from sibling tools that perform specific data retrieval or 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?

Provides explicit scenarios: 'Use when you need to browse, search, look up, or discover what tools exist for' and 'Call this FIRST when you have many tools available.' While it does not explicitly list alternatives, the guidance is clear on when to use this tool for exploration rather than direct invocation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds behavioral details like parallel execution, soft-fail for patents (USPTO sunset), and specific return fields, enhancing understanding beyond annotations.

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

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

Description is somewhat lengthy but front-loaded with example queries. Every sentence adds value, though minor redundancy could be trimmed. Overall well-structured.

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

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

Despite no output schema, the description comprehensively details all return fields, fallback mechanisms, and soft-fail behavior. For a complex multi-source tool, this provides sufficient context for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with clear descriptions for both parameters. Description adds value by giving concrete examples (e.g., 'AAPL' or '0000320193') and clarifying that names are not supported, which aligns with schema but provides extra context.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company, listing specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields. It distinguishes from siblings like resolve_entity by noting to use that first if only a name is available.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack...' when a holistic view is needed, and provides example queries. Also states when not to use: if you only have a name, use resolve_entity first.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds domain-specific context (upcoming, free/outdoor/community civic) and filtering capabilities, enhancing transparency beyond annotations.

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

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

The description is concise (two sentences), front-loaded with the main purpose, and contains no superfluous information. Every sentence contributes.

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 and the richness of annotations and schema, the description provides sufficient context. Lack of output schema is mitigated by the straightforward return of event listings.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that the query applies to title/location/description and providing examples, which complements the schema's parameter descriptions.

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

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

The description clearly states the tool's purpose: retrieving upcoming San Francisco Rec & Park events, with filtering by date and keyword. It specifies the resource and actions, distinguishing it from unrelated siblings.

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

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

The description indicates when to use the tool (for SF Rec & Park events, free/outdoor/community civic events) but does not explicitly state when not to use or mention alternatives. The sibling list shows no competing event tools.

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

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

Annotations already indicate destructiveness (destructiveHint=true) and idempotency (idempotentHint=true). The description adds context about specific use cases like sensitive data clearing, which aligns with and enriches the 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, zero waste. Front-loaded with the action and immediately provides usage guidance. Every sentence adds value.

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

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

For a simple tool with one parameter, clear annotations, and no output schema, the description is complete. It covers purpose, usage, and relationship to sibling tools.

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

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

Schema coverage is 100% with a well-described 'key' parameter. The description adds no further detail beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action (Delete), resource (previously stored memory), and mechanism (by key). It distinguishes from sibling tools 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 provides three scenarios when to use: stale context, completed tasks, clearing sensitive data. Also suggests pairing with related tools, offering clear guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds value by explaining the fetch-extract-emit behavior, confirming non-destructive nature. No contradictions.

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

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

Two sentences, first sentence front-loads purpose and output, second gives use cases. No fluff, but slightly more structure could improve scannability.

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

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

For a simple generation tool with two parameters, full schema coverage, and annotations providing safety profile, the description is fairly complete. It mentions output format and use cases, though return structure is not detailed.

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

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

Schema covers 100% of parameters with descriptions. The tool description does not add extra information about parameters beyond what schema provides, meeting baseline for high coverage.

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

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

Description uses specific verb 'Generate' and resource 'llms.txt file for any URL'. It clearly states the action (fetches page, extracts title/description/key links, emits markdown) and distinguishes from sibling tools which are unrelated.

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

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

Explicitly lists three use cases: getting a client's site indexed, drafting for own project, auditing competitor. While it doesn't give when-not-to-use, the context and sibling tools make usage 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, idempotentHint, destructiveHint. Description adds return field details, but behavioral traits are covered 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?

Two sentences, no unnecessary words. Front-loaded with purpose, then usage guidance. 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?

For a simple list tool with one optional boolean parameter and rich annotations, the description covers purpose, return fields, and usage context completely.

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

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

Schema coverage is 100% and the parameter 'include_inactive' is described in the schema. Description adds no additional parameter context 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?

Clearly states 'List the caller's active subscriptions' and specifies return fields. Differentiates from sibling tools like subscribe/unsubscribe by describing the listing action.

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

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

Explicitly advises using this tool to review monitored items before adding subscriptions or to find an id for cancellation, providing clear context.

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

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

The description reveals significant behavioral traits beyond the annotations: the claim_token mechanism for tracking feedback, rate limiting ('5 per identifier per day'), the fact it's free and doesn't count against quota, and the team's daily digest process. These add considerable context not available from structured fields. No contradiction with annotations was found.

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

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

The description is a single dense paragraph but every sentence provides necessary information: purpose, usage types, exclusions, token workflow, rate limits, and roadmap impact. It is front-loaded with the core action, and while long, it avoids redundancy. The structure is logical, though breaking it into bullet points could slightly improve scannability.

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

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

Given four optional parameters and no output schema, the description covers all essential aspects: what the tool does, when to use it, exclusions, token-based follow-up, rate limiting, and quota impact. It explains the return value mechanism (claim_token) and its subsequent use. For the tool's complexity, this is complete and leaves no critical gaps.

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

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

The input schema already provides 100% coverage of parameter descriptions, setting a baseline of 3. The description adds extra meaning by explaining the claim_token round-trip workflow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and giving guidance on what to avoid in messages ('don't paste the end-user's prompt'). This elevates it above the baseline.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific feedback types (bug, feature/data_gap, praise), distinguishing it from sibling tools like ask_pipeworx or discover_tools. The verb+resource structure is specific and unambiguous.

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

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

The description provides explicit when-to-use guidance for each feedback type and clearly states when NOT to use it: 'if the tool came from a different MCP server... file it with that server instead.' It also clarifies tool identity for uncertain cases: 'Pipeworx tool names are the ones this connection lists.' This exceeds typical usage guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds valuable context: data source (CF analytics-engine), no PII, cached 5min-1h. This goes beyond annotations.

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

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

Front-loaded with the core purpose, then bullet-like uses, then technical details. Every sentence adds value. 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?

For a read-only analytics tool with one parameter and no output schema, the description covers purpose, usage, window behavior, caching, data source, and privacy. Fully complete.

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

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

Schema has one optional enum parameter with basic description. Description adds meaning by explaining window effects (short vs long windows). Schema coverage is 100% but description adds substantial value.

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

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

The description clearly states the tool returns top tools, packs, and call volume over recent windows. It distinguishes from sibling tools like ask_pipeworx or discover_tools by focusing on trending analytics.

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

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

Explicitly lists three use cases (discovering hot data, confirming canonical tools, checking alignment). Also explains window selection trade-offs. Lacks explicit 'when not to use' but the positive guidance is strong.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral details: fill check, partition filter, semantic anchor, and conditions for trade validity (e.g., realizable_edge_pp <= 0 means do not trade). No contradictions.

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

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

The description is fairly long but well-structured with clear sections for each mode, and every sentence adds necessary detail. Could be slightly more streamlined, but the complexity of the tool justifies the 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 the complexity of multiple modes and no output schema, the description fully explains the return value structure (opportunities array with gap_pp, suggested_trade, etc.) and conditions like fill check. No obvious 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%, but the description adds significant value with examples (event slugs, topic phrases), explains full URL acceptance, and details the behavior for each parameter beyond the schema's basic 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 explicitly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific behaviors, making the purpose very clear.

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 each mode: 'Call with NO args for a trending_scan', 'pass event for...', 'pass topic for...'. Also references an alternative tool (polymarket_fill_risk) for custom sizing, but does not compare to all sibling tools.

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

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

The description discloses extensive behavioral details beyond the 4 annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It explains caching ('Cached 1h at the KV level keyed on all knobs'), response structure (by_segment, fed_candidates, _diagnostics), parameter effects (e.g., slippage_pp subtracted from |edge|, min_kelly filters single-leg opportunities), and edge conditions (24h-move warning). 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 thorough but lengthy, containing detailed explanations of model families and response segments that could be streamlined. While the structure is logical (purpose -> models -> output -> knobs -> diagnostics), the wordiness reduces conciseness. The front-loading of the purpose is effective, but some redundancy exists (e.g., tradeable-edge knobs are described both inline and in a dedicated section).

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

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

Given 9 parameters, no output schema, and complex nested response fields, the description is remarkably complete. It explains the response top-level structure (by_segment, fed_candidates, _diagnostics), caching behavior, and every parameter's effect and default. For a tool of this complexity, the description leaves minimal gaps, ensuring agents can understand invocation and output interpretation.

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

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

Schema coverage is 100%, so the schema already documents all 9 parameters. The description adds value beyond the schema by explaining parameter interactions (e.g., 'min_kelly ... Skips opportunities that are too small to bet sensibly even if the edge is large') and providing suggestions (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model'). This guidance aids correct invocation beyond basic schema definitions.

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

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

The description opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' clearly stating the resource (Polymarket markets) and action (scanning for edge opportunities). The detailed breakdown into five model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) distinguishes this tool from siblings like polymarket_arbitrage by specifying the proprietary Pipeworx methodology.

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 frames the tool for 'what should I bet on today' and details tradeable-edge knobs (min_liquidity, max_spread_pp, etc.) that guide parameter tuning. However, it lacks explicit when-to-use or when-not-to-use comparisons with sibling tools such as polymarket_arbitrage or polymarket_edge_tracker, requiring the agent to infer differentiation from the detailed model descriptions alone.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description goes far beyond, detailing the response structure (tracked[], expired[], snapshot_dates[]), field meanings (trend, decay_pp_per_day, lifespan_days), and limitations (60-day TTL, daily closes). This provides rich behavioral context beyond annotations.

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

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

The description is well-structured with front-loaded purpose, breakdown of response, and limitations. However, it is somewhat dense and could be more concise without losing essential details. Still, every part 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 tool's complexity (no output schema), the description fully covers inputs, output structure, and limitations. It provides enough information for an agent to use the tool correctly without additional context.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds minor context ('lookback', 'snapshot family') and restates defaults, but doesn't significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It distinguishes itself from the sibling polymarket_edges by focusing on time-series analysis rather than current snapshot data.

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

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

The description explains when to use the tool via the example contrasting fresh vs old wide edges, implying it's for assessing edge durability. While it doesn't explicitly list alternatives or when not to use it, the context is clear enough for an AI agent to infer appropriate usage scenarios.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context: it walks the order book ladder, returns detailed fill metrics (slippage, shares_filled, verdict), and warns of forced directional risk. 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 well-structured with clear sections for single-market and basket modes. It is front-loaded with the main purpose and uses capital letters for key instructions. Every sentence adds value, though a slightly tighter phrasing could improve conciseness.

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

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

Given no output schema, the description fully documents return fields for both modes, including verdict, slippage, shares_filled, per-leg details, and forced directional risk. It also provides context on when the tool is critical for avoiding losses.

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 enhances parameters by explaining the dual-mode usage of `market` vs `event`, default values for `side` and `size_usd`, and the distinct interpretations of `size_usd` for single-market versus basket mode.

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

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

The description explicitly states the tool does a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, providing a clear verb+resource specification.

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 when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why partial fills convert arb into directional risk, setting clear context.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, and the description adds substantial behavioral context beyond those: it explains how legs are paired, what compatibility_codes mean, which legs are never paired, how skipped comparisons are counted, and how temporal alignment is reported. This gives an agent a detailed model of the tool's runtime behavior and output shape.

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

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

The description is long, but it is highly structured with clear mode labels (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and every sentence carries operational detail. It is front-loaded with the core purpose and then dives into behavior; a only minor deduction for density, but no wasteful 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?

The tool has no output schema, so the description carries the full burden of explaining return semantics. It does so thoroughly: leg-by-leg prices, top_spreads_pp, safety fields, code meanings, skipped/unclassified counters, temporal alignment, and the caveat about pre-mapped topics. An agent has enough context to invoke the tool and interpret its results correctly.

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

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

Although the schema already documents all three parameters, the description adds meaningful semantics beyond the schema: it clarifies that topic is a pre-mapped shortcut set, that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and how modes interact when parameters are combined. This adds real selection and invocation guidance beyond the bare field names.

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

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

The description opens with a specific verb-resource pairing: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It also differentiates itself from sibling tools by focusing on cross-venue Kalshi–Polymarket comparison, while siblings like polymarket_arbitrage are internally focused on a single venue. The two modes and explicit safety-field explanation leave no ambiguity about what the tool does.

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

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

The description clearly explains when to use the topic mode versus explicit ticker/slug mode and warns that pre-mapped shortcuts often return compatibility warnings, implying these shortcuts are not automatically tradeable. It does not explicitly name sibling alternatives or state when to choose this tool over polymarket_arbitrage or polymarket_edges, but the usage context is otherwise well-defined.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds useful behavioral detail: scoping to an identifier (anonymous IP, key hash, account ID) and that omitting the key lists all keys. No contradictions.

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

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

The description is concise (two sentences) and front-loaded with the core action. Every sentence adds value—explaining the retrieval, listing behavior, usage context, and scoping. No wasted words.

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

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

Given the simple 1-parameter tool with read-only annotations and no output schema, the description covers return behavior (value or list of keys), use cases, and scoping. It is complete for an 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?

The single parameter 'key' has a schema description matching the tool description. Schema coverage is 100%, so the description adds no new meaning beyond 'omit to list all keys'. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all saved keys when omitted. It uses specific verbs ('retrieve', 'list') and identifies the resource (saved memory), distinguishing it from siblings like 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?

The description explains when to use the tool: to look up context stored earlier without re-deriving it. It mentions pairing with remember and forget. While it doesn't explicitly state when not to use or name alternatives, the context is clear given the sibling tools.

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

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

The description states that setting mark_read:true flags events as read, which is a write operation, but annotations declare readOnlyHint:true. This is a clear contradiction. Additionally, idempotentHint:true may be violated if repeated calls with different events are marked.

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, front-loaded with the core purpose, and each sentence adds essential 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 lack of an output schema, the description adequately explains the return structure (source, citation_uri, payload) and filtering options. However, it omits pagination behavior and error handling.

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

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

The schema covers all parameters (100% coverage), but the description adds value by providing an example type ('sec_8k') and explaining the effect of mark_read on subsequent calls, which enhances understanding beyond the schema.

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

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

The description clearly states it pulls fired events from a subscription feed and specifies the returned fields. However, it does not explicitly distinguish itself from sibling tools like 'events' or 'list_subscriptions', which have overlapping functionality.

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

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

The description mentions polling is fine and provides an alternative REST endpoint, but it does not specify when not to use this tool or contrast with other tools for fetching alert data.

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 safe (readOnly, idempotent, no destruction). Description adds 'ONE parallel call', fan-out logic, GDELT→GNews fallback, patent soft-fail, and return format (changes[], total_changes, URIs). 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?

Dense but well-structured paragraph. Front-loaded with example queries, then specifics. Every sentence adds value; slightly verbose but no waste.

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

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

Despite no output schema, description covers return structure and citation URIs. Fully explains parameters, sources, fallbacks, and sibling distinction. Sufficient for agent to select and invoke correctly.

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

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

Schema covers 100% of parameters. Description adds context: 'since' accepts ISO or relative with monitoring suggestion, 'value' can be ticker or CIK, 'type' only 'company'. Meaningfully supplements 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 'change feed for a company in the last N days/weeks/months' and lists exact sources (SEC, GDELT→GNews, USPTO). Distinguishes from sibling entity_profile by specifying static vs. dynamic scope.

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

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

Explicitly provides example queries ('What's new with X'), explains when to use vs. entity_profile, and gives parameter guidance ('Use "30d" or "1m" for typical monitoring'). Covers fallback and failure behavior.

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 context about scoping by identifier, persistence differences between authenticated and anonymous sessions, which goes beyond annotations. No contradictions.

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

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

Three well-structured sentences, front-loaded with purpose, no wasted words. Clear 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?

Given the simple input schema (2 required params, no output schema) and sufficient annotations, the description covers all necessary behavioral context: what to store, when, and how it persists. Complete for an AI agent's needs.

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

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

Schema coverage is 100%, so the schema already fully documents the parameters. The description adds example keys but no additional semantic depth beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's action ('save data') and its purpose ('reuse later'), with concrete examples like 'resolved ticker, target address, user preference'. It distinguishes from siblings by mentioning pair with recall and forget.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward' and provides alternatives: 'Pair with recall to retrieve later, forget to delete.' Also clarifies session scoping and persistence rules.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context: it cascades through multiple endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, and explicitly states unresolved identifiers under 'unresolved' rather than omitting them. This exceeds the annotation bar.

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 purpose and usage examples, then organized into SUPPORTED TYPES. While verbose, the technical details (EDGAR, GLEIF, OpenFIGI, ISIN-to-LEI) are necessary given the tool's complexity. Each section adds value, though some repetition could be trimmed.

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

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

For a tool with no output schema, the description compensates by explaining what identifiers are returned (CIK, ticker, LEI, FIGI, RxCUI), how they are labelled (source), and how failures are reported ('unresolved'). It also covers edge cases like non-US issuers and graceful degradation, making the tool's behavior fully predictable.

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 enriches both parameters: it clarifies 'type' with supported entity types and explains what 'value' accepts per type (ticker, CIK, ISIN, company name for company; brand/generic name for drug). It also gives concrete examples like 'ozempic' and 'metformin', adding 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 the tool resolves user-spoken names to canonical/official identifiers needed by other tools. It provides specific examples ('what's the ticker for…') and distinguishes itself by positioning as the first step ('Use FIRST whenever you have a name but need an ID').

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

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

Explicit usage guidance is given: 'Use FIRST whenever you have a name but need an ID.' The description also explains that it replaces 2-3 manual lookups, implying efficiency. It doesn't explicitly exclude alternatives, but the clear placement as the first step in the workflow is sufficient.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, confirming safe behavior. The description adds that it uses ai_visibility_check internally, ranks by score, and returns a ranked list with score, confidence, and signal density per entity. No annotation contradictions.

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

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

The description is two sentences, front-loaded with the main purpose, and provides a concrete example. Every sentence adds value without fluff.

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

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

The description covers the main use case and expected output format (ranked list with score, confidence, signal density). It is fairly complete given no output schema, though it could mention error scenarios or explicitly state the entity limit (2-8) from the schema. Overall, good completeness for the complexity.

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

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

Schema coverage is 100% with all parameters described. The description enriches meaning by explaining that the first entity is the subject and the rest are competitors, and that context is shared across probes. It also clarifies model options (workers-ai default, anthropic requires key).

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 of multiple entities side-by-side by probing each with ai_visibility_check and ranking by score. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by specifying the competitive audit use case.

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

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

The description explicitly states the tool is useful for competitive AI-marketing audits and gives an example question. It implies when to use but does not provide explicit exclusions or alternatives. However, the sibling tool list provides context for alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds critical behavioral context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and the return structure. No contradiction with annotations.

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

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

The description is relatively long but well-structured, front-loading the composite nature and then detailing return fields and failure behavior. Every sentence adds value, though minor trimming could improve conciseness.

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

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

No output schema, so description fully covers return fields, partial failure details, and timing caveats. For a complex multi-source tool, this provides the agent with all necessary context to understand and use the tool correctly.

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

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

Schema already covers both parameters with descriptions. Description adds valuable nuance: scoped packages accepted and default version behavior, going beyond the schema but not required since coverage is 100%.

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 it is a composite check for adding npm packages, combining deps.dev and bundlephobia data, and explicitly distinguishes from sibling tools by noting that other ecosystems fall under deps.dev:version directly.

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: 'Use whenever an agent asks "is X safe / popular / small"', and when-not-to-use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This clearly guides the agent 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?

Description adds behavioral details beyond annotations: reveals embedding model (BGE-base-en), chunking (500-char overlapping windows), cap (200K chars with truncation flag), and that passages include offsets for verification. No contradiction with annotations.

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

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

Three sentences covering purpose, usage guidelines, and technical details. Front-loaded with the primary action. No redundancy, but could potentially be tightened further.

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 3 params and annotations, the description covers input constraints, behavior, use case, and pairing with a sibling tool. Mentions output (offsets, scores) even without output schema. All necessary context for an 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%, so baseline is 3. Description adds value: specifies max chars for 'text', gives range and default for 'limit', and provides example queries for 'query'. Examples and constraints improve usability 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 starts with 'Semantic search INSIDE a fetched record,' clearly stating the verb and resource. It further explains the input (text and query) and output (top-N passages with offsets and scores). Also distinguishes from sibling 'ask_pipeworx_grounded' by noting they pair together but serve different roles.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' Also suggests pairing with ask_pipeworx_grounded, providing alternative usage context.

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

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

Annotations indicate non-read-only, open-world, idempotent, non-destructive. Description adds: creates subscription, returns id, requires OAuth account, delivery channel limits (SMS 10/day), webhook signing. No contradictions. Adds meaningful behavioral context beyond annotations.

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

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

Well-structured with key purpose first, then account requirement, then types, then delivery. While comprehensive, it could be slightly more concise in the type examples, but overall acceptable.

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, no output schema), description covers all essential aspects: purpose, prerequisites, type parameter formats, delivery options with constraints, return of subscription id, and webhook secret. No missing critical information.

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

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

Schema coverage is 100% but description adds significant value: explains enum values for type with real-world examples (e.g., sec_8k item codes), provides concrete JSON examples for params per type, details delivery channel parameters including phone verification, SMS cap, and webhook HMAC signing. Far exceeds baseline 3.

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

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

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream.' It uses a specific verb-resource pair and differentiates from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

Explicitly mentions account requirement (Pipeworx OAuth) and that anonymous+BYO cannot persist subscriptions. Lists supported types and their parameters. Implicitly tells when to use this vs recent_alerts for pulling. Could be improved by explicitly stating when not to use.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool returns 'category-bucketed example questions...drawn from the live catalog of thousands of tools,' providing beyond-annotation behavioral context about dynamic content.

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

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

The description is moderately concise (4-5 sentences) and front-loaded with triggering questions. Every sentence adds value, though it could be slightly more streamlined.

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

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

Given no output schema, the description adequately explains return values (categories, examples, tool shapes). For a simple onboarding tool with 0 required params and 1 optional param, the description is complete.

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

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

Schema coverage is 100% with a description for the topic parameter. The description adds meaning by listing example focus areas ('finance, pharma...') and explaining that omitting topic returns a full spread, going beyond the schema's basic description.

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

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

The description uses specific verbs ('returns category-bucketed example questions') and resource ('Pipeworx capabilities'), distinguishing from siblings like ask_pipeworx and discover_tools by stating it is an onboarding entry point for a newly connected agent.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides clear context but does not explicitly mention when to use 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?

Description adds significant context beyond annotations: deactivation (not deletion), ownership enforcement, and effect on historical data. No contradiction with annotations (idempotentHint, destructiveHint).

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 covering purpose, constraints, and effect. No redundant information.

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

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

For a simple tool with one parameter and no output schema, the description is complete, covering the action, ownership, and data lifecycle implications.

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

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

Schema already provides full description for parameter 'id' (uuid from subscribe). Description does not add further detail beyond schema coverage, so baseline of 3 is appropriate.

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

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

Clearly states 'Cancel a subscription by id', specifies uniqueness through ownership enforcement and deactivation behavior, and distinguishes from sibling tools like subscribe and list_subscriptions.

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

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

Explicitly states ownership enforcement ('only cancel your own subscriptions'), which is a key usage condition. Mentions that historical events remain via recent_alerts, hinting at when not to use destructive alternatives, but does not explicitly list when not to use this tool.

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

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

Beyond annotations (which only declare read-only, idempotent, open-world), the description discloses key behavioral details: verdicts returned (confirmed, refuted, etc.), the two routing paths (SEC EDGAR fast path vs. grounded pipeline), and the critical distinction between could_not_verify and unsupported. This adds substantial context about error handling and semantics.

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 every sentence earns its place: it opens with trigger phrases, states purpose, explains routing logic, lists return values, includes an important caveat about could_not_verify, and ends with the benefit over sequential calls. No fluff or 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 complexity (two paths, multiple verdicts, error states), the description covers when to use, how it works, what it returns, and the semantics of ambiguous outcomes. With no output schema defined, it adequately explains the return values and the meaning of cannot-not-verify, making it complete for an 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?

The schema already covers both parameters (100% coverage), so the description doesn't need to explain them. Yet it adds value by defining the claim parameter with concrete examples and explaining tolerance_pct's behavior and recommended settings (e.g., 1–2 for hallucination detection), which goes beyond the schema description.

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

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

The description clearly states the tool's purpose: 'natural-language claim verification against authoritative sources' with specific trigger phrases like "Is it true that…" and "fact check". It distinguishes from siblings by focusing on verifying factual claims and even explains how it replaces 4-6 sequential calls, making it distinct from general query tools like 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?

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides guidance for financial vs. other claims. However, it does not name specific alternative tools for when not to use it, so it lacks explicit exclusions, which keeps it just below a 5.

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