Macro Snapshot

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds value by disclosing cost implications (free default vs. BYO key for Anthropic) and the return format per model. 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 main action, default behavior, key condition (API key), return format, and use cases. Every sentence adds value with no redundancy.

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

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

Given no output schema, the description explains the return structure (per-model fields + combined view). It covers parameter usage and main use cases. There is no need for pagination or error handling details for this probing tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context beyond schema: default model, API key format, and the role of the 'context' parameter for disambiguation. This meaningful addition justifies a score of 4.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100). It uses specific verbs ('probe', 'score') and identifies the resource ('LLMs'), distinguishing it from sibling tools like 'scan_competitor_ai_presence' or 'deep_research'.

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') and states when to provide an API key. However, it does not explicitly contrast with sibling tools or specify 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 already declare readOnly, open-world, and idempotent hints, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it routes to 5,724 tools, fills arguments, returns citation URIs, works on every tier, and is a fast default call. It doesn't contradict 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 longer than average but well-structured and front-loaded with the most important guidance. Examples and use-case lists are valuable for an agent. Minor redundancy exists between 'PREFER OVER WEB SEARCH' and later 'Use whenever...' phrasing, but nothing is 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?

Given the tool's broad scope, the description is remarkably complete: it explains what the tool does, when to use it, which alternatives to step up to, how answers are returned, and that it works on every tier. Even without an output schema, it conveys the return format (structured answer with pipeworx:// citation URIs) and enough examples to invoke it correctly.

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

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

Schema description coverage is 100%, with the 'question' parameter described and aliases documented. The tool description adds examples and trigger phrases that help formulate a query, but it doesn't add new meaning about the parameter itself beyond what the schema already provides. 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 what the tool does: it routes natural-language questions to the appropriate one of thousands of verified data tools and returns structured answers with citation URIs. It explicitly differentiates itself from web search and from siblings like ask_pipeworx_grounded and deep_research, so an agent can distinguish it 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?

Provides explicit when-to-use guidance: prefer over web search for factual/current/historical data, use for trigger phrases like 'what is' and 'look up', and start here as the default entry point. It also gives clear step-up conditions for ask_pipeworx_grounded and deep_research, plus notes that breaking-news questions are already handled.

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, open-world, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: experimental candidate routing may or may not be active, the current no-candidate state, and the explicit note that there is no fallback. This is strong transparency for an experimental router.

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

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

The description is front-loaded with the essential beta identity and immediate differentiation from ask_pipeworx. It is slightly wordy with the specific retirement date and repeated emphasis that it is a full working router, but every sentence contributes useful context.

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 universal router with no output schema, the description compensates by explicitly stating the response shape is identical to ask_pipeworx and that the same 5,724 tools are reachable. It also clarifies current behavior and fallback semantics. It still relies on knowledge of ask_pipeworx for the exact response shape, but the pointer is concrete and sufficient in context.

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

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

Schema description coverage is 100% and every parameter is documented as an alias for 'question'. The description only reiterates 'same arguments' without adding new semantic detail, so it stays at the baseline rather than improving on 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?

States a specific verb and resource: it is a beta universal router identical to ask_pipeworx with candidate routing improvements. It explicitly distinguishes from ask_pipeworx ('candidate routing improvements enabled live') and from ask_pipeworx_grounded by pointing to the 'newest routing' use case.

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

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

Provides clear when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies results are compared against the stable router. It does not enumerate when not to use it or mention grounded alternatives, so it misses full exclusion guidance.

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

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

Beyond the annotations (read-only, open-world, idempotent, non-destructive), the description discloses the refusal behavior with exact refusal reasons ('not_in_source','no_tool_match','tool_error','data_truncated','llm_error') and the success return shape including evidence as a verbatim quote. It also reveals the internal routing to 5,724 tools and the extra LLM call cost. No annotation contradiction 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?

Every sentence is information-dense and purposeful: the opening phrase defines the tool, the middle explains routing plus extraction, the next details the return and refusal objects, and the closing gives usage guidance and a cost comparison. It is front-loaded with the core purpose and avoids fluff or repetition.

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

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

