The Graph

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds context: default model is free, BYO key for Anthropic, response structure includes score/confidence/signals/raw_response. No contradiction and adds value beyond annotations.

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

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

Single paragraph with clear front-loading: main action, default, options, return structure, use cases. Every sentence is informative with no redundancy.

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

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

Despite no output schema, description adequately describes return format (per-model score, confidence, signals, raw_response + combined view). Covers purpose, usage, parameters, and behavioral traits for a moderately complex tool with 4 parameters and no nested objects.

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. Description adds meaning: default model is Workers AI Llama-3.3-70b (free), _apiKey is for Anthropic only, context helps disambiguate. This enriches understanding beyond schema.

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

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

Description uses a specific verb 'probe' and resource 'LLMs', with clear output 'score visibility (0-100) per model'. It distinguishes from siblings like compare_entities or scan_competitor_ai_presence by detailing the exact probing mechanism and models used.

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 cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use optional parameters (models, _apiKey). However, lacks explicit exclusions or comparison to sibling tools for 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, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds that it routes to 5,344 tools, returns structured answers with stable citation URIs, works on all tiers, and is a single fast call—valuable behavioral context beyond the annotations. No contradiction.

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

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

The description is relatively long but efficiently front-loads the key directive ('PREFER OVER WEB SEARCH') and uses list-like enumeration for domains and examples. Each section serves to clarify scope, give use cases, or route to alternatives, so every sentence earns its place; still, it could be tightened slightly.

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

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

Given the tool's complexity and lack of output schema, the description covers the what, when, and how-to-use, including return format (structured answer with citations), examples, and tier compatibility. It also differentiates from siblings, making it complete for selection and invocation.

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

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

The schema has 100% coverage with 'question' and five aliases all explained, so baseline is 3. The description enriches this by providing example queries and emphasizing natural-language input, which helps agents formulate correct questions. However, it doesn't add new parameter-level details 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 function: routes the question to one of 5,344 tools across 1,393 verified sources and returns structured answers with stable pipeworx:// citation URIs. It distinguishes itself from siblings by positioning as the default entry point and explicitly naming alternatives (ask_pipeworx_grounded, deep_research). The verb is specific—routes, returns—and the resource is well-defined.

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 instructs to prefer this over web search for a broad set of factual domains, with concrete examples. It also specifies when to step up to ask_pipeworx_grounded for hallucination-resistant answers or deep_research for broad multi-part questions, and mentions suitability for breaking news. This gives clear when-to-use and when-not-to-use guidance.

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

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

The description adds substantial behavioral context beyond the annotations: it is experimental, may have candidate routing improvements live, currently matches the stable version, and is used for A/B testing. This explains the dynamic nature and potential variability, which annotations alone do not convey. No contradiction with readOnlyHint=true or destructiveHint=false.

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 essential beta context, and every sentence adds value: it defines the beta relationship, current status, usage guidance, and reassures full functionality. No fluff or repetition of schema/annotations.

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 is complete enough given the rich annotations and the existence of a sibling ask_pipeworx for reference. It mentions 'same response shape' but does not detail the output format; however, since no output schema is provided, this could be a minor gap. Still, the description covers the tool's purpose, current state, and usage, making it mostly 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?

The input schema fully covers all 6 parameters (question and 5 aliases) with clear descriptions, so the schema itself provides complete parameter semantics. The description only says 'same arguments' without adding detail, which is acceptable given the 100% schema coverage. Baseline of 3 is appropriate.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with identical tools and response shape, while explicitly distinguishing it from the stable version by noting experimental routing improvements. It names both the sibling stable tool (ask_pipeworx) and the exact nature of the beta difference.

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

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

It gives explicit guidance: use it exactly like ask_pipeworx when you want the newest routing, and notes results are compared against the stable router. It also clarifies that it is a full working router, not a fallback to nothing, which helps in deciding when to invoke it.

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

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

Beyond the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, the description discloses critical behaviors: it only extracts answers from the tool result, may return explicit refusals with specific reasons, and imposes an extra LLM cost. This adds significant 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 dense but well-structured, leading with a clear definition, then explaining the process, return contract, use cases, and cost tradeoff. Every sentence contributes meaningful information without redundancy, making it both comprehensive 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?

