Revternal

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

Beyond annotations (readOnlyHint, idempotentHint), the description explains the free default model, BYO key requirement for Anthropic, and the return format per model plus combined view. No contradictions with annotations.

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

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

The description is a single well-structured paragraph that front-loads the purpose. It is concise but could be slightly more scannable with bullet points.

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 all 4 parameters documented, strong annotations, and the description stating the output format (per-model scores etc.), the tool is fully specified for its complexity. No output schema needed.

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

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

Schema coverage is 100%, but the description adds valuable context: default model (free), _apiKey passed straight through, and context helps disambiguate. This meaningfully supplements the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/entity and scores visibility (0-100). It specifies supported models and return structure, distinguishing it from sibling tools like scan_competitor_ai_presence.

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

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

The description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not explicitly differentiate from similar tools or state when not to use it.

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

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

Beyond the readOnly, idempotent, and openWorld annotations, the description reveals meaningful behavior: it routes to thousands of tools, returns stable citation URIs, makes 'one fast call', works on every tier, and can handle breaking news. It also implies the default tool is not hallucination-resistant by recommending ask_pipeworx_grounded when verbatim evidence and confidence are needed.

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

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

Although lengthy, the description is front-loaded with the key directive ('PREFER OVER WEB SEARCH') and each subsequent sentence earns its place: scope, examples, default status, escalation paths, and breaking-news handling. The only minor redundancy is repeating 'even if web search could also answer it,' but the structure remains tight and scannable.

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

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

For a complex router tool with no output schema, the description covers the return format ('structured answer with stable pipeworx:// citation URIs'), when to use it over alternatives, and what question types it handles. Nothing an agent needs to correctly select and invoke this tool is missing.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for a single 'question' field and examples provided. The description adds no parameter-level semantics beyond what the schema already states, so it stays at the baseline.

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

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

The description states a specific verb ('routes the question'), a concrete resource (5,706 tools across 1,493 verified sources), and an output ('structured answer with stable pipeworx:// citation URIs'). It also explicitly contrasts itself with ask_pipeworx_grounded and deep_research, making it easy to tell apart from close siblings without inspecting schemas.

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

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

It opens with 'PREFER OVER WEB SEARCH' and gives exhaustive when-to-use guidance, including trigger phrases like 'what is', 'look up', and 'get the latest'. It clearly says 'START HERE for most questions' and provides explicit escalation rules: use ask_pipeworx_grounded for hallucination-resistant verbatim answers and deep_research for broad/multi-part questions.

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 establish read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: the beta status, that candidates are only active 'under test,' that none is active now, and that it 'currently matches ask_pipeworx exactly.' This gives an agent a clear picture of the tool's experimental nature and fallback behavior.

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

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

The description is dense and front-loaded: it opens with the beta identity, states the current match state, gives usage direction, and clarifies fallback. It is somewhat wordy with the specific retirement date and the 'falls back to nothing' clarification, but every sentence adds operational value.

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

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

For a universal router with no output schema, the description covers all essential operational facts: what it does, its relationship to ask_pipeworx, current active state, how to invoke it, and what kind of tool it is. An agent has enough context to select and call it appropriately.

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

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

Schema coverage is 100% with descriptions for all six parameters and aliases, so the schema carries the parameter burden. The description only repeats that it has 'same arguments' as ask_pipeworx and adds no new parameter-level details, which aligns with the baseline of 3.

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

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

The description clearly identifies this as the beta variant of ask_pipeworx and explains it is an identical universal router with the same 5,706 tools and same response shape. It explicitly differentiates the beta from the stable sibling by its live candidate routing improvements.

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

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

The description states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It gives clear context about the experimental edge and comparison against the stable router, though it does not explicitly state when not to use it or mention the grounded alternative.

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

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

The description goes well beyond the annotations, disclosing the return shape, explicit refusal reasons, evidence-only extraction, and the extra LLM call cost. There is no contradiction with the read-only, idempotent, non-destructive 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 yet well organized: purpose, behavior/return contract, usage guidance, and cost tradeoff each have a clear sentence. There is no filler or redundancy, and the most important distinction is front-loaded.

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

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

Even without an output schema, the description documents the success and refusal response shapes, the refusal_reason enum, and the cost difference versus the sibling. An agent has enough context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents the question parameter and its aliases. The tool description does not add parameter-specific semantics, but this is acceptable because the structured schema carries that burden.

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

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

The description states a specific, differentiated purpose: a hallucination-resistant answer mode that extracts answers only from tool results for high-stakes reads. It also explicitly contrasts with ask_pipeworx via the grounded extraction and evidence requirements, making sibling differentiation 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?

It explicitly says when to use the tool: when answers will be quoted, cited, or acted on, and when inventing facts is unacceptable. It also gives a clear alternative—prefer ask_pipeworx for casual lookups—and states the extra LLM call cost as a tradeoff.

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

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