Given the tool's complexity (routing across thousands of tools, refusal handling, return type), the description fully covers what an agent needs: success response shape, refusal reason enum, when to prefer the sibling, and the cost tradeoff. With no output schema available, the description compensates by spelling out the exact return payload, making the tool safely invocable.

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 aliases and a clear description of 'question' as natural language input. The description adds no parameter-level detail beyond the schema, which is acceptable but not extra value. Baseline 3 is appropriate because the schema already carries the parameter documentation 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 opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly stating the specific behavioral promise. It then explicitly contrasts with 'Same routing as ask_pipeworx' while explaining the key difference: it extracts answers using ONLY tool result content. This distinguishes it from sibling ask_pipeworx and ask_pipeworx_beta without ambiguity.

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 criteria: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples like financial verdicts and legal claims. It also provides a strong exclusion: 'prefer ask_pipeworx for casual lookups' with the cost rationale of one extra LLM call. This gives the agent clear decision rules versus the 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?

Annotations already declare readOnlyHint=true, idempotentHint=true. The description adds extensive behavioral context: it explains that low-confidence matches short-circuit and block analysis, closed markets return a specific status, fan-out logic, resolution-rule risk, and warning about medium/low matches. This goes far beyond annotations.

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

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

The description is long but well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded purpose. Every sentence adds value, covering many details. However, it could be slightly more concise; some details might be better in an output schema or separate docs.

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 thoroughly explains all response shapes, including edge cases like low-confidence match, closed markets, wide spreads, cancellation rules, and news fallback. It is comprehensive enough for an AI agent to understand the full behavior and response structure.

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

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

Schema description coverage is 100% (all 3 parameters described). The description repeats the parameter formats (slug, URL, text for 'market') but does not add new semantic meaning beyond the schema. Baseline 3 is appropriate as the description is adequate but not additive.

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

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

The description clearly states the tool researches a single Polymarket bet by pulling relevant Pipeworx data. It distinguishes from siblings like polymarket_edges and polymarket_arbitrage by focusing on a specific bet, not aggregates. The verb 'Research' and resource 'a Polymarket bet' are specific.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', providing clear when-to-use guidance. It also implies that this tool is for individual bet analysis, not for scanning multiple bets (which siblings do). No exclusions are needed given the context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinicaltrials for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of 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?

The description is relatively long but front-loaded with example queries and key guidance. Every sentence adds useful information, though the last sentence about replacing 8–15 lookups is somewhat redundant. It could be slightly condensed but remains efficient for the complexity.

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

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

Given the tool has 2 parameters with full schema coverage, no output schema, and annotations covering safety, the description adequately explains return values ('paired data + pipeworx:// citation URIs per entity') and sorting behavior. It also notes the tool's efficiency improvement, making it complete for agent 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% with descriptions. The description adds concrete examples (e.g., '["AAPL","MSFT"]' for companies, '["ozempic","mounjaro"]' for drugs) and clarifies the meaning of the 'type' parameter beyond the enum. This adds 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 explicitly states the tool performs side-by-side comparison of 2-5 companies or drugs in a single parallel call. It provides example queries like 'X vs Y' and 'rank these companies', making the purpose crystal clear. It also distinguishes from sequential single-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?

The description says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and quantifies the efficiency gain ('Replaces 8–15 sequential lookups'). This gives clear when-to-use guidance and identifies alternatives (entity_profile).

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

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

Even with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint already set, the description adds substantial behavioral context: account and paid-tier requirements, parallel routing across 5,724 tools, the findings-packet shape, explicit gaps[] instead of invented answers, contradictions[] scanning, semantic excerpting, hop/citation fields, and expected latency. It also warns about empty gaps[] for topics outside the structured catalog. No statement contradicts the annotations.

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

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

The description is long, but this is a genuinely complex tool and every sentence carries a distinct operational fact: auth, source scope, routing model, return fields, gaps behavior, latency, depth semantics, and alternatives. The critical scoping and account requirements are front-loaded before the mechanics, and nothing feels like filler or restatement of the schema.

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

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

There is no output schema, so the description carries the full burden of explaining what the caller gets back. It covers the findings-packet fields, citations, gaps for unanswerable facets, contradiction flags, hop tracking, and latency expectations. Combined with the auth and usage guidance, the description is complete enough for an agent to invoke the tool correctly and interpret its response.

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 already 3, but the description goes well beyond the schema. It explains that the question should be natural language and that broad/multi-part questions are the intended use case, and it gives per-depth behavior: quick is single-hop, standard adds gap-recovery plus contradictions, thorough adds lead-chasing and a longer second pass. This materially helps an agent choose the right depth.

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

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