There is no output schema, so the description takes responsibility for explaining the return value—detailing both success and refusal formats with common refusal reasons. It also covers routing behavior, use cases, and alternatives, making it highly complete for a complex tool that dynamically selects from thousands of sources.

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 for all parameters (aliases for question), and the schema description is clear. The description adds contextual information about how the question is used ('picks the right tool... fills arguments') but does not add specific parameter-level meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose as a 'hallucination-resistant answer mode for high-stakes reads,' explicitly distinguishing it from the sibling tool ask_pipeworx by describing the same routing but more rigorous extraction. It also details the return format and refusal behavior, making the function unmistakable.

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

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

Provides explicit guidance on when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'), including a cost tradeoff. This is exactly the kind of when/when-not guidance expected.

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

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

Annotations indicate read-only, idempotent, open-world. Description adds extensive behavioral details: fan-out examples, resolver contract (market_match_confidence, alternatives, suggestions), parent event extraction, news fallback fields, safety short-circuits, closed market handling, cancellation rules. Far exceeds annotation scope.

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 extremely verbose and presented as a single large paragraph. While it includes many details, it lacks clear sectioning or bullet points. It could be restructured with headings for readability without losing content.

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

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

Given the tool's complexity (multiple fan-outs, resolver logic, cancellation rules, safety mechanisms), the description covers all key aspects. No output schema exists, but response shapes are explained. It is thoroughly complete for effective agent use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how parameters affect behavior (e.g., depth quick vs thorough, include_raw for full payloads) and example inputs, going beyond schema descriptions.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data in one call. It specifies input types (slug, URL, question text) and distinguishes from siblings like ask_pipeworx by focusing on betting edge 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 use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. While siblings are not named, the context of Polymarket betting is distinct. Implicit guidance on when not to trust (low confidence, closed markets) is included.

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 hints. The description adds significant context: it makes one parallel call, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. This enriches behavioral understanding beyond annotations.

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

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

The description is slightly long but every sentence adds value. Key information is front-loaded (use cases, preference instruction). Could be trimmed very slightly, but overall it is efficient and well-structured.

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

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

Given the tool's complexity (two types, specific data sources, sorting, efficiency), and with annotations and schema covering basics, the description fully explains behavior, output, and when to use. No gaps remain for an agent to function correctly.

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

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

Schema coverage is 100% and the description adds meaning by explaining what each enum value does ('company' pulls 10-K data, 'drug' pulls FAERS counts) and what formats the values parameter accepts (tickers/CIKs for companies, names for drugs). This is highly useful.

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 performs side-by-side comparison of 2-5 entities (companies or drugs). It provides specific verb phrases like 'Compare X and Y' and explicitly distinguishes itself from sequential lookups, which differentiates it from siblings like entity_profile.

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

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

Explicit use cases are given ('Compare X and Y', 'X vs Y', etc.) and it advises preferring this tool over sequential single-pack lookups. It details what data is fetched for each type, helping the agent decide when to use the tool based on entity type.

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?

Goes well beyond the annotations (read-only, idempotent, open-world) to disclose account/paid-plan requirements, gap[] and contradictions[] behavior, semantic excerpting, latency expectations, and the fact that it never invents answers. This gives the agent a thorough understanding of what happens.

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?

While long, the description is dense and well-organized: account requirement, core mechanism, best-for, alternatives, depth semantics, output structure, latency. Every sentence adds necessary context for a complex tool, and the most critical info appears early.

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

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

The description covers purpose, usage boundaries, parameter nuances, output format (findings packet with gaps/contradictions), and performance expectations. Despite having no output schema, it fully explains what the agent can expect from the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by noting that 'thorough' requires a paid plan, reinforcing that broad questions are acceptable, and clarifying the depth choices' behavioral impact (gap recovery, contradiction scans).

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

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

The description clearly states the tool's function: multi-source structured-data research that decomposes questions into facets and routes them in parallel, returning a findings packet. It explicitly distinguishes itself from open-web search and siblings like ask_pipeworx, with concrete examples of ideal use cases.

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 and when-not-to-use guidance: best for broad/multi-part structured-data questions, while single lookups and breaking news should use ask_pipeworx. Also mentions the account requirement and alternative if not signed in.

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

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

Annotations indicate read-only, non-destructive, idempotent behavior. Description adds valuable context: results include full schemas with examples and are ready to call directly, no second lookup needed. 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 to four sentences, front-loaded with purpose, includes concrete examples and domains, 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 no output schema, description explains what is returned (top-N tools with schemas and examples) and the tool's role as first step. Could mention it indexes available tools, but sufficient.

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

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