The description extensively discloses behavioral traits beyond annotations: response shapes (result.market, result.analysis, result.evidence), resolver contract (market_match_confidence, alternatives, suggestions), parent_event extractor, news fallback fields, safety behavior (low-confidence resolution short-circuits, closed markets return status, wide-spread markets flagged), and resolution-rule risk parsing. This far exceeds what annotations (readOnlyHint, idempotentHint) provide, ensuring the agent understands all edge cases.

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

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

The description is very long and dense with information, but it front-loads the main purpose and usage in the first few sentences. While every sentence adds value, the length could be reduced by organizing details into bullet points or sub-sections. It sacrifices conciseness for completeness, which is acceptable given complexity but not optimal.

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

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

Given the tool has 3 parameters, no output schema, and moderate complexity, the description covers all necessary aspects: input, behavior, response structure (market, analysis, evidence, resolver contract, parent_event), edge cases (low-confidence, closed markets, wide spreads, cancellation rules), and safety instructions. It leaves no gap in the agent's understanding.

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

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

Despite 100% schema coverage (so baseline is 3), the description adds significant meaning: for 'market' it clarifies slugs, URLs, and question text; for 'depth' it explains 'quick = 2-3 evidence sources, thorough = full fan-out'; for 'include_raw' it details when to use true vs false and the response size implications. 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 tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input formats (slug, URL, question text), output (evidence packet + market-vs-model comparison), and usage examples. The verb 'research' and resource 'bet' are specific, and the description distinguishes it from siblings like polymarket_edges by focusing on pulling data for a single bet.

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 examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains classifiers and fan-out examples, helping the agent decide when to invoke. However, it does not explicitly state when NOT to use this tool or compare it to sibling tools like polymarket_arbitrage or validate_claim, which would strengthen guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds useful behavioral context: handles off-calendar fiscal years, returns sorted results with citation URIs. No contradiction with annotations.

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

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

Description is a single paragraph front-loaded with common trigger phrases. Every sentence adds essential information without redundancy.

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

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

Fully explains the tool's purpose, entity types, data sources, result format, and efficiency gain. No missing information despite lacking an output schema; annotations cover safety and idempotency.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by providing concrete examples (e.g., tickers like AAPL, MSFT) and explaining what data each type returns, enriching 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 performs side-by-side comparisons of 2-5 companies or drugs in one call, with specific trigger phrases and data sources. It distinguishes itself from sequential single-pack lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides clear examples for type and values, explaining data pulled for each 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?

Annotations declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial non-obvious behavior: account tier gating, parallel decomposition, gaps[] never invented, contradictions[] for standard/thorough, semantically excerpted records, fetchable citation_uri, and latency expectations of 15-60s up to ~90s. No contradiction with annotations exists.

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

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

Though long, the description is dense and front-loaded: account requirement and the critical 'NOT open-web search' disclaimer come first, followed by capability, usage boundaries, depth behavior, and return format. Every sentence adds operational or selection value, and the length is proportionate to the tool's complexity.

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

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

For a complex tool with no output schema, the description fully covers what an agent needs: return packet contents (evidence, confidence, source, gaps, contradictions, hops, citations), caveats (empty gaps for non-catalog topics), auth requirements, latency, and depth options. The two parameters are thoroughly explained in the schema plus description.

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 goes further by explaining depth semantics in plain terms ('standard re-angles unanswered gaps', 'thorough chases the best leads') and giving example questions that clarify question's natural-language intent. It adds meaning beyond the enum values already described.

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

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

The description defines a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1493 STRUCTURED data sources' in ONE call, and explicitly disclaims being 'NOT open-web search'. It distinguishes itself from siblings like ask_pipeworx by clarifying it decomposes broad/multi-part questions and routes to 5,706 tools in parallel.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and names alternatives with conditions — for a single lookup use ask_pipeworx, and for breaking/current news prefer ask_pipeworx because deep_research returns mostly empty gaps. It also provides an account prerequisite and fallback ('If you are not signed in, use ask_pipeworx instead').

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds valuable context: returns top-N most relevant tools with full input schemas and curated examples, ready to call directly. This goes beyond the annotations to explain behavior and output format.

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

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

The description is thorough but slightly verbose due to listing many domains. However, it is well-structured with clear front-loading of purpose and usage guidance. It earns its keep with actionable details like 'no second schema lookup needed'.

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 (discovery tool) and lack of output schema, the description fully conveys what the tool returns: names, descriptions, full input schemas with examples. It also notes that results are ready to call. No gaps in understanding.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining that 'query' accepts natural language and listing multiple aliases (task, q, description, search). It also provides examples in the schema. The description compensates well beyond what the schema provides.

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

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

The description clearly states the tool's purpose: to find tools by describing the data or task. It lists many specific domains (SEC filings, FDA drugs, etc.), and it distinguishes itself from sibling tools by being the discovery entry point, not a domain-specific research tool.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set'. Also explains when to use: when needing to browse, search, look up, or discover tools. Provides clear context without needing to infer.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds extra context about fan-out across sources, patent soft-fail, and output format, but doesn't detail rate limits or error handling.

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?