The description names a specific verb and resource: it performs 'grounded multi-source research across Pipeworx's 1497 STRUCTURED data sources' in one call, and explicitly contrasts itself with open-web search. It also differentiates itself from the sibling ask_pipeworx by describing decomposition, parallel routing, and the findings packet. This leaves no ambiguity about what the tool does.

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

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

The description gives explicit when-to-use guidance: it is 'best for broad/multi-part questions over structured data', while single lookups and breaking/current-news topics should go to ask_pipeworx. It also provides an account/auth gate by saying unsigned-in users should use ask_pipeworx instead. This is exactly the kind of routing clarity an agent needs.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds that returns top-N tools with full schemas and examples, ready to call. No contradiction, and context is useful beyond annotations.

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

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

Description is 4-5 sentences, front-loaded with purpose, then context, output details, and usage guideline. Every sentence adds value with no redundancy.

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

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

Despite no output schema, the description fully explains what the output contains. All six parameters are covered. The description is complete for an agent to understand 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?

All 6 parameters are fully described in the input schema (100% coverage). Description reinforces that query accepts natural language, but does not add 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 it finds tools by describing data or task, explicitly listing many domains. It distinguishes itself from sibling tools like ask_pipeworx or deep_research by being a discovery tool, not for direct answers.

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 'Call this FIRST when you have many tools available' and 'Use when you need to browse...'. It implies not to use when you already know the tool, but does not explicitly list alternatives.

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

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

The description adds significant behavioral detail beyond the annotations: it fans out across multiple sources, returns specific fields, notes the patent soft-fail timeframe, and explains the news fallback chain. Annotations already indicate readOnly, openWorld, idempotent, non-destructive, and the description is consistent with 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 front-loaded with example queries and packs a lot of information into one dense paragraph. While not using bullet points, it remains fairly concise. Minor improvement could be splitting into clearer sections.

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

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

The description covers input requirements, return fields, source behavior, fallback logic, and limitations (patent soft-fail, name unsupported). Without an output schema, it adequately describes the return values. However, it could mention potential variability in returned fields more explicitly.

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 value by clarifying input formats (e.g., ticker or zero-padded CIK) and reinforcing that names are not supported. It also explains the 'type' parameter is restricted to 'company' with future plans. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call'. It provides example queries and explicitly distinguishes from sibling tools by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and directing to resolve_entity for names.

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: 'ALWAYS PREFER over chaining single-pack... when the user asks for a holistic view'. It also states when not to use: if the user only has a name, use resolve_entity first. This provides clear context and 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 destructiveHint=true and idempotentHint=true. The description adds value by explaining the action as 'delete' and 'clear sensitive data', confirming the destructive nature without contradiction.

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

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

Three sentences, all essential and front-loaded with the action. No redundancy or 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 one-parameter tool with annotations and a clear schema, the description sufficiently covers purpose, usage, and pairing. No gaps remain.

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

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

Schema coverage is 100%, and the parameter description 'Memory key to delete' is already clear. The description does not add extra semantic meaning beyond referencing 'by key', so it meets the baseline.

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

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

The description clearly states the verb 'Delete' and the resource 'previously stored memory by key'. It is distinct from the sibling tools 'remember' and 'recall' implicitly by specifying deletion vs. storage vs. retrieval.

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 specific scenarios for use: stale context, task completion, clearing sensitive data. It does not explicitly state when not to use or name alternatives, but the context is clear and helpful.

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

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

The description explains the process (fetches page, extracts title/description/links, emits markdown) beyond what annotations provide. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with the description, and no contradictions exist.

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-loading the main purpose and listing use cases efficiently. Every sentence adds value without redundancy or wasted words.

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

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

Given the tool's simplicity (2 params, no output schema, rich annotations), the description covers purpose, use cases, and output format ('single text blob'). It is complete enough for an agent to understand 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 coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the schema for parameters 'url' and 'max_links'; it merely mentions 'for any URL' which aligns with the first parameter.

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 AI crawlers, specifying the action (generate), resource (llms.txt), and context (any URL). It distinguishes from siblings by focusing on this specific output format, which is unique among the listed tools.

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

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

The description provides clear use cases: getting a client's site indexed, drafting for own projects, or auditing competitors. It implies when to use the tool but does not explicitly state alternatives or when not to use it, which would improve 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, idempotentHint, and destructiveHint. The description adds that results are 'observations most-recent-first plus the latest value', and mentions default/max limit. No contradictions with annotations.

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

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