Schema coverage is 100%, so baseline is 3. Description provides examples and explains the 'query' parameter accepts natural language, but doesn't add significant detail beyond schema for individual parameters.

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

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

The description clearly states the verb 'Find tools' and specifies the resources (SEC filings, FDA drugs, etc.) and the task ('browse, search, look up'). It distinguishes itself from siblings by being the meta-discovery tool, explicitly saying 'Call this FIRST'.

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

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

Provides explicit guidance on when to use ('when you need to browse, search, look up, or discover what tools exist') and a strong recommendation ('Call this FIRST'). Does not explicitly state when not to use, but context is clear.

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

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

Annotations already indicate read-only and non-destructive behavior; the description adds rich detail on data sources, output fields, failure modes (USPTO sunset), and return format, surpassing the annotations alone.

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 examples first, then purpose, then details. Slightly lengthy but every sentence adds value; could be trimmed slightly but remains effective.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description is highly complete: it lists all returned fields, mentions soft-fail behavior, and references related tools. No output schema exists, so the description fully compensates.

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 describes both parameters well. The description repeats this information without adding significant new semantic details 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 defines the tool's purpose: generating a full cross-source profile of a US public company with example queries. It distinguishes itself from sibling tools like resolve_entity by noting that names are not supported 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?

Explicit guidance states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' when a holistic view is needed, and advises using resolve_entity if only a name is available.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description's 'Delete' aligns with destructive behavior, but adds no new behavioral traits beyond the annotation context. It mentions clearing sensitive data, which provides some additional context, but overall does not significantly enhance 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 two sentences long, concise, and front-loaded with the core action. Every sentence adds value, and there is no extraneous information.

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

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

Given the tool's simplicity (one required param, no output schema, annotations present), the description adequately covers the purpose and usage context. It lacks explicit mention of the return value or success/failure indicators, but that is not required per evaluation rules. Annotations fill in the safety profile, making it fairly 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?

The input schema has 100% coverage for the single parameter 'key', with a description 'Memory key to delete'. The tool description does not add any further semantics about the parameter (e.g., format, constraints). Since schema coverage is high, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Delete a previously stored memory by key.' It specifies the verb (delete) and resource (memory by key), and distinguishes from sibling tools like remember and recall.

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

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

The description provides explicit guidance on when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall. Although it doesn't explicitly state when not to use it, the guidance is clear and helpful.

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

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

Beyond annotations (readOnly, idempotent, destructive=false), description adds how the tool fetches the page, extracts title/description/links, and outputs standard markdown. This provides essential behavioral context for an agent.

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 followed by a bullet list of use cases. No redundant information, logically structured, and front-loaded with the primary 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?

Description covers purpose, behavior, output format, and usage scenarios. Given simple input schema and no output schema, this is adequate. Minor gap: no mention of error handling or network requirements, but acceptable for a read-only 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 already covers both parameters with descriptions (100% coverage). The tool description does not add new semantic information beyond what the schema provides, so baseline score of 3 applies.

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

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

Description explicitly states verb 'Generate', resource 'llms.txt file', and context 'for any URL'. It clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on file generation rather than 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?

Description lists three concrete use cases (client indexing, personal drafting, competitor auditing) but does not explicitly state when NOT to use the tool or name alternative tools for similar tasks.

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 openWorldHint, so the description adds limited value beyond confirming it uses 'standard introspection'. No behavioral traits are disclosed beyond what annotations cover.

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 entire description is a single, well-structured sentence that front-loads the action and resource. Every word adds value, making it extremely concise and clear.

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

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

Given the tool's simplicity (1 required parameter, no enums, output schema present), the description is fully complete. It clearly states the function, output, and purpose, requiring no additional information.

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

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

With 100% schema coverage and only one parameter (`subgraph_id` with a basic description), the description adds no additional parameter-level information. A baseline score of 3 is appropriate.

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

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

Description clearly states the tool fetches a subgraph's GraphQL schema, specifies the return types (types, fields, arguments), and explains the use case (building queries without external docs). This distinguishes it from sibling tools like `query_subgraph` which likely executes queries.

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

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

The description implies when to use the tool ('so an agent can build queries without external docs'), providing clear context. However, it does not explicitly state when not to use it or mention alternative tools, which would be a minor improvement.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by confirming it returns only active subscriptions by default, specifying return fields, and implying no side effects. 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 with no wasted words. The first sentence states purpose and return fields; the second gives usage guidance. Front-loaded and efficiently 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?