Information-dense and well-structured with semicolons, but slightly lengthy; could be more concise by trimming redundant phrases.

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

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

Despite missing output schema, description lists all return fields, sources, ordering, and fallback behavior, providing comprehensive context for a complex multi-source tool.

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

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

Schema coverage is 100% and description enriches both parameters with examples and constraints (e.g., 'names not supported'), going beyond schema comments.

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

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

Description uses specific verbs like 'full cross-source profile' and lists exact outputs and sources, clearly distinguishing from sibling tools like compare_entities and resolve_entity.

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

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

Provides explicit example queries, states preference over chaining single-pack lookups, and names alternatives (resolve_entity) for unsupported inputs.

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

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

Annotations already indicate destructiveHint=true, so the destructive nature is clear. The description adds useful context about stale data and sensitive information, but does not contradict annotations.

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

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

Two sentences that are front-loaded with the purpose and usage. No wasted words, every sentence adds value.

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

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

For a simple delete tool with one parameter and no output schema, the description provides all necessary context: purpose, when to use, and parameter semantics.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The description adds minimal extra meaning beyond the schema, so baseline of 3 is appropriate.

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

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

The description states 'Delete a previously stored memory by key,' which is a specific verb and resource. It clearly distinguishes from siblings like 'remember' and 'recall' by indicating the delete operation.

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

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

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

The description fully aligns with annotations (read-only, open-world, idempotent, non-destructive) and adds behavioral details: fetches the page, extracts title/description/key links, and outputs standard llms.txt format. 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 three sentences: purpose, process/output, and use cases. It is front-loaded with the main action and contains no unnecessary words. Every sentence adds value.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers purpose, process, output format, and use cases. It is slightly lacking in error handling or edge cases, but for a straightforward read tool this is acceptable.

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

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

Schema coverage is 100% with both parameters documented. The description does not add significant new meaning beyond the schema, as it only repeats that the URL is the site to summarize and max_links controls link count. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL. It specifies the verb 'generate' and the resource 'llms.txt file', and distinguishes from sibling tools as no other tool serves this purpose.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor. It gives clear context for when to use the tool, though it does not explicitly state when not to use it or mention 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?

Adds detail beyond annotations, such as that it returns active subscriptions optionally including cancelled ones (via include_inactive parameter). Annotations already indicate readonly, idempotent, non-destructive; description reinforces and adds return field specifics.

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 front-loading purpose, return fields, and usage recommendation. 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?

With only one optional parameter, no output schema, and robust annotations, the description fully covers what the agent needs to know to invoke and interpret results.

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 include_inactive. Description does not add additional meaning beyond the schema definition; it merely restates the parameter's effect implicitly.

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

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

Description clearly states 'List the caller's active subscriptions' and explicitly lists return fields (id, type, params, etc.). Differentiates from siblings like subscribe and 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?

Provides guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Implicitly communicates when to use (before adding or to cancel) but does not explicitly state 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 are all false and thus uninformative, so the description carries the full burden. It richly discloses the claim_token flow (how to check resolution), daily human review, rate limiting (5/identifier/day), and that it is free and non-quota-charging. This goes well beyond the schema.

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

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

Deliberately front-loaded with the core purpose in the first sentence. Each subsequent sentence adds distinct operational guidance without redundancy. It is longer than a two-sentence ideal, but every clause earns its place with practical specifics.

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

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

With no output schema, the description explains the return workflow (claim_token) and post-filing behavior. It covers rate limits, account-less usage, and how to check resolution. Some edge cases (e.g., outcomes when an account is present) are implied but not fully detailed, yet the overall guidance is 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 descriptions cover 100% of parameters and are already detailed for type, context, message, and claim_token. The description adds value by giving a concrete usage example (pipeworx_feedback({claim_token:"pwfb_…"})) and explaining when claim_token is returned, which is not in the schema.

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

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