Two concise sentences, front-loaded with purpose and usage, no fluff. Every sentence adds value.

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

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

Given the simplicity of the tool (read-only, two parameters) and rich annotations, the description is sufficient. It covers the return format and common use cases, though it could mention that the output is an array of observations.

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 enriches parameters by listing common series IDs and stating default and maximum limit values, adding meaning beyond the schema.

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

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

The description clearly specifies the verb 'Read' and the resource 'FRED series', with examples of common IDs. It distinguishes from sibling tools like 'macro_snapshot' by explicitly stating it can drill into any FRED series.

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 implicitly guides when to use this tool (to get recent history for any specific FRED series) and contrasts with 'macro_snapshot'. It provides many common IDs as usage context, but no explicit when-not or alternative naming.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so description's job is lighter. It adds value by noting default active-only behavior and the effect of include_inactive parameter. Describes returned fields, enhancing transparency without contradicting annotations.

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

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

Two sentences: first states purpose and output fields, second gives usage guidance. No fluff, every sentence is justified and front-loaded. 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?

Given low complexity (1 optional param, no output schema), the description covers purpose, usage, and behavior adequately. It lists return fields and default behavior. No missing critical information; could mention pagination or limits but not needed for this simple tool.

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

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

Schema covers the only parameter (include_inactive) with 100% description coverage, so description doesn't need to add much. It mentions the parameter implicitly but adds no new semantics beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions', providing specific verb and resource. It also enumerates return fields (id, type, params, etc.), making the output clear. Differentiates from siblings like subscribe/unsubscribe by focusing on listing.

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

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

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Tells when to use and provides practical context, distinguishing it from other actions.

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

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

Annotations already cover safety (readOnly, idempotent, not destructive). Description adds behavioral details: it composes 16 FRED series with live crypto, runs them in parallel, returns structured dashboard and callouts. 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 detailed but not overly lengthy. It front-loads the main purpose and lists key outputs. Slight redundancy in listing all series could be trimmed, but overall good.

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 parameters and no output schema, the description fully explains what the tool does and what it returns (dashboard with callouts). It is complete and self-contained.

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

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

No parameters exist, so baseline is 4. The description handles this perfectly by specifying 'No arguments' and not needing to explain any inputs.

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

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

The description clearly states the tool's purpose: providing a comprehensive snapshot of the US/global economy with a specific list of indicators. It distinguishes from siblings by noting it consolidates multiple indicators into one call.

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

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

Explicitly advises using this tool instead of fetching ten indicators separately, implying when to use (broad snapshot) and when not (if only one indicator needed). Could be more specific about 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 are all false, but the description adds rich behavioral context: it states the operation returns a claim_token, can be used later to check resolution, is rate-limited to 5 per day, is free, and doesn't count against tool-call quota. It also tells the agent not to paste end-user prompts. This goes far beyond the minimal annotation info.

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

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

The description is longer than average, but every sentence earns its place: purpose, use cases, exclusions, message constraints, token workflow, rate limits, and quota impact. It is front-loaded with the core action and proceeds logically. Slightly dense but not wasteful.

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

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

