Realestateapi

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

Annotations already indicate a safe read-only, idempotent operation. The description adds important behavior: default free model, BYO key for Anthropic with direct billing, and return structure including per-model fields. 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 two sentences long, front-loaded with the core action, and every sentence adds meaningful information. No redundancy or unnecessary detail.

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

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

Given the tool has 4 parameters (all documented), no output schema but description explains return format, and annotations provide safety, the description is largely complete. It lacks error handling details but that is acceptable for a non-destructive 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?

With 100% schema coverage, the baseline is 3. The description adds value beyond schema by explaining the default model for the 'models' parameter and providing examples for 'entity' and 'context'. It clarifies that '_apiKey' is only needed for Anthropic and how it's used.

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: probing LLMs to score visibility of an entity. It specifies the verb 'probe', resource 'LLMs', and output 'visibility (0-100)'. It distinguishes from sibling tools by focusing on AI model visibility rather than general entity info or 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.' It also explains when to provide an API key for Anthropic. However, it lacks explicit mention of when not to use the tool or alternatives, though the context of sibling tools makes this less critical.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds context about internal routing, stable pipeworx:// citation URIs, broad source coverage, and fast single-call execution. It does not contradict annotations but also does not detail failure modes or what happens when no source can answer.

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, leading with the key 'prefer over web search' message, followed by what it does, examples, and alternatives. The information is dense and every sentence contributes, but it could be tightened without losing value.

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

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

Given the tool's complexity and lack of an output schema, the description covers the return value (structured answer with citations), usage scenarios, and related tools. It is reasonably complete but could mention error handling, unanswerable queries, or more specifics about the returned 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 coverage is 100% for the question parameter and its aliases. The description enriches this by clarifying the scope of acceptable questions through extensive examples and categories (SEC, FDA, FRED, etc.), which helps the agent craft appropriate inputs. However, it adds no syntax or required formatting details beyond the schema.

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

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

The description states that the tool routes questions to the appropriate tool among 5,529 tools across 1,455 verified sources and returns structured answers with citations. It explicitly positions itself as the default entry point and distinguishes from siblings like ask_pipeworx_grounded and 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?

Provides explicit guidance on when to use this tool over web search, listing trigger phrases and example queries. It also tells when to step up to ask_pipeworx_grounded or deep_research and clarifies behavior for breaking news.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context about the beta nature, live candidate routing improvements, the current inactive candidate status, and the fact that it is a full working router. This goes beyond annotations and clarifies potential variability without contradicting them.

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

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

The description is a single, well-structured paragraph. It front-loads the key fact that it's a beta universal router, then efficiently conveys current status, usage, and a clarifying note. Every sentence contributes meaningful 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?

For a tool with high complexity (5,529 tools, no output schema), the description is remarkably complete. It explains the relationship to ask_pipeworx, the current state, the experimental purpose, and the routing comparison mechanism. The absence of an output schema is mitigated by explicitly stating the same response shape as ask_pipeworx.

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

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

The input schema has 100% description coverage, documenting 'question' and all five aliases. The description notes 'same arguments' but does not add further parameter semantics; baseline 3 is appropriate given the schema's completeness.

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 this is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge, fulfilling the requirement of a specific verb+resource+scope.

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

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

The description explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and notes that results are compared against the stable router. This provides clear when-to-use guidance and differentiates it from the stable 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?

Beyond annotations, describes exact return shape on success (answer, evidence, confidence, source, fetched_at) and explicit refusal reasons on failure. Discloses the extra LLM call cost and that only tool result content is used. No contradiction with readOnlyHint/idempotentHint; the refusal behavior is rich additional 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?

Five sentences, densely packed with essential information: purpose, routing mechanics, return contract, usage guidance, and cost tradeoff. No filler; the long return-type sentence is justified because no output schema exists.

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

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

For a complex tool with no output schema, the description fully explains success/failure contracts, refusal semantics, cost, and when to prefer the alternative. It is complete enough for an agent to select and invoke correctly.

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

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

Schema covers all six parameters (one required plus five aliases) with 100% coverage, including the note that question accepts aliases. The description adds no parameter-specific details, so baseline 3 applies.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode that extracts answers grounded in tool results, distinguishing it from sibling ask_pipeworx. Specific verb 'EXTRACTS' plus resource scope (tool result content) makes the purpose unambiguous.

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

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

Explicitly states when to use: whenever answers will be quoted, cited, or acted on and facts must not be invented, with examples. Explicitly names alternative: prefer ask_pipeworx for casual lookups due to extra LLM cost, and clarifies same routing.

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

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

The description goes far beyond annotations, detailing fan-out behavior for various bet types, response shapes, resolver contract (match confidence, alternatives), parent_event extractor, news fallback mechanisms, safety short-circuits for low-confidence matches and closed markets, and resolution-rule risk for cancellation. No contradiction with annotations (all imply safe, read-only, idempotent behavior).

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

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