Clearly states its function: feedback gathering for the Pipeworx team, enumerating specific types (broken, missing, praise). It also distinguishes itself from sibling tools by scoping to this Pipeworx connection only, explicitly excluding other MCP servers.

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 triggers: bug for wrong/stale data, feature/data_gap for missing tools, praise for good experiences. It gives a strong exclusion rule (different MCP servers should be reported elsewhere) and practical advice (describe in terms of Pipeworx tools/packs, don't paste user prompts).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds data source (CF analytics-engine), no PII, caching behavior (5min-1h), and output structure. 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?

Single paragraph with three bullet-pointed use cases. Dense and efficient, every sentence adds value. 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 explains return value (top tools, packs, volume) and data source. Caching and window options are covered. Complete for a simple read-only tool with one parameter.

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?

Only parameter 'window' has full schema coverage (enum). Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds value beyond enum labels.

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

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

The description states exactly what the tool does: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This clearly distinguishes it from siblings like 'discover_tools' or 'ask_pipeworx'.

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

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

Explicitly lists three use cases (discovering hot sources, confirming canonical choice, aligning use case) and explains window tradeoffs. Lacks explicit 'when not to use' but provides sufficient context.

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

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

Annotations indicate read-only, idempotent, open-world, non-destructive. Description adds extensive behavioral context: modes, fill check logic, semantic anchor, partition filter, edge cases. 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 thorough but slightly verbose. Well-structured with clear sections and front-loaded purpose, but could be slightly more concise. Still highly valuable.

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

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

Despite no output schema, the description fully details the response format (opportunities array, partition_check, fill check). Covers all aspects needed for correct invocation and interpretation.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds extra context: event slug meaning, topic as seed question, and explains how each parameter triggers different behavior.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and uses specific verbs and resources.

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 each mode: no args for trending scan, event for specific market, topic for cross-event. Provides guidance on fill check and when not to trade, and mentions alternative tool (polymarket_fill_risk).

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes well beyond by detailing caching ('Cached 1h at the KV level'), behavioral traits like slippage assumptions, Fed bet exclusion, and filter effects. 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 very long and dense, covering many technical details. While well-structured with clear sections, it could be more concise. However, the upfront purpose sentence is strong.

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 compensates thoroughly by detailing the response structure (by_segment, fed_candidates, _diagnostics), explaining model families, edge calculations, and knob effects. It is highly complete for an agent to understand what the tool returns and how to configure it.

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

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

Schema coverage is 100%, but the description adds significant value beyond schema. Each parameter gets contextual guidance: e.g., 'min_kelly' explains why it skips opportunities, 'slippage_pp' mentions zero trading fees but typical spread costs. This helps agents understand trade-offs.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan) and resource (Polymarket markets), and distinguishes from sibling tools like polymarket_arbitrage and bet_research by focusing on edge detection with Pipeworx.

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

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

The description provides explicit usage context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains when to use the tool and details the three response segments. While it lacks explicit 'when not to use', the extensive knob descriptions and filters imply appropriate scenarios.

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

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

Annotations provide readOnlyHint etc. Description adds rich context: response structure, trend calculation (new/widening/stable/decaying), meaning of negative edge_pp_net (SELL YES), and that gaps mean no scan that day. 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?

Purpose is front-loaded. Structure is clear: purpose, args, response fields, limits. Slightly verbose but well-organized. 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?

No output schema, so description must explain return values. It thoroughly details tracked[] (time-series, first_seen, trend, decay), expired[] (lifespan_days), and snapshot_dates[]. Also covers limitations and computation details. Very 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 confirms defaults (days=14, window='1wk') and clamp (2-30) but does not add new semantic guidance beyond the schema. Adequate but not superior.

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 answers 'how long has this edge existed and is it shrinking?' and details the output structure (tracked[], expired[], snapshot_dates[]). It differentiates from sibling 'polymarket_edges' by focusing on persistence and decay over time.

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

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

Explicitly guides when to use: to understand edge longevity vs. current edges. Mentions limits (60-day TTL, snapshotting start) and that decay numbers are from daily closes, not intraday. Implicitly contrasts with alternatives.

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

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

Annotations already declare readOnlyHint=true, safe, idempotent. The description adds behavioral context: it walks the order book ladder, returns verdicts (clean|degraded|cannot_fill), and warns about thin books and forced directional risk. No contradiction with annotations. It could be more concise but is transparent.

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 verbose and includes many details about outputs and risk warnings in a single paragraph. It could be structured with bullet points or separate sections for each mode. While comprehensive, it lacks conciseness and is not front-loaded enough for quick scanning.

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

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

Given the tool's complexity (two modes, multiple outputs, risk implications) and lack of an output schema, the description is remarkably complete. It covers all modes, output fields, default behaviors, edge cases, and risk guidance. No gaps are apparent.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains the default side in basket mode (auto based on partition sum), the interpretation of size_usd for baskets (settlement notional, shares per leg), and clamping range. It also clarifies that exactly one of market or event is required. This goes well beyond the schema.

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

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

The description clearly states the tool's purpose as a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between single-market and basket modes, and explicitly contrasts with sibling tools polymarket_arbitrage and polymarket_edges by advising usage before acting on their signals. This provides 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 gives explicit guidance on when to use the tool: before executing polymarket_arbitrage signals or polymarket_edges trades above ~$500. It explains the risks of not using it (partial fills leading to unhedged positions). However, it does not explicitly state when NOT to use it or provide alternatives, which would make it a 5.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description goes well beyond them: it discloses that warnings can be non-empty even when matched_pairs>0, that unknown metric_type/match_subtype legs are never paired, that premapped_pairing_unverified is always set in topic mode, and that most pre-mapped topics currently return warnings. This is exactly the kind of behavioral context that prevents misuse.

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

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

The description is long, but it earns most of its length by covering modes, response shape, safety fields, warning codes, and skipped-pair logic. It is front-loaded with the core purpose and clearly labeled sections. Still, the code catalog and counter explanations make it denser than strictly necessary.

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

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

With no output schema, the description carries the full burden of explaining return semantics, and it does so thoroughly: response prices, top_spreads_pp, compatibility fields, per-entry flags, temporal_alignment, skipped counters, low_confidence_pairs, and a real-world caution are all covered. An agent has nearly everything needed to invoke and interpret this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning: it enumerates all ten topic shortcuts, explains the two operating modes, and clarifies that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side. This goes far beyond the schema's short field descriptions.

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

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