For a simple list tool with one optional parameter and no output schema, the description covers the main aspects: purpose, return fields, default behavior, and usage. It could mention potential pagination or limits, but given the low complexity, it is adequately 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?

The input schema already fully describes the only parameter 'include_inactive' with a description. The tool description does not add new semantic meaning beyond what is in the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states it lists the caller's active subscriptions, specifying the verb 'list', the resource 'subscriptions', and the scope 'caller's active'. It also lists the returned fields, making the purpose unambiguous. Sibling differentiation is implicit through the list operation vs. subscribe/unsubscribe.

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

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

The description explicitly advises using this tool to review what you're monitoring before adding more or to find an id to cancel. This directly guides the agent on appropriate contexts, aligning with sibling tools for subscription management.

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

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

Adds behavioral context beyond annotations: rate-limited, free, team reads daily, signals affect roadmap. No contradiction with annotations (readOnlyHint false, destructiveHint false).

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 a single paragraph but well-structured and informative. Every sentence adds value. Could be slightly more structured with bullet points, but still effective.

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

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

Given the tool's simplicity (sending feedback), description covers purpose, usage conditions, constraints, and team handling. No output schema needed; completeness is high.

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

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

Schema coverage is 100%, and description reinforces enum usage with examples for each type. Provides guidance on message specificity and length, adding value beyond schema.

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

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

Description clearly states the tool sends feedback about bugs, features, data gaps, or praise. It uses specific verbs ('tell', 'describe') and distinguishes from siblings by focusing on feedback rather than data operations.

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 (bug, feature, data_gap, praise) and what not to do (don't paste user prompt). Mentions rate limits (5 per identifier per day) and free usage, providing clear boundaries.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds caching behavior (5min-1h), sourcing from CF analytics-engine, no PII, and self-aggregating nature, providing value beyond annotations.

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

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

The description is informative but slightly verbose. It uses bullet points for use cases, which aids readability. Every sentence adds value, though it could be slightly shortened.

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

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

Given the tool's simplicity (one optional param, no output schema), the description fully covers purpose, usage, behavior, and caching. No gaps are evident.

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 'window' has a description. The tool description adds context on how shorter vs longer windows behave, enhancing the schema's explanation.

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, top packs, and total call volume' over a recent window. It uses specific verbs ('returns') and resource ('Pipeworx trending data'), and distinguishes from siblings by focusing on trending/aggregate usage rather than direct querying or discovery.

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 enumerates three explicit use cases (discovering hot data sources, confirming canonical tool, seeing alignment). While it doesn't explicitly state when not to use it, the context is clear and actionable for an agent.

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

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

Annotations already declare readOnlyHint=true and non-destructive. The description adds rich behavioral context: algorithms (monotonicity, partition checks), filters (semantic anchor, partition filter), and fill check logic. It explains return format and failure modes (skipped_low_similarity, placeholder filtering). 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 thorough and well-structured but somewhat verbose. Each sentence adds value, but it could be slightly more concise without losing clarity. Still, excellent organization with clear sections.

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 the response format with fields like gap_pp, suggested_trade, reasoning, and partition_check details. It also covers edge cases (fill check, placeholder filtering) and refers to a sibling tool for further needs. Complete for a complex tool.

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

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

Schema description coverage is 100% with brief descriptions. The tool description goes far beyond: explains parameter types (slug, URL, seed question), how each mode behaves, and details about semantic anchor and partition filter. Adds significant value beyond schema.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes three modes: trending_scan (no args), event (single event slug), and topic (cross-event seed question). It differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly tells when to use each mode: 'Call with NO args for a `trending_scan`... pass `event`... or `topic`...' and provides recommendations: 'event (recommended for a specific market)'. It also warns against trading when realizable_edge_pp ≤ 0 and refers to polymarket_fill_risk for custom sizing.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds extensive behavioral context: caching at KV level (1h), three response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), edge calculation details (edge_pp_net, kelly_fraction), and diagnostic info (funnel counters, filter_skips). No contradiction.

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

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

The description is long but well-structured with clear sections (model families, tradeable-edge knobs, response top-level). It front-loads the purpose and uses capitalization for emphasis. Some sentences are dense but carry necessary detail; a slight trim could improve readability.

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 logic, the description fully covers output structure (by_segment, fed_candidates, _diagnostics) and explains why segments could be empty. It also describes edge calculation methodology and knob effects, leaving no major informational gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema details; e.g., for slippage_pp it notes 'Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade.' It also explains how min_kelly and min_partition_leg_kelly interact.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, distinguishing it from siblings like polymarket_arbitrage and polymarket_edge_tracker. It specifies the purpose is for agents to discover opportunities without paging hundreds of markets.

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

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