The description is very long and covers many details without clear section breaks. While every sentence is informative, it is not concise and could benefit from more structured presentation (e.g., bullet points). However, the complexity of the tool justifies some length.

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

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

Given the complexity of the tool (multiple classifiers, fan-outs, response structures, edge cases), the description is remarkably complete. It covers input formats, behavior, output shape, safety mechanisms, and special cases like closed markets and wide spreads. No output schema exists, so the detailed description of response fields is essential and well-provided.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'market' parameter can be a slug, URL, or question text; the 'depth' parameter defaults to thorough; and 'include_raw' when to use. Examples are provided. This adds context beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and provides example use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). This distinguishes it from sibling tools like polymarket_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?

The description explicitly states when to use the tool: for research questions about betting on Polymarket. It provides example use cases and mentions the classifiers and fan-out logic. However, it does not explicitly state when not to use it or compare directly with alternatives, though the context implies differentiation.

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. The description adds significant context: for companies it pulls latest 10-K data (revenue, net income, cash, debt) from EDGAR/XBRL with correct fiscal year handling; for drugs it pulls FAERS counts, FDA approvals, and trial counts. It also notes sorted results and citation URIs. Lacks details on rate limits or error handling.

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

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

The description is a single dense paragraph that front-loads example queries and key guidance. Every sentence adds value, but it could be slightly more structured with bullet points. However, it remains efficient and actionable.

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

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

Given no output schema, the description adequately covers return value components (paired data, sorted by primary metric, citation URIs). It explains data sources for both entity types. It does not specify exact response format or pagination, but provides enough for an agent to understand what to expect.

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

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

Schema coverage is 100% with descriptions, but the description adds substantial meaning: it explains that 'values' can be tickers/CIKs for companies or drug names, and specifies the data sources (SEC EDGAR for companies, FAERS/FDA for drugs). This goes well beyond the schema's enum and array constraints.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, using specific verbs and resource types. It distinguishes from sibling tools like entity_profile by emphasizing parallel vs. sequential lookups. Example queries like 'compare X and Y' provide immediate clarity.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing strong usage guidance. It lists example user intents. However, it does not specify when NOT to use the tool or list alternatives for other use cases.

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

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

Annotations already indicate readOnly/idempotent/non-destructive, and the description substantially enriches this by adding expected latency (15-60s, up to ~90s), the guarantee that gaps are never invented, how citations are made resolvable, the hop field, contradictions[], and source excerpting behavior. 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 long but dense, with no wasted sentences. It is front-loaded with the account requirement and the critical 'use ask_pipeworx instead' fallback. The single-paragraph structure is somewhat overwhelming for its length, but every sentence serves a purpose, so it earns a score above the minimum.

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

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

For a complex tool with no output schema, the description comprehensively covers inputs, expected outputs, timing, error behavior (explicit gaps[]), citation semantics, account tiers, and differences from alternatives. It is effectively self-contained for an agent deciding whether and how to invoke it.

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

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

Although schema coverage is 100%, the description adds meaning beyond the schema: it explains depth levels in terms of 'gap recovery', 'contradictions[] scan', and paid-tier behavior, and clarifies that question decomposition is the point of the question parameter. This is additive, not redundant.

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

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

The description clearly states the tool's verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call.' It distinguishes itself from siblings by explicitly noting this is NOT open-web search and contrasting with ask_pipeworx for single lookups and current news.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also states an account prerequisite and directs unsigned users to ask_pipeworx instead.

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

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

Annotations indicate readOnly, idempotent, non-destructive. The description adds that returned tools are 'ready to call directly, no second schema lookup needed,' which is valuable behavioral context beyond the annotations themselves.

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

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

Single paragraph, front-loaded with main purpose, every sentence provides distinct info. 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?

Even without output schema, the description fully explains what the tool returns (top-N tools with names, descriptions, schemas, examples). For a discovery tool, this is complete and actionable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by mentioning aliases for query parameter and providing concrete examples (e.g., 'analyze housing market trends'), though it does not deeply explain parameter usage beyond the schema.

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

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

The description clearly states the tool's purpose: finding tools by describing the data or task. It lists many specific domains (SEC filings, financials, FDA drugs, etc.) and explains that it returns top-N relevant tools with full schemas, distinguishing it from specific task 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?

Provides explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set.' While it doesn't explicitly state when not to use it, the context implies it's for discovery rather than executing a specific task.

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, etc. The description adds significant behavioral context: fans across multiple sources, returns specific fields, notes patent API sunset with soft-fail, and news fallback logic. Minor deduction: does not explicitly state that it batches all calls and may have latency.

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 packed with useful information across ~8 sentences, front-loaded with user query examples. While efficient, it could be slightly tighter by combining source enumeration into a single sentence. Still well-structured for 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?