The description opens with a clear verb-resource statement: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It immediately distinguishes itself from the many Polymarket-only siblings by pairing the two venues and explaining the 2-25pp divergence signal.

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 defines two usage modes (topic shortcuts vs explicit ticker/slug pairings) and tells the agent when each is appropriate. It also warns that most pre-mapped topics return compatibility_warning today and that pre-mapped ≠ tradeable. It does not name a specific sibling alternative, but the internal mode guidance is strong.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds scope details (anonymous IP, etc.) and pairing with other tools, which is helpful but does not significantly extend beyond the annotation hints.

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 front-load the primary action, then provide context and relationships. No filler or redundant information earns its place.

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

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

For a simple tool with one parameter and no output schema, the description fully explains purpose, usage context, scoping, and sibling relationships. An agent has all necessary information to decide when and how to invoke 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?

The schema already covers the single optional parameter 'key' with a clear description. The description repeats the same information about omitting key to list all keys, adding no new semantic value beyond the schema.

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

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

The description uses specific verbs ('retrieve', 'list') and clearly identifies the resource ('value previously saved via remember', 'saved keys'). It distinguishes from siblings 'remember' and 'forget' by name, making the purpose unmistakable.

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

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

The description explains when to use the tool: 'to look up context the agent stored earlier... without re-deriving it from scratch'. It provides contextual cues like scoping and pairing with remember/forget, but does not explicitly state when not to use it or list alternatives beyond naming siblings.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds behavioral details: it returns events with source, citation_uri, and raw payload; explains that setting mark_read:true flags events as read; and notes that polls work fine. This provides useful context beyond the annotations.

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

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

The description is a single paragraph of about 5 sentences, front-loaded with the main action. It is concise and covers essential information without fluff. However, it could be slightly more structured (e.g., using bullet points) for easier parsing.

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 5 parameters (all with schema descriptions), no output schema, and rich annotations, the description provides adequate context: it explains the return fields, the effect of mark_read, and an alternative access method. It covers the main usage scenarios but does not detail every parameter's behavior.

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

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

Schema coverage is 100%, so each parameter is already described in the schema. The description briefly restates the filter options (type and since) but adds value by explaining the mark_read behavior in context. Overall, it does not significantly enhance parameter understanding beyond the schema.

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

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

The description begins with 'Pull fired events from your subscription feed,' which clearly states the verb ('Pull') and the resource ('fired events from your subscription feed'). It distinguishes itself from siblings like 'list_subscriptions' by focusing on events from the feed, not listing subscriptions.

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

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

The description specifies when to use the tool (pulling alerts with optional filters) and mentions an alternative method via HTTP GET. It does not explicitly state when not to use it compared to siblings, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. Description adds value by detailing the multi-source fan-out (SEC, GDELT/GNews, USPTO), fallback logic, and return structure. No contradictions.

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

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

Front-loaded with user-facing examples, but description is somewhat long. Every sentence adds information, but could be slightly tightened without losing clarity.

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

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

Given the complexity (multiple sources, fallbacks, soft-failures) and absence of output schema, the description covers return structure (grouped changes, counts, citation URIs) and edge cases thoroughly.

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

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

Schema coverage is 100%, but description adds extra context: examples for `since` (ISO and relative shorthands like '30d', '3m'), and clarification that `value` accepts tickers or CIKs. This goes beyond the schema's baseline descriptions.

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

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