The description explicitly says it is built for 'what should I bet on today' and mentions tradeable-edge knobs (min_liquidity, max_spread_pp) for filtering. However, it does not provide explicit when-not-to-use or compare directly with siblings like polymarket_arbitrage or polymarket_edge_tracker.

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 (readOnlyHint, idempotentHint), the description details snapshot lifecycle (cache-miss gaps, 60-day TTL), return structure (tracked/expired/snapshot_dates), and computation details (daily closes, not intraday), with no contradictions to 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-loads purpose and includes structured response details, but is verbose with lengthy inline explanations of return fields (tracked, expired, snapshot_dates) that could be more compact.

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

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

Completely compensates for lack of output schema by fully describing all return fields and edge cases (gaps, TTL limits, computational basis), making the tool fully understandable for 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?

Adds value beyond schema by specifying default values (days=14, window='1wk') and constraints (days max 30, clamp 2-30), enriching the agent's understanding of parameter behavior.

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

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

Description uses specific verbs ('edge persistence and decay telemetry') and resources ('daily polymarket_edges snapshots'), clearly distinguishing this tool from the sibling 'polymarket_edges' by focusing on time-series behavior rather than current values.

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

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

Provides clear context for when to use (to understand edge longevity and decay), but does not explicitly state when to avoid or list alternatives, though the purpose implies differentiation from 'polymarket_edges'.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description goes beyond by detailing the walk-the-ladder algorithm, return fields (top_of_book, vwap_fill_price, slippage_pp, verdict), and risks (thin books, forced directional risk). No contradiction with annotations.

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

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

The description is somewhat verbose but well-structured with subheadings (SINGLE-MARKET, BASKET) and clear field lists. Every sentence adds value; minor redundancy (e.g., 'capture overround by selling every leg' could be tighter) but overall efficient for the complexity.

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

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

Given no output schema and 4 parameters with nested logic, the description fully explains return values (theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk), mode behavior, and usage context (prerequisite for arb trades). Nothing missing for an agent to invoke correctly.

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

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

With 100% schema coverage, baseline is 3, but the description adds substantial meaning beyond the schema: it explains mode selection ('market' vs 'event'), default side logic, and how size_usd is interpreted differently for buys vs sells and basket mode (settlement notional). This significantly enhances agent understanding.

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

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

The description clearly states the tool's verb ('check realizable-vs-theoretical edge') and resource ('live CLOB order-book depth'). It distinguishes between single-market and basket modes, and explicitly names sibling tools ('polymarket_arbitrage', 'polymarket_edges') as triggers for using this tool, achieving strong differentiation.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains consequences of not using it (partial basket fills convert arb to unhedged directional position) and specifies when not to use it implicitly via the threshold.

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

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

The description provides extensive behavioral details beyond the annotations: it explains the spread computation, safety fields (compatibility_warning, temporal_alignment, skipped counters), and conditions under which spreads are meaningful. It is consistent with the readOnlyHint and idempotentHint annotations, adding context without contradiction.

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

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

The description is well-structured with bold key terms, a list of modes, and a breakdown of response fields. It is relatively long but every sentence is informative. Slight reduction could improve conciseness, but it remains 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 complexity of cross-venue spread calculation and the absence of an output schema, the description thoroughly explains the response format, safety fields, and edge cases (e.g., incompatible bet shapes). It covers all necessary context for correct invocation.

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

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

The input schema already describes all three parameters (100% coverage), but the description adds value by explaining the two modes of operation, listing the 10 pre-mapped topics, and clarifying how explicit fields override topic-mapped sides. This enriches 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 defines the tool as computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It explains two modes (topic shortcuts and explicit pairings) and contrasts with sibling tools like pollymarket_arbitrage, making its purpose distinct 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 explains when to use the tool (e.g., for comparing same question across venues) and sets expectations about rare tradeable spreads via pre-mapped topics. It also warns about compatibility warnings. However, it does not explicitly mention when NOT to use it or suggest alternatives from the sibling list.

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 as read-only, idempotent, and non-destructive. The description adds relevant behavior: it returns the GraphQL data block plus any errors, and explains the subgraph ID format. This complements the annotations well 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?