Despite no output schema, the description thoroughly explains what is returned: cik, company_name, recent_filings (with URIs), fundamentals, patents, news, LEI. It also notes limitations (patent sunset, fallback logic) and source details, making the tool's behavior fully understandable.

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

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

Schema coverage is 100% and description echoes schema info. However, description adds value with concrete examples ('AAPL', '0000320193'), explains zero-padded CIK format, and reinforces the link to resolve_entity. This extra context justifies a 4 rather than 3.

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

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

The description clearly states 'full cross-source profile of a US public company' with specific examples ('Tell me about X', 'research Acme'), distinguishing it from sibling tools that likely perform single-source lookups. It emphasizes 'ONE parallel call' vs chaining, setting clear scope.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view.' Also warns that names are not supported and directs to 'resolve_entity first if you only have a name,' providing clear when-to-use and when-not-to-use guidance.

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

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

The description 'Delete' aligns with the destructiveHint annotation. It adds context beyond annotations by explaining the purpose (clearing stale or sensitive data) and pairing with other tools, which helps the agent understand behavior.

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

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

The description is two sentences long, with the first sentence stating the core purpose and the second sentence providing usage guidance. No filler or redundant information.

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

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

For a tool with only one required parameter and no output schema, the description is fully complete: it explains what the tool does, when to use it, and how the parameter works. No additional information is needed.

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

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

Schema coverage is 100% and the parameter 'key' is described in the schema. The description adds 'previously stored memory by key,' which reinforces the parameter meaning but does not add new information 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 action ('Delete a previously stored memory by key'), with a specific verb and resource. It distinguishes the tool's purpose from siblings like remember and recall.

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

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

The description provides explicit guidance on when to use the tool: when context is stale, task done, or to clear sensitive data. It mentions pairing with remember and recall for context, but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format. Output is a single text blob.' No contradiction.

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

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

Two efficient sentences plus a short bulleted use-case list. No wasted words; front-loaded with the core action and purpose.

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

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

No output schema exists, but description explains the output format. Parameters are well-covered in schema. Use cases are clear. For a simple tool with 2 params, the description is fully adequate.

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

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

Schema description coverage is 100% with good descriptions for both parameters (url and max_links). Description does not add extra semantics beyond what the schema already provides, so baseline of 3 is appropriate.

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

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

Starts with a specific verb and resource ('Generate a production-ready llms.txt file for any URL'), and distinguishes from sibling tools by mentioning AI crawlers (ChatGPT, Claude, Perplexity) and specific use cases like auditing competitors.

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

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

Explicitly lists three use cases: getting a client's site indexed, drafting for own project, or auditing competitor's AI visibility. No explicit 'when not to use', but positive guidance 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 indicate readOnlyHint, idempotentHint, and destructiveHint false. Description adds behavioral detail: returns specific fields and defaults to active subscriptions only, with optional inactive inclusion. No contradictions.

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

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

Two concise sentences: first states purpose and output fields, second provides usage guidelines. No redundant information.

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

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

For a simple tool with one optional parameter and no output schema, the description covers return structure, functionality, and usage context thoroughly.

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

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

Schema coverage is 100% and schema already describes the parameter. Description clarifies the default behavior ('active' vs include_inactive) but adds no new syntax or format beyond schema.

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

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

The description states the tool lists the caller's active subscriptions, specifies return fields (id, type, params, etc.), and distinguishes it from sibling tools (subscribe, unsubscribe) by its review purpose.

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

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

Explicitly instructs when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for tool 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 provide only false hints (readOnly, openWorld, idempotent, destructive), which add no positive disclosure. The description compensates by revealing rate limits (5/day), the claim_token follow-up mechanism, no quota impact, and that the team reads digests daily. It does not describe the underlying write operation (creating a feedback ticket) in explicit side-effect terms, but the intended behavior is clear.

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

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

The description is a single dense paragraph, but it is front-loaded with the core purpose and each subsequent sentence adds a distinct piece of operational guidance (scope, claiming, rate limits). It is longer than minimal, but every sentence earns its place; minor structure improvements could use bullets.

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 feedback tool with no output schema, the description thoroughly covers behavior: what happens when filing (returns a claim_token), how to check status later, daily review cadence, rate limits, and scope boundary. It is complete enough for an agent to select and invoke the tool correctly in all described scenarios.

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 goes beyond the schema by explaining how claim_token works as a follow-up read mechanism ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), and gives message writing guidance about not pasting end-user prompts. This adds meaningful semantic 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates concrete use cases (bug, feature, data gap, praise) and clearly distinguishes itself from sibling tools by being the designated feedback channel for Pipeworx 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?

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 clear exclusion for tools from other MCP servers and advises filing with that server instead, naming 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 indicate readOnly, idempotent, and non-destructive. Description adds: derived from CF analytics-engine, no PII, caching behavior (5min-1h). 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?