Description clearly states it provides a change feed for a company, with specific query examples ('What's new with X', 'latest on Y'). It explicitly distinguishes from the sibling tool entity_profile by noting when to use the static profile instead.

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

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

Provides explicit when-to-use examples and mentions when to use entity_profile as an alternative. Also explains fallback behavior between GDELT and GNews, and soft-failure for patents.

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

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

Annotations provide idempotentHint=true. Description adds persistence details (authenticated users permanent, anonymous 24hrs). No contradictions, but could mention overwrite behavior.

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

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

Four sentences, front-loaded with purpose, no unnecessary words. Each 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?

No output schema, but for a write tool it's acceptable. Pairing with recall covers retrieval. Description covers scope, persistence, and pairing adequately.

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

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

Schema coverage is 100% with descriptions. Description adds example key names and value types, marginally extending schema info. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse across conversations/sessions, using key-value pairs. It distinguishes from siblings like forget and recall by explaining the pairing.

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

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

Explicitly says 'use when you discover something worth carrying forward' and pairs with recall/forget. Lacks explicit 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?

The description goes far beyond the readOnlyHint and idempotentHint annotations by detailing that sources are labeled, unresolved identifiers are explicitly listed under `unresolved`, enrichment degrades gracefully, and internal calls cascade through multiple endpoints. This gives the agent a clear picture of what to expect.

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 mostly information-dense, front-loaded with the core purpose and examples. There is minor redundancy, such as listing input types twice, but the overall structure is clear and every sentence earns its place given the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining what the tool returns. It does so thoroughly: for each entity type it lists identifiers and sources, describes fallback behavior, and explains the `unresolved` field. It is fully complete for an agent to decide when to use it and what to expect.

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

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

Even though the schema already covers both parameters, the description adds deep meaning: for `type` it explains the 'company' and 'drug' modes with full output specifications, and for `value` it lists accepted formats (ticker, CIK, ISIN, name) and provides examples like 'ozempic' and 'metformin.' The ISIN-to-LEI mapping detail further enriches parameter understanding.

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

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

The description uses a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also provides example queries and distinguishes itself from sibling tools by noting these identifiers are inputs for other tools, making its unique role explicit.

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

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

It explicitly states 'Use FIRST whenever you have a name but need an ID' and explains that it replaces 2-3 manual lookups. However, it does not mention when not to use the tool or name specific alternative tools, falling short of the 5-level criteria which requires when/when-not/alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by detailing the type of data returned (work patterns, collaboration style, etc.) without contradicting annotations. It could be improved by noting data freshness or limitations.

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: function and outputs, use cases, and an example. Every sentence is essential, front-loaded, and waste-free. Excellent conciseness.

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

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

Despite no output schema, the description thoroughly lists all return categories (work pattern, collaboration style, professionalism signals, activity recency) and provides concrete use cases. This gives the agent sufficient context to understand and use 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?

The input schema has 100% coverage with descriptions for both parameters (_apiKey and github_username). The tool description only restates the example, adding no new semantics. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Get behavioural intelligence for one developer by GitHub username' and lists the specific categories returned. This distinguishes it from sibling tools like 'revternal_enrich_developer' which likely focuses on bio data.

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

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

The description provides clear usage contexts: 'Use to assess engagement, seniority signals, and outreach timing.' However, it does not mention when not to use this tool or explicitly name alternatives, missing the bar for a 5.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context by listing specific return fields and mentioning 'ranked skills breakdown (languages by repo share)', which goes beyond annotations. No contradictions.

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

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

Two sentences plus a one-line example. Extremely concise and front-loaded with the main purpose. Every word earns its place, no fluff.

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

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

Given the low complexity (2 parameters, no output schema), the description fully captures what the tool does and what it returns. It lists multiple return fields and provides an example, so an agent has enough context to use it correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by providing an example usage and clarifying that the _apiKey is injected when omitted, which enhances understanding beyond the schema.

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

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

The description clearly states the verb 'Enrich' and resource 'developer' from a GitHub profile URL, listing specific outputs. However, it does not explicitly differentiate from sibling tools like 'revternal_developer_intel' or 'revternal_search_developers', which have overlapping purpose. Still, the verb and resource are specific enough.

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 tells when to use: 'Use to enrich a lead or candidate you already have a GitHub URL for.' This provides clear context for appropriate usage. It does not explicitly state when not to use or mention alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond these: it explains the default returns an existing record and 'found:false' if none, and that fetch_live=true causes a slower, costlier fresh fetch. It also lists the specific data fields returned, which is useful and not contradictory.

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

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

The description is two sentences, front-loaded with the core purpose, and includes an example. Every sentence earns its place: purpose, behavior, usage context, and a usage example. No fluff or repetition of schema details.

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

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

The tool is a read-only enrichment with a simple input (one required URL) and clear return data. The description explains both operational modes, cost implications, and expected output fields. No output schema exists, so the field list in the description adequately covers return values. Annotations cover safety traits, making this 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 description coverage is 100%, so the baseline is 3. The description adds a concrete example and clarifies the fetch_live behavior in prose, reinforcing the schema's parameter descriptions without significantly expanding them. The example is helpful for correct invocation.

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

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

The description states a specific verb ('enrich') with a clear resource ('one person from their LinkedIn profile URL') and what it returns ('full normalized profile' with fields listed). It also distinguishes from sibling tools by emphasizing 'one person' and 'you already have a LinkedIn URL for', which separates it from people search tools.

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

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

The description explicitly says when to use it ('Use to enrich a lead, candidate, or contact you already have a LinkedIn URL for') and explains the two modes (default vs fetch_live). It does not name an alternative tool explicitly, but the 'already have a LinkedIn URL' condition implies when not to use it (e.g., when you need to search for people).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds value by specifying output contents (profiles indexed, processing status). No contradictions.

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

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

Two sentences plus an example. The first sentence states purpose, the second gives usage guidance, and the example is minimal. No unnecessary words.

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

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

For a simple stats tool with no output schema, the description adequately covers what the tool returns and when to use it. Could mention return format but not strictly necessary.

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

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

Input schema coverage is 100% with clear description for the _apiKey parameter. The description adds no further param details, which is acceptable given the schema is complete.

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

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

Clearly states the tool returns index statistics for the Revternal dataset, specifying 'total profiles indexed and processing status'. This distinctly separates it from sibling tools like revternal_developer_intel or revternal_search_developers.

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

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

Explicitly advises using the tool before search to 'gauge coverage and freshness', giving clear when-to-use context. Does not list alternatives but the sibling set implies other revternal tools are for data retrieval.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds valuable behavioral details: return fields (name, headline, profile fields), opaque cursor for pagination, requirement of at least one filter, and accepted value formats (seniority levels, country codes). This adds context beyond annotations without contradicting them.

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

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

The description is well-structured and efficient: first sentence states purpose, second covers return format, third covers the required-filter constraint, fourth lists enums, fifth gives use cases, and the final line shows an example. Every sentence carries meaningful information with no fluff.

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

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

For a 10-parameter tool with no output schema, the description covers the essential behavioral aspects: return shape, pagination cursor, input constraints, and an example. It relies on the schema for per-parameter semantics, which is acceptable. A minor gap is lack of detail on how multiple filter types combine, but the example partially addresses this.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra value by highlighting the 'at least one filter is required' constraint (not present in schema's required list) and providing a concrete usage example. It also reinforces the searchable dimensions (job title, seniority, location, domain, skills) that map to 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 tool searches Revternal's people-intelligence index for any person (not just developers), with a specific verb and resource. It distinguishes from sibling tools like revternal_search_developers by explicitly broadening scope beyond developers, making it unique.

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

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

The description gives explicit usage context: 'Use for recruiting, GTM prospecting, and lead research when you have criteria rather than a specific profile.' This implies when-not to use (specific profile) and points toward enrich tools for profile-specific needs, though it doesn't name them explicitly.

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

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

Annotations already indicate read-only, idempotent, non-destructive operations. The description adds value by specifying the return fields (GitHub usernames with role, language, location, last-active timestamp) and pagination behavior (limit, offset, default sort). No contradictions.

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

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

Two sentences plus an example; no filler. Front-loaded with core function and use cases. Every sentence contributes meaning.

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

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

Given 8 parameters (all optional, well-described in schema) and no output schema, the description covers the key return data and pagination. It could mention that results are GitHub-only and what happens with no filters, but overall it is sufficient for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions the key filters (role, primary_language, location, active_within_days) and provides an example, but does not add significant meaning beyond the schema descriptions.

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

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

The description clearly states it searches developers by role, language, location, and activity for specific use cases like recruiting and lead-gen. It distinguishes itself from sibling Revternal tools (e.g., revternal_developer_intel, revternal_enrich_developer) by focusing on live search of a large index.

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

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

The description gives explicit use cases (recruiting, GTM, research) and provides a concrete example. It does not explicitly state when not to use this tool versus alternatives, but the sibling context implies it is the primary search tool for developer discovery.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false, so safety is clear. The description adds behavioral context: it probes each entity with 'ai_visibility_check', ranks by score, and returns a ranked list with specific fields. 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 concise sentences followed by a usage example. It is front-loaded with the main action and avoids unnecessary words. Every sentence adds value.

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

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

Given no output schema, the description explains the return format (ranked list with score, confidence, signal density). It also describes the process (probing with ai_visibility_check) and the input structure. For a 4-parameter tool with thorough annotations, this is complete.

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

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

Schema description coverage is 100%, so the schema itself documents all parameters. The description mentions 'entities' and the overall process but adds no extra meaning beyond what the schema provides. 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 compares AI visibility across multiple entities, using the verb 'Compare' and specifying the resource as 'AI visibility across multiple entities'. It distinguishes from sibling 'ai_visibility_check' by being the multi-entity version.

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

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

The description provides clear context: 'Useful for competitive AI-marketing audits' and an example query. It implicitly guides when to use (when comparing multiple entities) but does not explicitly state when not to use or mention alternatives, though the sibling 'ai_visibility_check' is obvious.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds important behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timed-out sources. 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 a single paragraph but well-structured with purpose first, then usage, then return fields, then limitations. It is slightly long but each sentence provides value; could be more concise 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 no output schema, the description fully explains the return value including summary fields (is_latest, license, etc.), per-advisory details, links, and alternative versions. It also covers behavior on failure and NPM-only scope, making the tool's behavior predictable.

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

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

Input schema has 100% coverage with descriptions for both 'package' and 'version'. The description adds extra semantics: scoped packages are accepted, and version defaults to latest when omitted, which is not in the schema.

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

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

The description clearly states the tool's purpose: a composite check for evaluating npm packages combining deps.dev and bundlephobia data. It uses specific verbs ('fans out across') and resource nouns, and the sibling list does not contain any similar tools, so it is well-distinguished.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also specifies the NPM-only scope in v1 and directs users to deps.dev:version for other ecosystems, effectively telling when not to use this tool.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging, and that outputs include character offsets and similarity scores.

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

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

Four well-structured sentences with the main action first, followed by usage context, pairing info, and implementation details. 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?

Despite no output schema, the description covers output features (offsets, scores), limits (200K chars, truncation flag), and pairing with a sibling. Lacks details on edge cases like empty results or errors.

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 reiterates the 200K char cap for 'text' and gives natural-language query examples for 'query', but adds minimal new semantic meaning beyond the schema.

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

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

The description clearly states the tool does semantic search inside a fetched record, with concrete examples like SEC 10-K body or article. It explicitly distinguishes from the sibling ask_pipeworx_grounded by describing how they pair.

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 to use when the record is too big for the prompt, saving context. It also mentions pairing with ask_pipeworx_grounded. However, it doesn't mention when not to use it or alternatives for small texts.

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 (idempotentHint=true, destructiveHint=false), the description adds important behavioral details: subscription requires OAuth account, SMS delivery has a 10/day cap, webhook signing secret is returned only once, and webhook auto-disables after 10 consecutive failures. 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 comprehensive but somewhat lengthy due to detailed examples. It is well-structured with clear sections for types, delivery channels, and prerequisites. Minor improvement could be bullet-point formatting for even easier scanning.

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

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

Given no output schema, the description correctly states the return value (subscription id). It covers prerequisites, all supported types with parameters, delivery options with limitations, and side effects (e.g., webhook secret one-time return). The description is complete for a subscription creation tool.

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

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

The input schema has 100% coverage, but the description significantly enriches each parameter with concrete examples and constraints. For instance, it explains sec_8k item code meanings, polymarket_edge topic and min_spread_bps, fred_series series_id, and delivery channel specifics like phone verification and webhook HMAC signing. This adds substantial value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb ('create') and resource ('subscription'), and distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description provides explicit context for when to use, including the requirement for a Pipeworx OAuth account and that anonymous/BYO cannot persist subscriptions. It lists supported types and delivery channels. However, it does not explicitly state when not to use or name alternatives, though the context implies appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context about the output format (category-bucketed examples with exact tool+argument shape) and that it draws from a live catalog, exceeding the annotation information.

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

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

The description is a single paragraph of three sentences, efficiently conveying purpose, output, and usage. It is front-loaded with trigger phrases and could be slightly tighter, but the information density is high.

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

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

The tool is simple (1 optional parameter) with annotations covering safety. Even without an output schema, the description clearly explains the return type (category-bucketed example questions with tool+argument shape), making it fully complete for an agent's decision-making.

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 a clear parameter description. The description repeats the parameter meaning but does not add significant new interpretation beyond the schema, so 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?

The description clearly states the tool returns category-bucketed example questions and explicitly distinguishes it as the onboarding entry point, differentiating it from sibling tools like ask_pipeworx or compare_entities.

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 it ('Use this FIRST when you do not yet know what Pipeworx can do') and how to call it with or without the topic parameter, with examples of focus areas.

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

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

Description adds behavioral context beyond annotations: ownership check, deactivation (not deletion), and link to historical events via recent_alerts. No contradiction with annotations.

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

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

Two sentences, each adding value. First sentence states purpose, second clarifies behavior. No filler.

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

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

For a simple one-parameter tool with annotations and no output schema, the description provides complete context: ownership, deactivation, impact on historical data, and reference to sibling tool recent_alerts.

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

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

Schema covers the single parameter id with a description, and the tool description does not add further parameter semantics. Baseline score of 3 due to high schema coverage.

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

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

Description clearly states 'Cancel a subscription by id' – a specific verb and resource. It distinguishes from siblings like list_subscriptions and subscribe by focusing on cancellation.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior, providing clear context for when to use and what to expect. Does not explicitly list when not to use, but implied.

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

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

Beyond the readOnly/idempotent annotations, the description discloses critical behavioral details: the meaning of each verdict (could_not_verify means the check did not happen and must not be treated as evidence, unsupported means no source covered), the automatic fallback for non-financial claims, and the presence of verification_error. This added context is substantial and goes well beyond what annotations provide, making the tool's edge cases transparent.

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 and front-loaded with trigger examples, then usage, then return semantics, and an IMPORTANT caveat. Every section earns its place given the tool's complexity. It could be slightly tightened (e.g., the phrase 'routed to the right live source' is somewhat redundant), but overall it is appropriately sized relative to the tool's sophistication.

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

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

With only 2 parameters and no output schema, the description carries the full burden of explaining return values. It thoroughly covers the verdict list, the value with citation, reasoning, and the distinct meanings of could_not_verify and unsupported. It also explains the routing logic for different claim types, making it complete for an AI agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics: it clarifies that tolerance_pct overrides the wording-implied tolerance, suggests values for hallucination detection (1-2), and notes the default cap at 5. It also gives realistic examples for the claim parameter. This enhances the schema without being redundant.

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

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

The description clearly defines the tool as natural-language claim verification against authoritative sources, with a specific verb ('validate claim') and resource (factual claims). It distinguishes itself from siblings by detailing the two verification paths (SEC EDGAR for financial, grounded pipeline for other) and by noting it replaces 4-6 sequential calls, making its scope and value explicit.

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

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

The description explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives examples of trigger phrases and claim types. However, it does not explicitly name alternative sibling tools or state when not to use this tool, only contrasts with the multi-step process it replaces. Thus it meets 'clear context' but lacks explicit exclusions or alternative tool names.

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