Three concise sentences with zero wasted words. Front-loaded with core purpose. Every sentence adds value.

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

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

With full schema coverage, clear annotations, and an output schema, the description covers the essential aspects. It could mention constraints like internet dependency or cost, but the current info is sufficient for correct usage.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minor context (e.g., subgraph_id format) but largely reinforces schema descriptions. It does not significantly expand beyond what the schema already provides.

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

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

Clearly states the action (run a GraphQL query) and the specific resource (subgraph on The Graph network). The description distinguishes this tool from all siblings, which are unrelated (e.g., bet_research, introspect_schema).

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 context on when to use the tool (to query subgraphs) and includes subgraph_id format guidance with lookup instructions. However, it does not explicitly specify when not to use it or mention any alternatives, though none are obvious among siblings.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds context about scoping to an identifier and pairing with siblings, but does not elaborate on auth or side effects beyond annotations. No contradiction.

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

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

The description is concise, front-loaded with the action, and uses minimal sentences to cover all necessary information without excess.

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 one optional parameter and no output schema, the description fully covers behavior, usage, scoping, and relationships to siblings. No gaps.

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

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

Input schema covers the 'key' parameter with 100% description coverage. The description adds nuance: omitting key lists all keys, and key should correspond to a saved value, 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 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)', using a specific verb+resource structure. It distinguishes 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 ('to look up context the agent stored earlier... without re-deriving it from scratch') and provides pairing guidance with 'remember' and 'forget'. It does not explicitly state when not to use, but the context is clear.

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

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

Annotations already mark readOnly/idempotent/non-destructive. Description adds valuable details: return fields (source, citation_uri, raw payload), mark_read behavior (flags read for next call), and that polling is fine. 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 efficient sentences: first states purpose, second describes return content and filtering, third gives usage tips. Front-loaded with key action, 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?

No output schema, but description explains return fields (source, citation_uri, raw payload). Covers all parameters with usage context, includes alternative access method, adequate for a read-only feed tool.

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

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

Schema has 100% description coverage, so baseline is 3. Description adds context: 'type' filters subscription type, 'since' is ISO timestamp, mark_read affects subsequent calls, default limit 50. Adds extra nuance beyond schema.

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

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

Clearly states 'Pull fired events from your subscription feed' with specific verb 'Pull' and resource 'fired events'. Distinguishes from siblings like list_subscriptions by focusing on alert content rather than subscription configuration.

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 context on filtering by type/since, mark_read effect, and polling suitability. Mentions alternative HTTP endpoint for scripting. Lacks explicit when-not-to-use but covers main 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?