Despite having no output schema, the description explains what the tool returns (a claim_token) and how to use it later. It covers content guidelines (don't paste end-user prompt), scope boundaries (only Pipeworx tools), and operational limits (rate limit, quota). For a feedback tool with nested context objects, this is fully complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds some context (e.g., the claim_token usage pattern, the workflow of filing and returning), but it doesn't add new meaning to the individual parameter definitions beyond what the schema already states. It's adequate but not a major enhancement.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from sibling research/query tools by framing it as feedback about Pipeworx tools themselves, not a request for information.

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

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

Explicit when-to-use guidance is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a concrete exclusion—tools from other MCP servers—and tells the agent to file those elsewhere. The claim_token workflow is explained clearly.

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 caching behavior (5min-1h) and data source (CF analytics-engine, no PII), which provides useful context beyond annotations.

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

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

Two concise paragraphs with front-loaded main output. Every sentence adds value without redundancy.

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

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

For a simple read-only tool with one optional param and no output schema, the description covers purpose, usage, caching, data source, and use cases completely.

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

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

Schema has one param with enum and description. The description adds semantic nuance: shorter windows for hot trends, longer windows for steady-state demand, enhancing understanding beyond the enum.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window. It distinguishes from siblings like discover_tools by focusing on real-time popularity 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?

Three explicit use cases are given, covering discovery, validation, and alignment. It does not explicitly state when not to use, but the context is sufficient.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds substantial behavioral context: semantic anchor for cross-event pairs (Jaccard similarity ≥0.30), partition filter for placeholder slugs, fill check against live CLOB depth. 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?

Although lengthy, every sentence adds value. The description is structured logically: main purpose, then detailed breakdown of each mode with examples, then behavioral details like semantic anchor and fill check. Front-loaded with core function. No wasted words.

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

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

Given the tool's complexity (two optional parameters, no output schema), the description covers all needed aspects: input modes, internal processing (monotonicity, partition checks, fill check), output structure (opportunities[], partition_check), and edge cases (placeholder filtering, fill check thresholds). It is sufficiently complete for effective use.

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

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

Schema coverage is 100% (both event and topic described). The description adds significant meaning beyond the schema: event can accept full URLs, topic triggers a cross-event scan with internal search logic. It provides examples of valid slugs and topic questions, greatly aiding 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 clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific examples, making it easy to understand what the tool does relative to siblings.

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

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

Explicit guidance is provided for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. The description also explains when not to trade based on fill check results, offering clear usage boundaries.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details such as caching at 1h, response structure with diagnostics, and tradeable-edge knobs, which go beyond the 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?

The description is verbose but front-loaded with the core purpose. Each sentence adds specific, non-redundant detail such as model families, knobs, and response elements. While dense, it avoids fluff and justifies its length 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 9 parameters, no output schema, and high complexity, the description comprehensively covers the response structure (by_segment, diagnostics), caching behavior, filtering knobs, and even edge cases (Fed bets, placeholder filters). Ideal for an AI agent to understand 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 coverage is 100%, so the schema already documents all parameters. The description adds significant context for many parameters, including slippage explanation, tradeable-edge knobs, and partition filtering logic, 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 tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, explicitly stating its purpose is 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by providing specific model families and response segments.

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 positions the tool as a discovery engine for bettors and provides filtering knobs (min_kelly, min_edge_pp, etc.) to guide when to use it. However, it does not explicitly state when not to use this tool or directly compare to alternatives like polymarket_arbitrage, so it loses one point.

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 and idempotentHint. Description adds valuable context: that decay is computed from daily closes (not intraday), that snapshots have a 60-day TTL, and that gaps in snapshot_dates indicate no scan occurred. This goes beyond annotations.

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

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

The description is dense and informative but could be more structured. It front-loads key purpose but then includes response format and limits in a single paragraph, which may be harder to parse.

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 explains the response structure (tracked, expired, snapshot_dates) with field meanings. It also covers limits and assumptions, making it complete for a read-only data tool.

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

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

Schema description coverage is 100%, and the description restates the parameters with default and max values, which adds minimal value. Baseline 3 is appropriate since the schema already covers semantics.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and whether it's shrinking. This distinguishes it from siblings like polymarket_edges (which likely provides current edges) and polymarket_arbitrage.

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 explains when to use: to distinguish between a fresh wide edge and an old one, with the example that a 3-week-old wide edge exists for a reason. Also details output structure and limits, though does not explicitly say 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 indicate read-only, open-world, idempotent, non-destructive. Description adds behavioral context: it performs a check but warns about risks like partial basket fills converting arb into unhedged directional positions. 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?

Long but dense description with bold headers for REQUIRES, SINGLE-MARKET, BASKET. Every sentence is informative. Could be slightly more concise, but structure aids readability.

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

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

No output schema, but description lists return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and covers both modes with defaults and risk warnings. Comprehensive for a complex tool.

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

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

Schema coverage is 100%, so baseline 3. Description adds semantic meaning: explains single-market vs basket mode, default values, and how size_usd is interpreted (max spend on buys, target proceeds on sells for single-market; settlement notional for basket). Adds significant context.

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

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

The description clearly states it is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It lists specific return fields and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly tells when to use: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. Explains why: theoretical overround on thin books is not capturable, and partial basket fills lead to unhedged directional positions.

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 flag readOnly/openWorld/idempotent, and the description goes well beyond them: it warns that compatibility_codes[] can be non-empty even when matched_pairs>0, explains pairing_unverified means keyword matching not shared resolution source, and discloses that spreads are gross because Kalshi fees are not modeled. It also defines null semantics for temporal_alignment and explains skipped legs, so the agent knows what results mean.

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

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

The description is front-loaded with the purpose and uses labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) for scannability. It is long, and some detail is repeated, but nearly every sentence carries safety or disambiguation value 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 burden of explaining the return contract, and it does: leg-by-leg prices, top_spreads_pp, compatibility_warning/codes, temporal_alignment semantics, fees_note, and skipped counters. It also documents limitations and edge cases (unknown legs never paired, null alignment meaning), so an agent has what it needs to interpret results safely.

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%, giving the baseline of 3, and the schema already documents the override behavior. The description adds the mode distinction—auto-fetch in `topic` vs custom pairing in explicit mode—and asserts both modes run the identical matcher, which is real semantic value beyond the property descriptions.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which immediately distinguishes it from sibling arbitrage/edge tools. It also states the two input modes and the output object, leaving no ambiguity about what operation the tool performs.

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

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