Efficiently structured with output summary first, then use cases, then technical details. No unnecessary words; every sentence adds value.

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

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

For a simple read-only tool with one parameter, the description covers purpose, use cases, data source, and caching. No output schema needed; complete 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?

Only one parameter (window) with 100% schema coverage. Description adds meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' enhancing the enum values.

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

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

Clearly states it returns 'top tools, top packs, and total call volume over a recent window'. Uses specific verbs and resource description, distinguishing it from siblings like discover_tools or ask_pipeworx.

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

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

Lists three specific use cases (discovering hot data sources, confirming popular tool, alignment). Does not explicitly state when not to use, but provides clear context for when it is appropriate.

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

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

Annotations indicate read-only, idempotent, open-world semantics. The description goes well beyond by detailing internal checks (semantic anchor, partition filter, fill check with CLOB depth), explaining return conditions (realizable_edge_pp ≤ 0 implies no valid trade), and describing output fields.

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

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

Though lengthy, every sentence is informative and adds value. The structure is logical: main purpose first, then mode explanations, followed by detailed sub-checks and response format. It earns its length without redundancy.

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

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

The description fully compensates for the lack of output schema by explicitly listing response fields (opportunities[], partition_check, fill_check details). It covers all major behavioral aspects and handles edge cases (skipped_low_similarity, placeholders_filtered, thin_legs[]).

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

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

Input schema covers both parameters with descriptions, but the tool description adds significant context: examples of event slugs, acceptance of full URLs, explanation of what topic does with seed questions, and the underlying logic (Jaccard similarity, placeholder filtering). This substantially aids correct parameter usage.

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

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

The description explicitly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between modes (no args, event, topic) and explains what each does, making the purpose unmistakable.

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

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

The description provides explicit guidance on when to use each call mode: no args for trending scan, event for a specific market (recommended), and topic for cross-event scanning. It even notes limitations such as partition filter and placeholder slugs, and suggests when to use polymarket_fill_risk for custom sizing.

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

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

The description extensively discloses behavioral traits beyond annotations: caching at KV level (1h), detailed model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), edge calculations (net of slippage, Kelly fractions capped at 0.25), response structure (by_segment, fed_candidates, _diagnostics), and tradeable-edge knobs. 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 verbose (nearly 300 words) but well-structured with sections and front-loaded purpose. It could be more concise, but the density of information is reasonable 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?