The description adds significant behavioral context beyond annotations: it notes the parallel call, the soft-fail for USPTO due to API sunset, and the return structure (changes[] grouped by source, total_changes, 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 front-loaded with user query examples and is information-dense. While slightly long, every sentence adds necessary detail. It is well-structured and concise for the complexity of the tool.

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

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

Given the tool's complexity (aggregating from multiple sources), the description is highly complete: it covers sources, fallback, parameter formats, output structure, and sibling tool differentiation. No output schema exists, but the description adequately explains returns. This is exceptionally thorough.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing examples for `since` ('7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring. It also clarifies `value` accepts ticker or CIK. This extra guidance justifies a 4.

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

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

The description explicitly states the tool provides a change feed for a company over a time window, with examples like 'What's new with X' and 'latest on Y'. It details the sources (SEC, GDELT/GNews, USPTO) and distinguishes from sibling entity_profile, 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?

The description provides concrete usage examples and explicitly tells when not to use it ('Use entity_profile instead when you want the static profile'). It also explains fallback behavior (GDELT preferred, GNews on error) and the `since` parameter shorthand, 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?

Describes persistence beyond annotations: authenticated users get persistent memory, anonymous sessions retain memory for 24 hours. Also mentions scoping by identifier. No contradictions 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?

Description is four sentences, each adding value: purpose, usage, storage mechanics, persistence, and companion tools. No redundant or unnecessary words.

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

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

Given two string parameters, no output schema, and comprehensive annotations, the description fully covers behavior (idempotent, non-destructive), retention policies, and pairing with sibling tools. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minimal extra meaning beyond schema—only mentions 'key-value pair', which schema already details. No additional parameter nuances.

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

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

The description clearly states the verb 'save' and resource 'data', explaining it stores key-value pairs for reuse across conversations. It distinguishes from sibling tools like recall and forget by specifying storing vs retrieving/deleting.

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 use 'when you discover something worth carrying forward' and mentions pairing with recall to retrieve and forget to delete, providing clear context for when to use this tool versus alternatives.

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

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

The description adds value beyond annotations by detailing that each call cascades through multiple lookup endpoints (replacing 2-3 manual lookups), auto-disambiguation, and returns citation URIs. It is consistent with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint 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 comprehensive and well-organized but slightly verbose. It front-loads key usage examples and user intents, making it easy to scan, though a few sentences could be tightened.

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 two parameters with full schema coverage, no output schema, and the complexity of resolving entities, the description completely covers what the tool returns for each type (including citation URIs) and how it works, leaving 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 greatly enriches parameter meaning by providing examples (e.g., ticker 'AAPL', CIK '0000320193'), explaining auto-disambiguation, and specifying output details (ticker, CIK, company_name, citation for company; RxCUI, ingredient, brand, citation for drug).

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 identifiers for companies and drugs, using specific verbs like 'resolve' and naming the resource 'entity'. It differentiates from sibling tools by indicating it's the first step when a name is known but an ID is needed.

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

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

The description explicitly advises 'Use FIRST whenever you have a name but need an ID' and provides example queries for each supported type. It implies that other tools require these IDs as input, but does not explicitly list alternatives or when not to use the tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it explains the probe workflow (using ai_visibility_check), the ranking process, and the output fields (score, confidence, signal density). 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 only two sentences but packs essential information: action, workflow, use case, and output. It is front-loaded with the core purpose and avoids redundancy. Every sentence adds value.

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

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

Given the tool complexity (4 params, no output schema), the description adequately covers purpose, usage, workflow, and output. It mentions return fields but not exact structure; however, for a comparative audit tool, this is sufficient. A slightly more detailed output example would raise it to 5.

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?

Despite 100% schema coverage, the description adds significant semantics: it notes that the first entity is treated as 'subject' for narrative, specifies entity count range (2-8), and explains the role of the models and context parameters in the comparison. This goes well beyond the schema descriptions.

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

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

The description clearly states the verb 'compare' and resource 'AI visibility across multiple entities'. It distinguishes itself from sibling 'ai_visibility_check' by emphasizing side-by-side comparison and ranking, making the purpose 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 a clear usage scenario ('competitive AI-marketing audits') with a concrete example question. While it does not explicitly state when not to use or name alternatives, the context is sufficiently clear for an AI agent to infer appropriate 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 readOnly, idempotent, non-destructive. Description adds significant behavioral details: composite call structure, fan-out to two services, partial failure handling, timeout specifics (5-30s), and return field list. No contradictions.

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

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

Description is long but every sentence adds value. Front-loaded with main purpose. Could be slightly more concise but highly efficient given the complexity.

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

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

Despite lacking an output schema, the description fully enumerates the return fields, handles edge cases (partial failures, timeout), and covers all important aspects. Highly complete.

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

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

Schema coverage is 100%, so baseline is 3. Description adds that scoped packages are accepted and version defaults to latest, which adds helpful context beyond the schema.

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

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

The description clearly states it's a composite check for npm packages covering license, advisories, version history, and bundlephobia info. It distinguishes itself from siblings by specifying the exact use case and ecosystem 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 states when to use ('is X safe / popular / small' or 'what does adding lodash cost me'), specifies NPM-only scope, and mentions graceful degradation for partial failures. Provides clear guidance on 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 indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds substantial context: embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping windows), and limits (200K chars, truncation flag). This goes well beyond what annotations provide.

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

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

The description is front-loaded with the main purpose and includes necessary details in a logical flow. It is slightly long but every sentence adds value, making it efficient overall.

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 return values ('passages with character offsets and similarity scores'), limitations (200K char cap with truncation), and integration with sibling tools. No output schema exists, so this completeness is essential and well-handled.

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

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

Schema coverage is 100% with parameter descriptions. The description adds meaning by providing concrete examples (e.g., 'SEC 10-K body', 'supply-chain risk') and clarifies the purpose of the 'text' and 'query' parameters. The 'limit' parameter is implied but not explicitly detailed in the description beyond 'top-N'.

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 ('semantic search') and the resource ('inside a fetched record'), with a specific verb and resource. It distinguishes from sibling tools like ask_pipeworx_grounded by explaining the focused use case.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded for grounding, providing clear context for when to use this tool over alternatives.

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

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

The description adds rich behavioral context beyond annotations: OAuth requirement, subscription types with examples, delivery channels, email/SMS constraints, webhook HMAC signing details, and auto-disable after 10 consecutive failures. Annotations already indicate idempotent and non-destructive, and description aligns.

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

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

Reasonably concise given the complexity; front-loaded with purpose. Could be slightly more terse in delivery descriptions, but each sentence adds necessary detail.

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

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

Given the tool's complexity (multiple subscription types, delivery options, OAuth requirement, rate limits), the description covers all critical aspects: return value, prerequisites, types, delivery channels, limits, webhook signing. No output schema, but description sufficiently explains what is returned.

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

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

Schema coverage is 100%, and description adds significant meaning with examples and constraints for each parameter (e.g., type enum descriptions, params field with full examples, delivery field with detailed webhook signing process, phone verification, rate limits). Exceeds baseline expectation.

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. The verb 'create' and noun 'subscription' are specific, and the resource is live-data event stream. Distinguishes from siblings like list_subscriptions and unsubscribe by nature.

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

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

Provides explicit context on when to use (creating a subscription) and prerequisites (requires Pipeworx OAuth account). Mentions limitations for anonymous/BYO users and delivery channel restrictions. Does not explicitly state when not to use, but the purpose is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds behavioral context: it is nondestructive, returns static example questions, and can be called with no arguments. No contradictions.

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

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

Description is front-loaded with common query patterns and is information-dense without being verbose. Every sentence adds value. Could be slightly more concise but structure is clear.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all necessary context: what it returns (category-bucketed questions with tool info), when to use it (first step), and how to vary its behavior. Complete and self-contained.

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?

Parameter schema has 100% coverage with a description. Description adds value by explaining the purpose of omitting vs. specifying topic and listing the possible values in a readable format (e.g., 'finance', 'pharma'). Goes beyond the schema's terse enum list.

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

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

Description clearly states it returns category-bucketed example questions with exact tool and argument shape. Identifies itself as the onboarding entry point for a new agent, distinguishing it from siblings like ask_pipeworx or entity_profile.

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

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

Explicitly advises 'Use this FIRST when you do not yet know what Pipeworx can do for you'. Provides context on when to use (initial onboarding, learning meta-tools) and mentions the topic parameter to narrow scope. Does not explicitly list when-not scenarios, but the guidance is clear enough.

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

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

Description adds value beyond annotations: deactivation vs deletion, historical events retained. Aligns with idempotentHint and destructiveHint. Clearly states ownership enforcement.

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 waste. Front-loaded with action and key constraints.

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 one-param tool with annotations, the description covers purpose, constraints, side effects, and retention policy. No output schema needed; complete.

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

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

Schema already documents 'id' as uuid returned by subscribe (100% coverage). Description only says 'by id', adding no new meaning beyond schema.

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

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

Clearly states 'Cancel a subscription by id' and distinguishes from siblings like subscribe and list_subscriptions by specifying effect (deactivate) and ownership enforcement.

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?

Gives clear context: ownership enforcement and that the subscription is deactivated not deleted. Does not explicitly state when not to use or alternatives, but the constraint is helpful.

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

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

The description adds significant behavioral context beyond annotations. It discloses the two verification paths (SEC EDGAR+ XBRL for financial claims, grounded pipeline for others), the returned verdict types, and the inclusion of citations and reasoning. This aligns with readOnlyHint and openWorldHint without contradiction.

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

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

The description is moderately concise for its complexity. It starts with illustrative examples, then explains purpose, verification paths, output, and efficiency benefit. Every sentence adds value, though some redundancy exists (e.g., repeating 'grounded pipeline' in different forms). Still well-structured.

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

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

Given the tool's complexity, the description covers all necessary aspects: purpose, usage scenarios, behavioral details, parameter semantics, and return values (verdict, actual value with citation, reasoning). Despite lacking an output schema, the description fully describes what the tool returns.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the tolerance_pct parameter's behavior: it overrides implied tolerance, suggests 1-2 for hallucination detection, and clarifies default (implied by wording, capped at 5). This 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 defines the tool's purpose: natural-language claim verification against authoritative sources. It uses concrete example phrases like 'fact check' and 'verify the claim that...' and distinguishes it from siblings by stating it replaces 4-6 sequential calls.

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

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

The description provides explicit guidance on when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims and other factual claims, detailing the verification paths, which helps the agent decide when to invoke this tool over alternatives.

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