It gives explicit mode guidance: `topic` for 10 pre-mapped macro shortcuts and explicit ticker/slug for custom pairings, including override semantics. It does not name sibling tools as alternatives, but it tells the agent when the shortcut list may mislead ('pre-mapped ≠ tradeable'), which is actionable context for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping detail ('Scoped to your identifier'), pairing behavior, and the dual behavior of omitting vs providing key. Does not mention error handling or rate limits, but annotations cover safety profile.

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 pack core action, usage context, scoping, and tool pairings. Front-loaded with purpose, no redundant phrases. Every sentence adds value.

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

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

For a simple tool with one optional param and no output schema, the description covers purpose, usage, scoping, and relationships. Could mention what happens when key is missing (returns null/error?), but not essential.

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 good parameter descriptions (including 'omit to list all keys'). The description repeats this and gives a concrete example key ('user_research_topic'), which adds marginal value. Baseline 3 is appropriate since schema already does the work.

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

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

The description clearly states the verb 'Retrieve' and 'list' with the resource 'saved keys/values'. It explicitly distinguishes from siblings 'remember' and 'forget' by mentioning pairing. Concrete examples (target ticker, address, research notes) clarify usage.

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?

Describes when to use: 'look up context the agent stored earlier... without re-deriving it from scratch'. Mentions scoping and pairing with remember/forget. Does not explicitly list when NOT to use or provide alternative tool names, 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?

Beyond annotations (read-only, idempotent, non-destructive), the description reveals that mark_read flags events as read, affecting subsequent calls. It also describes the content of returned events, providing full behavioral context.

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

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

The description is concise and front-loaded with the main purpose. Each sentence adds necessary information without redundancy, making it efficient and easy to parse.

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 explains the return format and fields. All 5 parameters are covered with behavioral context, and the tool's role among many siblings is clear.

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?

While schema descriptions cover all 5 parameters, the description adds value by providing an example for type ('sec_8k') and explaining the effect of mark_read. This 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 tool pulls fired events from a subscription feed, specifying what is returned (source, citation_uri, raw payload). It distinctly identifies the tool's function among many siblings.

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

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