Despite lacking an output schema, the description fully explains the response structure (by_segment, diagnostics, fed candidates) and how to interpret results. It covers caching, filters, edge calculations, and segment-specific details, making the tool's behavior and output completely understandable.

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 each parameter having a clear description. The tool description adds marginal value by explaining the purpose of knobs (e.g., min_partition_leg_kelly's behavior for partition arbs), but the schema already provides adequate semantics. Baseline 3 is appropriate.

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

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

The description clearly states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifically targets the 'what should I bet on today' use case, distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by detailing three model families and tradeable-edge knobs.

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

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

The description provides clear context on when to use the tool (discovering opportunities without paging hundreds of markets) but does not explicitly compare with sibling tools or state when not to use it. The inclusion of filters and knobs implies usage scenarios, but explicit guidance on alternatives is missing.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds significant behavioral details: reads snapshots, returns time-series, trend, decay, and explains data sources and limitations. No contradiction with annotations.

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

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

Description is detailed but efficiently structured, starting with high-level purpose then diving into response format and limits. Every sentence adds value; however, the response format section is somewhat long but necessary given no output 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?

Despite no output schema, description fully explains the response structure (tracked, expired, snapshot_dates) covering fields, meaning, and edge cases. Also notes limits like 60-day TTL and snapshot gaps. Complete for the tool's complexity.

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

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

Schema covers 100% of parameters with basic descriptions. Description adds meaning to 'days' (default 14, max 30) and 'window' (snapshot family with examples 24hr, 1wk, 1mo). Enhances understanding beyond schema.

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

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

Description clearly states purpose: edge persistence and decay telemetry from daily snapshots. Distinguishes from sibling polymarket_edges by focusing on historical time-series and trends, answering 'how long has this edge existed and is it shrinking?'

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

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

Description explains when to use: to assess edge age and decay, contrasting fresh vs old edges. Implicitly indicates not to use for just current edge values (use polymarket_edges instead). Does not explicitly list exclusion criteria but provides clear context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about risks like forced directional risk from partial fills. 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 well-structured with bold headings for single-market and basket modes, making it scannable. It is detailed but not excessively verbose; however, it repeats some information (e.g., return fields) and could be more concise by using bullet points. Front-loaded with essential purpose and usage rule.

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

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

Given the complexity (two modes, many return fields, no output schema), the description is comprehensive. It covers all return fields, explains mode differences, provides usage context, and warns about pitfalls (thin books, directional risk). It equips an AI agent to select and invoke the tool correctly in diverse scenarios.

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 meaning beyond schema: explains side auto-detection for basket mode, clarifies size_usd interpretation for buys vs sells and as settlement notional for baskets, and describes default behavior. This is useful but not exhaustive; it could detail constraints like share size for baskets.

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

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

The description clearly states the tool's function: a realizable vs theoretical edge check against live CLOB order-book depth. It distinguishes two modes (single-market and basket) with specific actions like walking the ladder and returning detailed information. This exceeds a vague purpose and differentiates from siblings 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 states when to use this tool: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. It also explains why (theoretical overround not capturable, partial fills create directional risk), providing clear guidance on when not to rely solely on theoretical values.

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

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

Annotations already mark readOnly, idempotent, non-destructive. Description adds detailed behavior: two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and notes that real spreads are rarer than the shortcut list suggests.

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

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

Well-structured with clear sections, front-loaded core concept. However, somewhat verbose; could be tightened without losing information. Still, all sentences add value.

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

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

Given no output schema, the description thoroughly explains return values (leg prices, top spreads, compatibility warning, temporal alignment, skipped counters). Covers edge cases and meaning of safety fields, making the tool fully comprehensible.

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

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

Schema coverage is 100%, but description adds significant context: explains topic shortcuts list, how explicit parameters override topic-mapped side, and provides example usages. Goes beyond schema to explain interplay between parameters.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same question, with two modes (topic shortcuts and explicit pairings), distinguishing it from siblings like 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 (comparing spreads across venues) and warns that most pre-mapped topics return compatibility warnings, so not all shortcuts are tradeable. Provides criteria for meaningful spreads via safety fields.

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. The description adds value by detailing the return fields and providing an example. No contradictions. Could mention rate limits or authentication requirements beyond the API key.

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

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

The description is only two sentences, with the first stating purpose and return fields, and the second providing a concrete example. No filler or redundant information.

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

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

Given the tool fetches property details and has no output schema, listing return fields (owner, value, sale, characteristics, mortgage) provides adequate context. Could be more detailed about additional data points like tax history.

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

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

Schema coverage is 100% with parameter descriptions. The description adds an example showing usage of address and _apiKey, and clarifies that id or address are alternatives. This aids understanding beyond schema alone.

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

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

The description clearly states the tool retrieves full property detail by id or address, listing key return fields (owner, estimated value, last sale, characteristics, mortgage). It distinguishes from sibling tools like realestateapi_property_search which is for searching properties.

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

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

The description implies usage when you have a specific property id or address, but does not explicitly state when to use this tool versus alternatives (e.g., after a search). No when-not or exclusion criteria are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds specific behavioral traits: it returns matching properties with specified fields and demonstrates usage with filters. It does not contradict annotations and provides useful detail about return content.

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

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

The description is two sentences plus a well-formatted JSON example. It is front-loaded with the core purpose and efficiently conveys usage. Every element is necessary and 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 11 parameters and no output schema, the description covers the purpose, input filters, and return fields. However, it does not describe pagination, error handling, or exact response structure. With full schema coverage and annotations, it is mostly complete but leaves some ambiguity for the agent.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds value by showing a concrete example with multiple parameters and mentioning defaults (e.g., size default 10, max 50). This helps the agent understand parameter interplay 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 starts with 'Search properties by city/state/filters' which clearly states the action and resource. It lists specific filters (off-market, absentee-owner, value range) and mentions return fields (address, owner, beds/baths, estimated value). The sibling tools include realestateapi_property_detail, so this tool's purpose is distinct as a search function.

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 no explicit guidance on when to use this tool over alternatives like realestateapi_property_detail or realestateapi_skip_trace. It gives an example but no context about prerequisites, when not to use, or comparison with siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds that it is a 'pure passthrough, nothing is stored,' which provides extra context about data handling. It also states the return includes owner name plus phone numbers and emails, which is behavioral information 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 a single sentence plus a code example, both highly relevant and front-loaded. No unnecessary words; every element serves a purpose.

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

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

Given the absence of an output schema, the description sufficiently explains return values (owner name, phone, emails). Parameter descriptions and annotations cover safety and behavior. The description is complete for a well-understood third-party API tool.

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

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

The input schema has 100% description coverage. The description includes an example call showing usage and notes that optional parameters last_name and first_name improve match accuracy, adding meaning beyond the schema descriptions.

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

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

The description clearly states it 'skip-traces' owner contact info for an address, returning owner name, phone numbers, and emails. The verb 'skip-trace' is specific and the resource 'owner contact info for an address' is well-defined. It distinguishes from sibling tools like 'realestateapi_property_detail' and 'realestateapi_property_search'.

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

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

The description implies use when needing owner contact info for a property address. It mentions the tool is a 'pure passthrough' with no storage, which is a usage caution. However, it does not explicitly list when to use or when not to use, but the context is clear given the tool's purpose.

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=true, idempotentHint=true, destructiveHint=false, so description carries lower burden. Adds valuable context: scoped to user identifier (anonymous IP, BYO key hash, or account ID) and pairing with save/forget operations.

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, each earning its place: first states action, second adds usage context and example use cases, third covers scoping and pairing. 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 retrieval tool with one optional parameter and no output schema, the description fully explains behavior, scoping, key omission, and pairing with siblings. No gaps.

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

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

Schema coverage is 100% with one optional string parameter. Description adds meaning beyond the schema by explaining that omitting the key lists all saved keys, which is critical usage info.

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

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

Description clearly states the action ('retrieve' a value or 'list' all keys) and the resource (memory saved via remember). It explicitly names sibling tools (remember, forget) for differentiation.

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

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

Describes when to use: to recall previously stored context without recomputing. Implicitly advises against using for saving (use remember) or deleting (use forget). Could be more explicit about when not to use, but context from sibling names and pairing 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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds the key behavioral detail that setting mark_read:true flags events read, affecting subsequent polls. This goes beyond annotations without contradicting them. No further rate limits or side effects are disclosed.

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

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

The description is a single paragraph of 5 sentences covering purpose, output, filters, and an alternative endpoint. It is reasonably concise, though it could be broken into bullet points for easier scanning. The main purpose is front-loaded.

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

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

Given 5 optional parameters, no output schema, and informative annotations, the description adequately covers the tool's behavior, key outputs, and usage context. It mentions the most important fields and provides an external alternative. The lack of output format detail is acceptable since the output is likely a list of events with the mentioned fields.

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

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

With 100% schema description coverage, baseline is 3. The description adds value by providing an example filter value ('sec_8k'), clarifying that 'since' is an ISO timestamp, and explaining the effect of mark_read. This enriches the meaning beyond the schema's short 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 pulls fired events from a subscription feed, specifying the resource (alerts) and action (pull). It distinguishes by mentioning the fields returned (source, citation_uri, payload) and filtering options, making the purpose specific and unambiguous.

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

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

The description implies use for polling and mentions an alternative endpoint for scripts/dashboards, but does not explicitly state when to choose this tool over siblings or when not to use it. The alternative reference is helpful but lacks direct comparative 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?

Description reveals parallel fan-out to three sources, GDELT→GNews fallback logic, USPTO soft-fail due to API sunset, and return structure (changes grouped by source, total_changes, citation URIs). Annotations (readOnlyHint, idempotentHint, etc.) are consistent and the description adds valuable behavioral context beyond 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?

Description is moderately long but each sentence contributes unique information (examples, source details, fallback, sibling distinction). Front-loaded with query patterns, then technical details. Could be slightly trimmed, but no wasted sentences.

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

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

Given the tool's complexity (multiple sources, fallback, soft-fail) and lack of output schema, the description covers essential behavior and return shape. Mentions citation URIs but doesn't explain them deeply. Still, agents have enough to decide and invoke correctly.

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

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

All three parameters are described in the schema (100% coverage). The description adds practical usage guidance: example relative values for 'since', typical monitoring range, and acceptable formats for 'value' (ticker or CIK). This enhances the schema's basic descriptions.

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

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

Description clearly states the tool provides a change feed for a company across multiple sources (SEC, GDELT/GNews, USPTO) in a single parallel call. It explicitly distinguishes itself from the sibling tool 'entity_profile', which provides static profiles.

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?

Includes example queries, typical usage ('30d' or '1m' for monitoring), and fallback behavior (GDELT preferred, GNews on rate limit/5xx). Also advises when to use 'entity_profile' instead. Does not exhaustively cover when not to use, but sufficient for most cases.

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 idempotentHint=true and destructiveHint=false. The description adds valuable context: memory scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous, and that it's a key-value store. 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?

Four sentences, front-loaded with core purpose. Every sentence adds essential information (when to use, scoping, persistence, pairing with sibling tools). 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 2-parameter write tool with no output schema, the description fully covers purpose, usage, behavior, and lifecycle. No gaps given the tool's complexity.

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

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

Schema coverage is 100% with descriptions for key and value. The description provides example key formats and notes value can be any text, but these add minimal information beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions. It provides concrete examples (resolved ticker, target address, user preference) and distinguishes from siblings (recall, forget) by naming them.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and instructs to pair with recall and forget. Also notes scope (by identifier) and lifespan differences for authenticated vs. anonymous users.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds substantial context: unresolved identifiers are explicitly listed under 'unresolved' rather than omitted, every identifier is labeled with its source, and GLEIF/OpenFIGI enrichment degrades gracefully with EDGAR identifiers still returned. It also discloses the cascading internal lookups, giving the agent a realistic expectation of the tool's behavior.

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

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

The description is appropriately front-loaded with usage examples and a clear verb-object structure. It is longer than average, but every sentence adds useful detail (supported types, resolution behavior, degradation, output conventions). It is organized into recognizable segments (intro, supported types, behavior notes) without fluff. A slight deduction for density, but it remains accessible and earns its length.

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

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

Since there is no output schema, the description carries the full responsibility of explaining return values and side effects. It clearly describes that the tool returns canonical identifiers (CIK, ticker, LEI, FIGI, RxCUI, etc.), labels them with sources, and explicitly lists unresolved ones. It also covers graceful degradation and cascading lookups. For a tool with complex behavior and no output schema, this description is exceptionally complete and actionable.

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 descriptions already cover the enum values and value formats with examples ('AAPL', '0000320193', 'ozempic'). The tool description reinforces this but does not add new parameter-level semantics beyond what is in the schema. It mentions accepted input formats for company and drug, but that duplicates the schema descriptions. Therefore, a baseline 3 is appropriate since no significant additional parameter meaning is provided.

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 concrete example queries and a clear definition: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It specifies supported types (company, drug) and the exact identifiers returned. This clearly distinguishes it from sibling tools like entity_profile or compare_entities, which focus on profiles or comparisons, not identifier lookup.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID.' Also notes it 'replaces 2-3 manual lookups,' giving the agent a clear trigger condition and rationale. It also clarifies when to use company vs. drug type, and mentions graceful degradation if enrichment sources are unavailable, providing additional context for when results may be partial.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds significant behavioral details: it probes each entity with 'ai_visibility_check', ranks results, and treats the first entry as the subject. No contradiction with annotations.

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

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

The description is two sentences with a third example sentence, all front-loaded with purpose and key details. No wasted words; every sentence contributes to understanding.

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

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

Given four parameters and no output schema, the description covers purpose, behavior, parameters, output format (score, confidence, signal density), and use case. It lacks mention of error handling or edge cases, but with strong annotations, it is mostly complete.

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

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

All parameters have schema descriptions (100% coverage). The description adds value by explaining the 'entities' parameter's first-entry treatment, the 'context' parameter's disambiguation role, and the 'models' parameter's supported options and default, enriching the schema meaning.

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

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

The description clearly states the tool compares AI visibility across multiple entities, uses 'ai_visibility_check', ranks by score, and returns a ranked list. This distinguishes it from sibling tools like 'ai_visibility_check' (single entity) 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?

Explicitly mentions 'Useful for competitive AI-marketing audits' and gives an example question, providing clear context for when to use. However, it does not explicitly state when not to use or mention specific alternative tools.

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

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

Description fully aligns with annotations (readOnly, idempotent, not destructive). Adds context: fans out across external services, partial failures degrade gracefully with sources_failed reporting, and bundlephobia timing out is possible. 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 well-structured and front-loaded with the core purpose. Each sentence provides essential information: composite nature, sources, return block, usage guidance, limitations, and partial failure handling. No waste or redundancy.

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

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

Given the complexity (composite of two external services), no output schema, and only 2 parameters, the description is remarkably complete. It details the summary block fields, per-advisory details, links, alternative versions, and degradation behavior. No obvious gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema: confirms scoped packages accepted for 'package' and clarifies default behavior for 'version' (defaults to latest). This extra guidance 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 identifies it as a composite check for npm packages that combines deps.dev and bundlephobia data. It uses specific verbs ('scan', 'check') and resource ('dependency'), and effectively distinguishes from sibling tools by emphasizing it's a single-call composite, unlike individual API queries.

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

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

Explicitly states when to use it: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". Provides exclusion criteria: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. Also mentions potential delays and graceful degradation.

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

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

Annotations already provide readOnlyHint, etc. The description adds details: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char limit with truncation flag. 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?

Concise at about 4 sentences, front-loaded with main purpose. Every sentence adds value: use case, benefit, pairing, technical details. No wasted words.

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

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

Given the tool's complexity (semantic search, embeddings, character offsets, limit) and no output schema, the description is complete. It explains behavior, limits, and expected return values (passages with offsets, scores).

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

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

Schema coverage is 100%, and the description adds examples for the query parameter (e.g., 'supply-chain risk'), clarifies the text parameter's max length, and specifies the limit default and range. 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 clearly states 'Semantic search INSIDE a fetched record' with specific verb, resource, and scope. It distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded and the context-saving benefit.

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

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

Explicitly says when to use: 'when the record is too big to cram into the prompt' and why it's better: saves context, returns passages with offsets. Also provides pairing guidance with ask_pipeworx_grounded.

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 significant detail beyond annotations: auth requirements, type-specific params, delivery options, rate limits (10/day SMS), webhook auto-disable. Annotations already indicate writing and idempotent; description does not contradict.

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

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

Dense but well-structured; front-loaded with purpose, then details. Every sentence adds value, though a bit lengthy due to embedded examples.

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

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

Covers requirements, types, params, delivery channels, limitations, and return value (subscription ID). Lacks explicit error handling info, but overall comprehensive for a create tool with 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 coverage is 100%, but description adds examples, constraints (e.g., 'sponsor or condition required'), and type-specific details that complement the schema definitions.

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

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

Clearly states it creates a proactive monitoring subscription and returns the subscription ID. Distinct from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

Provides explicit requirements (OAuth account, types, delivery channels) and examples. Does not explicitly list when to avoid or compare to alternatives, but 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 already show readOnly=true and idempotent=true. Description adds critical behavioral context: it is the onboarding entry point, returns live catalog-derived samples, and can be called with zero arguments. No contradictions.

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

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

The description is front-loaded with the core question and purpose. It is slightly verbose due to listing categories, but every sentence adds value. Could be trimmed slightly but remains well-structured.

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

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

Given the tool's role as an onboarding entry point, the description fully explains its return format (category-bucketed examples with tool+argument shape), invocation options, and relationship to meta-tools. No output schema is needed.

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

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

Schema coverage is 100% and the schema already describes the 'topic' parameter with allowed values and behavior. The description reiterates these options but does not add new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description explicitly states the tool returns category-bucketed example questions for onboarding. It uses specific verbs and resources ('returns example questions') and distinguishes itself by being the first call when unfamiliar with Pipeworx.

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

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

Clear when to use: 'FIRST when you do not yet know what Pipeworx can do' and 'to learn how to call the meta-tools'. Provides alternatives (ask_pipeworx, entity_profile, etc.) and explains argument usage (omit for spread or pass topic).

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

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

The description adds significant behavioral context beyond annotations: the row is deactivated (not deleted), historical events stay available, and ownership is enforced. This aligns with annotations (idempotent, not destructive) and provides concrete details about the mutation's effect.

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 core purpose and immediately adding ownership and deactivation details. Every sentence adds value without redundancy. It is efficiently structured for quick agent interpretation.

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

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

Given the tool's simplicity (one parameter, no output schema), the description fully covers the operation: what it does, who can use it, and what happens to data. It references the sibling 'recent_alerts', completing the context. 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% with a clear description of the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' The tool description does not add further semantics beyond mentioning 'by id', which is already implied. For a single, well-documented parameter, this is adequate.

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 verb 'Cancel' and resource 'subscription by id', clearly distinguishing from siblings like 'subscribe' and 'list_subscriptions'. It also explains ownership enforcement and deactivation effect, making the purpose unmistakable.

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

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

The description states ownership enforcement, implying you can only cancel your own subscriptions. It also mentions that historical events remain available via 'recent_alerts', which provides context for post-cancellation behavior. However, it does not explicitly state when not to use or list alternative tools, though 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?

The description adds substantial behavioral context beyond the annotations: it details the return value categories (verdict, actual value, citation, reasoning), explains the exact meaning of non-obvious verdicts (could_not_verify vs. unsupported), and warns callers that could_not_verify carries a verification_error and must not be shown as evidence. It also mentions the automatic fall-through routing and tolerance override behavior, which are genuinely useful operational traits not visible in the schema or 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 information-dense; every sentence serves a purpose, and the most important usage guidance is front-loaded in the first sentence. The later verdict definitions and caller warnings are necessary for correct invocation and interpretation, though they add length. It is not as tight as a two-sentence example, but the density justifies the size.

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

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

The tool has only 2 parameters with 100% schema coverage and no output schema, so the description carries the burden of explaining return behavior. It fully covers verdict semantics, error handling, citation format, and the routing logic, making the description self-sufficient for an agent to select, invoke, and interpret results. The 'replaces 4–6 sequential calls' note also completes the efficiency context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value beyond the schema by explaining how tolerance_pct interacts with the claim wording ('Overrides the tolerance implied by the claim wording') and prescribing concrete values for hallucination detection ('set 1–2 for hallucination detection'). It also provides an example of claim format and clarifies the default cap of 5, which helps the agent populate the parameter correctly.

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 concrete natural-language query phrasings and explicitly states 'natural-language claim verification against authoritative sources,' which precisely identifies the tool's verb (verify), resource (claims), and scope. It also distinguishes itself from siblings by contrasting the structured SEC EDGAR/XBRL fast path for company-financial claims versus the grounded pipeline for any other factual claim, making its purpose unmistakable.

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

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

The description explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and provides strong exclusion/alternative context by naming the two distinct pipelines (company-financial vs. other factual claims). It also explains that the tool replaces 4–6 sequential calls, effectively conveying when it is the efficient choice over composing multiple operations, though it doesn't name sibling alternatives directly.

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