Explicitly mentions that polling works fine and provides an alternative endpoint for scripts/dashboards. Also advises on filtering by type and since, and explains mark_read behavior for controlling what appears next.

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 valuable context beyond annotations: fans out to multiple sources, fallback, soft-fail, return structure (changes[] grouped by source, total_changes, 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?

Front-loaded with examples and purpose. Includes many details, but could be slightly more concise. Still efficient for the complexity.

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

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

Complete for a tool with multiple sources, fallback, and varied inputs. Explains return structure and use cases despite no output schema.

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

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

Schema descriptions cover all parameters; description adds examples for 'since' (ISO date, relative shorthand) and 'value' (ticker or CIK). Adds marginal value over schema.

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

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

Description clearly states it provides a change feed for a company, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. Examples like 'What's new with X' and comparison with entity_profile distinguish it from siblings.

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

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

Explicitly says when to use (e.g., 'latest on Y', 'news on Tesla') and when not to (use entity_profile for static profile). Includes fallback logic for GDELT→GNews and soft-fail for USPTO.

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

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

Description adds behavioral details beyond annotations: key-value pair scoped by identifier, persistence for 24 hours for anonymous sessions. Annotations already indicate idempotent and non-destructive, but description adds important expiration and scoping context.

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

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

Three concise sentences: first states purpose, second gives usage guidance, third adds behavioral details. Front-loaded and no wasted words.

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

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

For a simple tool with no output schema, description covers input and use cases well. Does not explicitly state return value, but typical save operation return (e.g., success) is implied. Slight gap for output 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 coverage is 100% with descriptions for both key and value. Description provides example keys but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states 'Save data the agent will need to reuse later', identifying a specific verb and resource. It distinguishes from siblings like recall and forget, and explains the scope across conversations or sessions.

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 you discover something worth carrying forward'. Provides context on persistent vs. anonymous sessions and pairs with recall and forget, offering clear usage guidance.

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

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

The description goes well beyond the annotations, explaining graceful degradation of LEI/FIGI enrichment, explicit reporting of unresolved identifiers, ambiguity handling via figi_candidates, source labeling, and internal cascading lookups. This gives the agent a strong behavioral model without contradicting the read-only and idempotent annotations.

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

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

The description is long but front-loaded with the core purpose and usage guidance. The detailed entity-type sections are dense and somewhat sprawling, yet each part adds needed operational nuance. It could be tightened, but the structure is logical and the key information appears early.

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

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

Given the lack of an output schema, the description thoroughly covers what an agent needs to know: input formats, expected outputs, unresolved identifier behavior, ambiguous match handling, and degradation strategy. No critical operational gap remains.

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 substantial meaning beyond the schema: it explains the type enum, gives concrete examples for value, and warns about passing only the entity name rather than a full noun phrase for bonds. It also clarifies accepted formats like ticker, CIK, ISIN, or name, which are not fully detailed in the schema alone.

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

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

The description uses specific verbs and resources: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes its role as the first step when a name needs to become an ID, and the extensive examples make the purpose unambiguous even among sibling tools like entity_profile 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?

It gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains supported entity types, accepted input forms, and edge cases like ambiguous names and bond issuers. It does not explicitly name alternative tools or state when not to use it, but the 'use first' framing provides clear contextual direction.

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 behavioral details: it probes each entity with ai_visibility_check, returns a ranked list with score, confidence, signal density per entity, and treats the first entity as the subject for narrative. This adds value beyond annotations.

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

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

Two concise sentences, front-loaded with the main action ('Compare AI visibility...'). Every sentence adds value without redundancy. The description is efficiently structured for quick comprehension.

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 (multi-entity comparison, aggregation from another tool), the description explains the process, the ranking, and the output fields (score, confidence, signal density). It also notes the narrative bias. No output schema exists, so the description adequately covers what the agent will receive.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: 'entities' must be 2-8 with first as subject; 'models' defaults to workers-ai and requires _apiKey for anthropic; '_apiKey' passed to api.anthropic.com; 'context' disambiguates common names with example. This enriches the schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities, ranking them by score. It uses specific verbs ('Compare', 'Probes', 'ranks', 'surfaces') and specifies the resource (AI visibility). It distinguishes itself from sibling ai_visibility_check (single probe) and compare_entities (generic comparison).

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

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

The description provides a use case ('competitive AI-marketing audits') and gives an example question. However, it does not explicitly state when not to use this tool or list alternatives (e.g., ai_visibility_check for a single entity). The context is clear but lacks exclusionary guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds key behavioral traits: fans out across two services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts.

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 detailed but front-loaded with the composite nature. Though slightly long, every sentence provides necessary information without redundancy.

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

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

Given no output schema, the description lists all return fields (summary block, per-advisory detail, links, alternative versions) and explains partial failure behavior. It is comprehensive for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by noting that scoped packages are accepted and that version defaults to latest, providing additional context beyond the schema.

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

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

The description clearly states it's a composite check for npm packages covering license, advisories, version history, bundle size, and tree-shaking support. It is distinct from sibling tools, none of which focus on package scanning.

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

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

Explicitly states when to use: when an agent asks about package safety, popularity, or cost. Also clarifies it's NPM-only in v1 and mentions fallback to deps.dev for other ecosystems.

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?

Discloses truncation at 200K chars, embedding model (BGE-base-en), window size, similarity metric, and offset for quote verification. No contradiction with annotations (readOnly, openWorld, idempotent).

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?

Concise yet comprehensive: front-loaded key info, each sentence adds value. 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?

Explains return values (passages with offsets and scores) despite no output schema. Fully covers tool behavior and limitations.

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 queries, default limit, and text truncation flag, providing additional meaning beyond schema.

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

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

Description clearly states it performs semantic search inside a fetched record, with specific examples (SEC 10-K, article). Distinguishes from 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?

Explicitly states when to use: when record is too large for prompt. Mentions sibling tool and provides guidance on pairing with ask_pipeworx_grounded for grounding.

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

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

The description provides extensive behavioral details beyond annotations: requires OAuth, returns subscription ID, delivery channels limits (10/day SMS), webhook auto-disable after 10 failures. 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 fairly long but well-structured, front-loading the purpose. Every sentence adds value, though minor trimming could improve conciseness.

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

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

Given complexity (3 params, nested objects, no output schema), the description is highly complete: explains types, parameters, delivery, requirements, limits, and response content (subscription ID).

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 substantial meaning: explains each type and params structure, delivery options with examples and constraints, and webhook signing secret.

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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes from sibling tools like list_subscriptions 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?

The description explains when to use the tool (to subscribe), prerequisites (Pipeworx OAuth account), and limitations (anonymous/BYO cannot persist). It does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context (category-bucketed examples, tool+argument shape, live catalog) without contradiction, and provides usage behavior (optional topic narrowing).

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

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

The description is front-loaded with example queries and structured logically, but is somewhat lengthy. Every sentence adds value, though it could be slightly more concise.

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

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

Given the tool's role as an onboarding guide with no output schema, the description fully explains what it returns, how to call it, topic options, and when to use it relative to other tools. No gaps.

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

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

Schema coverage is 100% with topic description listing options. The description repeats these options in natural language and adds the nuance that omitting topic yields cross-category spread, but this is marginal added value.

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

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

The description clearly states it returns category-bucketed example questions with tool suggestions, distinguishing it from siblings like ask_pipeworx and compare_entities by positioning it as the onboarding entry point.

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 this FIRST' when the agent doesn't know what Pipeworx can do, and explains how to call it with or without a topic, as well as mentioning related meta-tools for further action.

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

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

The description adds useful context beyond annotations: ownership enforcement, row deactivation, and historical availability. 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 concise sentences with the key information front-loaded, 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?

Complete for a simple tool with one parameter, no output schema; covers purpose, ownership, and effects. Minor gap: no mention of potential errors or prerequisites.

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

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

Schema coverage is 100% and the description does not add extra meaning for the 'id' parameter 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 action ('Cancel a subscription by id') and resource, distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

It explains ownership enforcement and the side effect (deactivation vs deletion), but does not explicitly mention when not to use or contrast 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?

This description goes far beyond the annotations. It explains critical failure semantics: 'could_not_verify means the check did not happen... it is NOT evidence for or against the claim, and must not be shown as one.' It also details the meaning of 'unsupported' (we looked and cover no source), the verdict types returned, and the inclusion of a pipeworx:// citation. The readOnlyHint and idempotentHint are consistent with the description — it performs no mutation. The description adds rich context about errors and return behavior that annotations do not cover.

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

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

The description is moderately long but every sentence adds necessary value: trigger phrases, routing logic, verdict list, failure semantics, and the performance benefit. It is front-loaded with the most actionable information ('Use whenever...') and structured naturally from purpose to behavior to caveats. There is no filler or tautology.

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

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

Despite lacking an output schema, the description fully describes the return payload (verdict, actual value with citation, reasoning) and clarifies the meaning of each error state (could_not_verify, unsupported). It also explains the two distinct pipelines and their scope (financial vs. other). Given the tool's complexity, this is a complete and self-contained description that would allow an agent to invoke it correctly without further documentation.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats the tolerance_pct semantics already present in the schema (e.g., the default, the 0.5–50 range, and the hallucination-detection use case) without adding new parameter-level detail. The claim parameter is also documented in the schema with examples. The description does contextualize parameters within the overall flow, but no additional meaning is added beyond what the schema already provides.

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

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

The description opens with a clear, specific verb-object pair ('validate claim') and immediately defines the tool's role as natural-language claim verification against authoritative sources. It distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research by focusing on issuing a verdict (confirmed, refuted, etc.) and by explicitly describing the two processing paths (SEC EDGAR for financial claims, grounded pipeline for everything else).

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

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

The description provides a direct usage trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also outlines the routing logic (which claims go to the structured path vs. grounded pipeline) and notes that the tool replaces 4–6 sequential calls, giving integration context. It does not explicitly name alternative tools or state when NOT to use it (e.g., for subjective or non-factual questions), so it lacks an explicit exclusion clause but still offers strong guidance.

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