Stat Ee

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds that it is a probe that scores, returns per-model data, and notes cost implications (free default, BYO key for Anthropic). It provides helpful details beyond the annotations.

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

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

The description is concise (3 sentences), front-loads the main purpose, then details model options, output format, and use cases. Every sentence earns its place with 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?

The description explains the output format per model and combined view, and covers all parameters adequately. It does not detail what 'signals' or 'raw_response' entail, but the lack of output schema is compensated by the clear structure given. Overall, it is complete enough for the tool's complexity.

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

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

Schema coverage is 100%, so each parameter has a description. The description adds extra context: it explains that _apiKey is needed only if 'anthropic' is in models, and that it is passed straight through. This adds meaning beyond the schema, so given the baseline of 3, a 4 is warranted.

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

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

The description clearly states the verb 'probe', the resource 'one or more LLMs for what they know about a business/brand/product/topic', and the output 'score visibility (0-100) per model'. It is specific and distinguishes the tool's purpose effectively.

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

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

The description provides clear usage context: default model is free, Anthropic requires API key, and use cases like AI-marketing audits and competitive monitoring. However, it does not explicitly contrast with sibling tools like scan_competitor_ai_presence, missing an opportunity for stronger 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 provide safety and idempotency. Description adds context beyond annotations: it routes to specific sources, returns structured answers with stable pipeworx:// citation URIs, and is fast. 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?

Description is front-loaded with 'PREFER OVER WEB SEARCH' and well-structured: targeting, usage criteria, examples, alternatives. Slightly long but every sentence adds value. Could trim examples list slightly but still efficient.

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

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

Given the tool's complexity (4476 sources), the description covers domains, examples, when to use alternatives, and output format (structured answer with citations). No output schema, but description adequately explains return value.

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

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

Schema covers 100% of parameters with descriptions and examples. Description adds little beyond schema: it gives more natural language examples in text, but the schema already has examples. 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 it answers factual questions by routing to 4,476 tools across 1127 sources, and distinguishes from siblings like ask_pipeworx_grounded and deep_research with explicit guidance. The verb 'route' and resource 'question-to-answer pipeline' are specific.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and gives when-to-use criteria (factual questions, 'what is', 'look up', etc.). Also states when not to use: for hallucination-resistant answers use ask_pipeworx_grounded, for broad questions use deep_research. Clear alternatives and 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?

Description adds significant behavioral context beyond annotations: details workflow (routing, filling arguments, extracting only from tool result), return format including refusal reasons, and notes extra LLM call cost. 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 moderately long but well-structured: purpose first, then mechanism, use cases, trade-offs. Each sentence adds value, though some slight redundancy (e.g., fetching data explained twice).

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, description covers purpose, mechanism, return format textually (answer, evidence, refusal reasons), use cases, and cost. Lacks explicit output schema but compensates with clear textual specification.

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 each parameter (all aliases). Description adds context that question accepts natural language and aliases (q, text, etc.), which is helpful beyond schema.

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

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

Description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' with verbs like 'picks', 'fetches', 'extracts'. It distinguishes from sibling 'ask_pipeworx' by emphasizing groundedness and explicit refusal mechanism.

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 an answer will be quoted, cited, or acted on' with examples (financial verdicts, legal claims). Also recommends preferring 'ask_pipeworx for casual lookups', providing clear 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 extensively covers behavioral traits beyond the annotations (readOnlyHint, idempotentHint, etc.). It details low-confidence resolution short-circuiting, closed market handling, wide-spread illiquidity notes, resolution-rule risk, fallback mechanisms for news, and a parent event extractor. All these add transparency and help the agent understand edge cases and safety. 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 long but well-structured with bold headings for sections like CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc. It front-loads the purpose and usage. Every section provides necessary details for a complex tool. While it could be trimmed slightly, the information is valuable and earns its place. The structure aids readability.

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

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

Given the complexity of the tool (multiple classification types, fan-out patterns, response shapes, safety mechanisms), the description is remarkably complete. It explains resolver logic, parent event extraction, news fallback, cancellation rules, and various status codes. Since there is no output schema, the burden is high, and the description meets it 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%, so baseline is 3. The description adds value by providing concrete examples for the 'market' parameter (slug, URL, question text) and clarifying the 'depth' parameter options. The 'include_raw' parameter is well-documented in the schema, but the description reinforces the recommendation. Overall, it enhances understanding beyond the schema.

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

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

The description starts with a clear action verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It explains the input types (slug, URL, question text), the process (resolve, classify, fan out), and the output (evidence packet + comparison). Use cases are explicitly given: 'should I bet on X', etc. This clearly distinguishes it from siblings like polymarket_edges (edge tracking) and polymarket_arbitrage (spread analysis).

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

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

The description states 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context for when to use. However, it does not explicitly say when not to use or name alternatives. Given the many sibling tools, explicit exclusions would be beneficial, but the provided guidelines are still strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it makes a single parallel call, handles off-calendar fiscal years correctly, sorts results by primary metric, and returns citation URIs. This goes beyond annotations but leverages their presence.

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

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

The description is front-loaded with example queries and efficiently conveys key points. Each sentence adds value, though slightly verbose. It could be trimmed slightly without losing meaning.

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

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

Given the schema and annotations, the description is fully complete. It explains the tool's purpose, when to use it, what data is returned (paired data, citation URIs), and how results are sorted. No output schema needed as the description covers return expectations.

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

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

Schema coverage is 100% with descriptions for both parameters. The description significantly enriches parameter semantics: for 'type' it explains what data is pulled (company: 10-K financials; drug: FAERS, FDA approvals, trials). For 'values' it specifies format (tickers/CIKs for company, names for drug) and constraints (2-5 items). This provides meaning far 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 performs side-by-side comparison of 2-5 companies or drugs, with specific verb 'compare' and explicit resource types. It distinguishes itself from sibling tools like entity_profile by focusing on multi-entity comparison and citing 'ALWAYS PREFER over sequential single-pack lookups.'

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It gives example queries and details what each entity type returns, making it clear when to use this tool vs alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant context: returns findings packet with evidence, confidence, source, citation, explicit gaps[], never invents, and expected response time 15-60s. No contradiction.

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

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

The description is relatively long but well-structured, front-loading the account requirement and alternative tool. Every sentence is informative, though could be slightly more concise. Overall efficient.

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

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

Given the tool's complexity, 2 parameters, and no output schema, the description is highly complete. It explains the return format, behavior (gaps[], never invents), constraints (structured sources only, not open-web), and expected timing. No output schema needed.

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

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

Schema description coverage is 100% with descriptions for both parameters. The description adds value by explaining what each depth level means (quick=3, standard=5, thorough=8) and that thorough requires a paid plan. Slight extra meaning beyond schema.

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

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

The description states it performs 'grounded multi-source research across Pipeworx's STRUCTURED data sources' by decomposing questions into facets and routing to tools in parallel. It clearly distinguishes from siblings like ask_pipeworx (single lookup) and mentions best use cases.

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

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

Explicitly says 'for a single lookup use ask_pipeworx' and 'for BREAKING...current-news...prefer ask_pipeworx'. Also notes account requirement and that depth:'thorough' needs a paid plan. Provides clear when-to-use and alternatives.

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

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

Annotations already mark the tool as read-only, idempotent, non-destructive. The description adds valuable behavioral details: 'returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This clarifies the output format and reusability, going well 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 three sentences long, front-loaded with the core purpose. It is information-dense but could be slightly more concise (e.g., merging the domain list with the purpose). Still, every sentence earns its place.

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

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

Given the tool's moderate complexity (6 parameters, mostly aliases) and rich schema coverage, the description fully explains the tool's behavior and output. No output schema exists, but the description compensates by detailing what is returned (top-N tools with schemas).

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 includes multiple alias parameters for 'query'. The description adds context that 'query' is a natural language description and lists examples. This adds meaning beyond the schema, though the aliases are already documented.

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: 'Find tools by describing the data or task.' It lists numerous specific domains (SEC filings, financials, etc.), making it concrete. The tool distinguishes itself from siblings like 'deep_research' and 'search_within' by focusing on tool discovery rather than data retrieval.

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

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

Explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use it. However, it lacks explicit when-not-to-use scenarios, e.g., if the agent already knows the target tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds context: multi-source fan-out, specific return fields, USPTO sunset soft-fail. No contradictions.

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

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

Front-loaded with examples and clear structure. Every sentence adds value, though slightly lengthy. Efficient but could be tightened.

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

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

Given complexity (multiple sources, no output schema), description covers all return fields (filings, fundamentals, patents, news, LEI) and limitations (USPTO sunset, no names). Input schema is fully covered. Agent gets complete picture.

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

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

Schema has 100% description coverage. Description adds meaning: specifies that names are not supported and recommends resolve_entity for names. This extra guidance justifies above baseline 3.

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

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

The description uses specific verb 'profile' and resource 'US public company' with scope 'full cross-source'. It includes example queries and explicitly states preference over chaining single-document lookups, distinguishing it from siblings like resolve_entity.

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

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

Explicitly says when to use (for holistic views) and when-not (if only a name, use resolve_entity first). Clear guidance on preference over alternatives, though could mention other siblings like deep_research.

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 as destructive and idempotent. Description adds use-case context (stale context, sensitive data) but does not disclose error handling or behavior for nonexistent keys. 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?

Three concise sentences, each serving a distinct purpose: definition, usage, and sibling relationship. No redundant information, front-loaded with primary action.

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 single-parameter destructive tool with annotations, the description is nearly complete. It covers purpose, usage, and relations. Missing details about error handling or return value, but output schema is absent so inference is acceptable.

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

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

Schema coverage is 100% with description 'Memory key to delete.' Description adds no new information about the 'key' parameter beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key,' specifying the verb (delete) and resource (memory). It distinguishes itself from siblings 'remember' and 'recall' by explicitly pairing with them, implying different operations.

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

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

Provides explicit when-to-use criteria: 'context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with 'remember and recall,' indicating alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that it 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', providing expected behavior without contradicting annotations. It could mention rate limits or size constraints, but given annotation coverage, the description adds useful context.

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

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

The description is a single paragraph of 4 sentences, front-loading the main purpose, then explaining the process, output, and use cases. Every sentence adds value with no unnecessary words.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully covers purpose, process, output format, and use cases. It is complete for an agent to understand and invoke the tool correctly.

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

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

Both parameters ('url' and 'max_links') are fully described in the schema (100% coverage). The description adds examples ('e.g. 'https://example.com'') and default/max values ('default 25, max 50'), providing meaning beyond the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, explaining the verb and resource. It distinguishes from siblings by specifying the exact output and use cases, and there is no other sibling tool with this specific 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 clear use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), implying when to use it. However, it lacks explicit 'when not to use' or direct comparison to alternatives, though the sibling list does not contain a direct replacement.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying the return fields and that it's for the caller's subscriptions, without contradicting annotations.

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

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

Two sentences with 32 words, each sentence is essential and front-loaded with the purpose and return fields.

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 purpose, return fields, usage guidance, and ties to sibling tools. Annotations provide safety guarantees. No output schema needed. Complete for an agent to decide and invoke.

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

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

Schema coverage is 100% with a clear description for 'include_inactive'. The description reinforces the default of active subscriptions but does not add new semantic 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 uses 'List the caller's active subscriptions' specifying the verb and resource, and distinguishes from siblings like subscribe and unsubscribe by focusing on listing existing subscriptions.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear context for when to use it, though it does not exhaustively list alternatives.

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

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

The description discloses rate limiting (5 per identifier per day), that it's free and doesn't count against tool-call quota. Annotations are minimal (all false), so the description provides essential behavioral context.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds distinct value. No wasted words.

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

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

For a simple feedback tool with no output schema, the description covers purpose, usage, behavioral quirks, and parameter advice comprehensively. Nothing is missing.

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

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

Schema coverage is 100%, but the description adds guidance on message format: be specific, 1-2 sentences typical, 2000 chars max. It also advises against pasting end-user prompts, adding practical semantics.

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

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

The description clearly states the tool's purpose: submitting feedback about Pipeworx tools (bugs, features, data gaps, praise). It explicitly distinguishes itself from sibling tools which are mostly query/research tools.

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

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

The description provides explicit when-to-use scenarios (bug, feature, data_gap, praise) and what not to do (don't paste end-user prompt). It also mentions rate limits, cost, and quota behavior.

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

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

Beyond annotations (read-only, idempotent, non-destructive), description adds data source (CF analytics), no PII, and caching 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?

Concise 5 sentences, no redundancy. Front-loaded with main purpose, use cases, and technical details in logical order.

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

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

Complete for a read-only trending tool with no output schema. Explains return values, caching, data ethics, and parameter semantics fully.

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 nuance: shorter windows for hot trends, longer for steady-state demand, exceeding the enum description.

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

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

Clearly states the tool returns trending data (top tools, packs, call volume) and how it's derived. Distinguishes from siblings like ask_pipeworx or discover_tools by focusing on aggregate usage trends.

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 (discovery, confirmation, alignment) and explains window selection tradeoffs. Lacks explicit 'when not to use' but provides strong contextual 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?

Discloses algorithmic steps (Jaccard similarity threshold, partition filter, fill check with book depth) beyond annotations. No contradictions; annotations indicate read-only and idempotent, which the description supports.

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?

Despite length, every sentence is informative. Well-structured: requirements first, then mode details, then algorithmic specifics, then response and caveats. No superfluous content.

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

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

Covers all necessary aspects: input requirements, algorithmic details, response structure, edge cases, and references to sibling tools. No missing information given the complexity and absence of 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?

Adds significant value beyond schema descriptions by explaining the dependency, usage context, example values, and how each parameter alters behavior. Schema coverage is 100%, and the description enriches it.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes between event and topic modes, and differentiates from sibling tools like 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 requires one of the two parameters (event or topic) and explains when to use each. Provides examples, warns about placeholder slugs, and tells when not to trade based on fill check results.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context, including caching, model families, response segments, diagnostic information, and caveats like 'your edge may already be in the price'. 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 lengthy but well-organized, front-loaded with the core purpose. It uses clear section breaks (e.g., MODEL_DRIVEN, STRUCTURAL_ARBITRAGE) and provides structured details on response format. While dense, every sentence adds value for the complex tool.

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

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

Given the tool's complexity (9 parameters, no output schema, intricate logic), the description is highly complete. It explains the output structure (by_segment, fed_candidates, diagnostics), filtering mechanisms, and caching behavior, ensuring agents can fully understand and use the tool.

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

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

All 9 parameters have schema descriptions, achieving 100% coverage. The description adds further context, explaining the role of knobs (e.g., 'Tradeable-edge filter'), default values, and practical usage tips (e.g., 'bump for very thin partitions'). It does not repeat the schema but enriches it.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb and resource, and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on top markets and a unique opportunity detection mechanism.

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 targets the use case 'what should I bet on today' and explains how agents can discover opportunities without paging through hundreds of markets. It provides guidance on knobs like min_liquidity and max_spread_pp for filtering, but lacks explicit when-not-to-use scenarios relative to 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, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: history bounded by 60-day TTL, snapshot gaps, decay computed on daily closes, not intraday. No contradictions.

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

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

The description is fairly long but front-loaded with key information. Every sentence adds value, though some phrasing could be tightened without losing clarity.

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

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

Despite no output schema, the description comprehensively outlines the response structure (tracked, expired, snapshot_dates). Given the complexity of time-series analysis, it is adequately complete for an agent to understand the tool's outputs.

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?

Both parameters are described in the schema (100% coverage). The description adds extra meaning by explaining the snapshot family concept and defaults, as well as the significance of 'window'.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge duration. It distinguishes from sibling tools like polymarket_edges by focusing on historical tracking.

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

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

The description explains what the tool answers and outlines response structure. While it doesn't explicitly state when not to use it, the context is clear and contrasts with alternatives implicitly.

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, and non-destructive behavior. The description confirms this by stating it 'checks' order-book depth and returns a verdict. It adds details about walking the ladder, returning fill details, and exposing forced directional risk. No contradiction with annotations.

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

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

The description is relatively long but well-structured with section headers (REQUIRES, SINGLE-MARKET, BASKET). It front-loads the purpose and every sentence adds value. Minor redundancy could be trimmed, but for a complex tool it is appropriately concise.

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

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

Despite lacking an output schema, the description enumerates all return fields for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, profit_usd). It explains edge cases like thin_legs and forced_directional_risk. Given the tool's complexity (4 params, two modes), the description is fully complete.

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

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

Schema description coverage is 100%, but the description adds significant context: explains the dual meaning of size_usd (spend vs proceeds) and side default logic in basket mode (auto from partition sum). It also clarifies the return structure, which is not in the schema.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two distinct modes (single-market and basket), lists the return fields, and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly advises using this tool before acting on polymarket_arbitrage signals or polymarket_edges trades above $500. It explains the rationale (theoretical overround on thin books is not capturable; partial basket fills cause unhedged positions). This provides clear when-to-use and why.

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, including two modes, response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment), and detailed explanations of skipped cross types. Annotations only indicate read-only, open-world, idempotent, and non-destructive, while the description adds rich context about edge cases and result interpretation.

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, front-loading the purpose and modes, then detailing response and safety fields. Every sentence adds meaningful information, though it could be slightly more concise without losing clarity.

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

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

Given the tool's complexity and lack of an output schema, the description compensates by explaining response fields and edge cases thoroughly. It covers both modes, safety warnings, temporal alignment, and compatibility conditions, making it adequate for an agent to understand and use the tool correctly.

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

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

The input schema already has 100% parameter coverage with descriptions. The description adds value by explaining the two modes: 'topic' auto-fetches matching events from pre-mapped macros, while explicit parameters override the topic mapping. It also clarifies parameter relationships and provides usage examples.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on cross-venue comparison and explicitly describes two operational modes (topic shortcuts and explicit pairing).

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

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

The description provides context on when to use the tool, explaining the two modes and noting that pre-mapped topics often yield compatibility warnings, indicating limited tradability. However, it does not explicitly contrast with alternatives like 'compare_entities' or 'polymarket_arbitrage', leaving some guidance implicit.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by explicitly warning about the ~100k-cell limit, which is important behavioral context not captured by annotations.

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

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

Two sentences, no filler. First sentence states purpose, second adds a key parameter hint. Efficient and 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?

The description covers the main purpose and a constraint, but does not clarify the return format (though implied in body schema). With no output schema, a brief mention of the response format would improve completeness.

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 that 'body is a PxWeb query object' and mentions filtering to stay under the cell limit, which adds marginal meaning but does not detail the structure beyond the schema.

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

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

The description uses the verb 'Pull data' with resource 'table', which is clear. However, it does not explicitly distinguish from the sibling tool 'table_meta', which likely provides metadata instead of data.

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

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

The description implies usage by stating 'Pull data from a table', but provides no guidance on when to use this vs alternatives like 'table_meta' or 'search_within'. The cell limit warning is a usage hint, but not a full guideline.

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 (readOnlyHint, idempotentHint, destructiveHint) are already provided, and the description adds valuable behavioral context: scoped to user identifier, pairing with remember/forget, and behavior of omitting key. No contradiction with annotations.

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

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

Three sentences, each serving a purpose: function, usage, scoping. Front-loaded with action verb. 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?

For a simple tool with one optional parameter and no output schema, the description fully explains functionality, usage, scope, and relationship to siblings. No gaps.

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

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

Schema coverage is 100% (exactly one parameter with a description). The description adds that omitting key lists all keys, which is already in the schema description. No further parameter semantics beyond 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 it retrieves a value saved via remember or lists all keys if omitted. It distinguishes from siblings remember (save) and forget (delete). The verb 'Retrieve' and resource 'value' are specific, and examples are given.

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?

States when to use (look up stored context) and when to list all keys. Does not explicitly mention when not to use, but the context and siblings imply alternatives (e.g., use remember to save). Good guidance but lacks explicit exclusions.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable context: the mark_read parameter has a side-effect (flags events as read), which annotations do not capture. It also explains returned fields and polling suitability, going beyond the annotation basics.

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

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

Every sentence serves a purpose: purpose, key fields, filtering, side-effect, and alternative access. It is front-loaded with the core action and remains compact 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?

Despite lacking an output schema, the description lists the returned fields. It covers all parameters and their effects, including side-effects. It could mention pagination behavior, but limit parameter suffices. Overall, it provides solid context for a read tool with moderate 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%, but the description enriches parameter meaning by providing examples (e.g., 'sec_8k' for type) and explaining the effect of mark_read on subsequent calls. This adds value beyond the schema's minimal 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 uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), and clearly distinguishes the tool from siblings like list_subscriptions by focusing on event retrieval. It also mentions key output fields, making the purpose unmistakable.

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

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

The description explains when to use it (to get recent alerts, filter by type/since, mark as read) and even offers an alternative access method. However, it does not explicitly state when not to use it or compare to specific siblings, leaving some room for improvement.

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

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

Annotations already indicate safe read-only operation (readOnlyHint, idempotentHint, destructiveHint false). Description adds detailed behavioral context: fan-out across multiple sources, fallback logic (GDELT→GNews), and PatentsView API sunset status.

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 lengthy but well-structured with front-loaded examples. Every sentence adds value; minor redundancy possible but overall efficient.

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

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

Given no output schema and simple parameter set, description covers all inputs, behavior, sources, fallback, and alternative tool. No gaps identified.

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

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

Schema coverage is 100%, but description adds extra meaning: explains 'since' accepts ISO date or relative shorthand with examples, clarifies 'value' accepts ticker or CIK. Provides context beyond 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?

Description clearly states verb ('get change feed'), resource ('company'), and scope ('in last N days/weeks/months'). Distinguishes from sibling entity_profile by contrasting time-windowed vs static profile.

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

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

Explicitly tells when to use (for recent changes over a window) and when not to (use entity_profile for static profile). Provides example query patterns and fallback behavior.

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

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

Annotations indicate readOnlyHint=false (write operation), idempotentHint=true (safe to retry), destructiveHint=false (not destructive). The description adds context: stores as key-value pair scoped by identifier, with persistence details (persistent for authenticated, 24-hour for anonymous). No contradictions with annotations.

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

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

The description is front-loaded with the main purpose in the first sentence. It is slightly verbose but each sentence adds value. Could be marginally more concise, but structure is logical and flows well.

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

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

Given the tool's simplicity (2 required parameters, no output schema, no nested objects), the description is comprehensive. It covers purpose, usage timing, behavioral traits, persistence model, and sibling tools. No gaps remain for an agent to correctly select and invoke.

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 examples for 'key' and 'value'. The description adds value by explaining what kinds of keys are typical ('subject_property', 'target_ticker', 'user_preference') and suggesting content for 'value' ('findings, addresses, preferences, notes'). This goes beyond schema examples, enhancing understanding.

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

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

The description clearly states the tool's purpose ('Save data the agent will need to reuse later') and provides concrete examples of use cases (resolved ticker, target address, user preference, research subject). It distinguishes from siblings 'recall' and 'forget' by explicitly pairing with 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 states when to use ('when you discover something worth carrying forward') and contrasts with related tools ('Pair with recall to retrieve later, forget to delete'). Also clarifies persistence differences between authenticated users and anonymous sessions, providing clear context for selection.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that it cascades through multiple endpoints and replaces manual lookups, and specifies return fields for each type.

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

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

Well-structured with examples and callout 'Use FIRST'. Every sentence adds value, though slightly lengthy.

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

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

Given no output schema, description fully explains return values for both types including citation URIs, making it self-contained and complete.

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

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

Schema coverage is 100%. Description adds examples for each parameter (e.g., ticker 'AAPL', drug 'ozempic') and explains 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 resolves names to official identifiers with examples (ticker, CIK, RxCUI). However, it does not explicitly differentiate from sibling 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 clear context with 'Use FIRST whenever you have a name but need an ID' and lists supported types. Does not include when not to use or alternatives.

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

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

Description complements annotations (readOnlyHint, idempotentHint, etc.) by explaining the tool calls ai_visibility_check per entity and returns a ranked list with score, confidence, and signal density. No contradiction; adds process-level detail beyond annotations.

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

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

Two sentences achieve high information density with zero waste. Front-loaded with the core action ('Compare AI visibility across multiple entities side-by-side') followed by method and use case.

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 of moderate complexity with no output schema, the description adequately covers inputs, process, and output format (ranked list with metrics). Missing details like timeout or pagination are acceptable for this scope.

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 context for key parameters: entities (first is subject), models (which models), context (shared context), and _apiKey (needed for anthropic). This clarifies usage beyond schema descriptions.

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

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

Description clearly states the tool compares AI visibility across multiple entities, using ai_visibility_check, and ranks results. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the competitive audit context.

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

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

The description gives an explicit use case ('competitive AI-marketing audits') and an example question, but does not explicitly mention when not to use or list alternative tools. However, the context is clear enough for an agent to infer appropriate usage.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description details partial failure behavior, timing issues (bundlephobia first measurement takes 5-30s), and the 'sources_failed' field. It also lists the exact return fields, providing full behavioral context.

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

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

The description is dense and informative but slightly verbose at three long sentences. It front-loads the main purpose and packs details efficiently, though a tighter structure could improve readability.

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

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

Given the absence of an output schema, the description thoroughly covers return values (summary block, advisories, links, alternatives), edge cases (partial failures, timeouts), and ecosystem limitations. It is 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 coverage is 100%, so baseline is 3. The description adds value by clarifying that 'version' defaults to latest, accepting scoped packages, and tying parameters to the composite check purpose. It goes slightly beyond schema definitions.

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

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

The description clearly states that the tool performs a composite check for npm packages, covering license, advisories, size, and tree-shaking support. It distinguishes itself from sibling tools like 'validate_claim' by being specific to npm package evaluation.

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 usage scenarios ('is X safe / popular / small') and provides alternatives for non-npm ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), offering 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds significant value beyond annotations: it reveals the embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), character limit (200K chars with truncation and flag), and the fact that passages include offsets for verification.

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 purpose. While it contains several sentences, each one adds unique value: purpose, usage guidance, output details, sibling pairing, and technical specifics. It could be slightly shorter but is 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?

No output schema exists, so the description compensates by explaining return values (passages with offsets and similarity scores). It covers input limits, output behavior, and integration patterns, making it fairly complete for a search tool despite the lack of an explicit 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%, so the schema already describes all three parameters. The description adds value by providing concrete query examples (e.g., 'supply-chain risk', 'fiscal year 2024 revenue') and clarifying the default limit (5) beyond the schema's range.

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 semantic search inside a fetched record, specifying inputs (text and query) and outputs (top-N passages with character offsets and similarity scores). It distinguishes itself from siblings by explicitly mentioning pairing with ask_pipeworx_grounded and contrasting with fetching entire documents.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' Also provides guidance on pairing with ask_pipeworx_grounded for grounded answers, giving clear alternatives and 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 read-only, open-world, idempotent, and non-destructive. The description adds value by explaining item types ('l' vs 't') and the ID pattern, which helps the agent understand the tree structure.

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

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

Two concise sentences with immediate clarity. Every word earns its place, and the structure is front-loaded with the 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?

For a simple tree-navigation tool with one optional parameter and no output schema, the description is complete. It explains item types and the special table ID pattern, leaving no ambiguity.

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 description adds no new parameter meaning. The schema's description of 'path' is sufficient; the tool description does not elaborate further.

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

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

The description uses a specific verb 'Navigate' and resource 'subject tree', immediately clarifying the tool's function. It distinguishes from siblings by focusing on tree navigation and item types, not querying or editing.

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 for exploring the subject hierarchy but provides no explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned despite many sibling tools.

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

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

Annotations indicate mutable (readOnlyHint=false) and idempotent (idempotentHint=true). The description adds critical behavioral details: returns subscription id, requires OAuth, 10/day SMS cap, webhook signing secret returned once. 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 tightly packed with necessary information. Each sentence adds value: purpose, prerequisites, type details, delivery channels. It is well-structured and front-loaded with the core action.

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 states it returns the new subscription id. It covers all relevant aspects: types, params, delivery, limitations, and authentication. The agent has sufficient information to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema: for each type it provides concrete examples and required/optional fields. It clarifies the params structure and delivery options, making parameter usage clear.

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 'Create a proactive monitoring subscription to a live-data event stream,' which is a specific verb+resource. It clearly distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description specifies prerequisites (Pipeworx OAuth account), supported types with detailed params, and delivery channels. It indirectly indicates when not to use (anonymous/BYO cannot persist). However, it does not directly compare to alternatives like list_subscriptions or unsubscribe, just to other tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations: it explains the output format (category-bucketed questions with tool+argument shapes) and dynamic behavior (full spread vs topic focus). 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 common queries. It packs a lot of information (purpose, usage, output, examples, alternatives) without redundancy. Every sentence contributes value, making it efficient despite 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?

Given the low complexity (1 optional parameter, no output schema, no nested objects), the description is remarkably complete. It covers what the tool does, how to use it, what it returns, when to use it, and how it relates to other tools. No gaps are apparent.

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

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

The input schema covers the topic parameter with a description listing possible values. The description reinforces and expands by providing examples ('finance', 'pharma', 'betting') and explaining the effect of omitting the parameter. While schema coverage is 100%, the description adds useful usage 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 explicitly states the tool is an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings like discover_tools and ask_pipeworx by stating 'Use this FIRST when you do not yet know what Pipeworx can do for you'.

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

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

The description provides clear usage instructions: call with no arguments for the full spread or pass a topic to focus. It specifies when to use it ('FIRST when you do not yet know') and mentions learning how to call meta-tools like ask_pipeworx, entity_profile, compare_entities, giving context for alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds that it provides specific metadata (dimensions, valid values), which goes beyond the annotation hints.

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

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

Two concise sentences: first states what the tool returns, second gives usage guidance. No unnecessary words.

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

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

Given the tool's simplicity (single parameter, no output schema), the description sufficiently explains purpose and usage. It could mention the return format, but the high-level description is adequate for a metadata lookup tool.

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

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

Schema coverage is 100% with a clear description and example for the single parameter 'path'. The description does not add additional semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns table definition metadata (dimensions, valid values) and specifies its intended use for building filtered queries. It distinguishes from the sibling tool 'query_table'.

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

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

The description gives explicit guidance on when to use this tool: 'Use these to build a filtered query_table call.' It implies the alternative is to use query_table directly, though it doesn't explicitly list when not to use.

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

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

Annotations indicate a non-destructive write operation; description adds crucial context: 'row is deactivated (not deleted)' ensuring historical events remain available. No contradiction with annotations.

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

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

Two sentences, front-loaded with purpose, no redundant information. Every sentence earns its place.

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

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

Given low complexity (1 parameter), annotations, and no output schema, the description fully covers usage, behavior, and constraints without 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?

Only one parameter 'id' with 100% schema coverage. Description repeats schema's purpose but adds origin context ('returned by subscribe'), marginally adding value beyond schema.

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

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

Description uses specific verb 'Cancel' and resource 'subscription by id', clearly distinguishing from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for use. Lacks explicit when-not-to or alternative tools, but the condition 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 indicate readOnly, idempotent, openWorld, and non-destructive. The description adds significant value by detailing return values (verdict types, extracted structure, citation, percent delta) and underlying data sources (SEC EDGAR + XBRL), exceeding the information provided by annotations.

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

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

The description is well-structured with examples, usage, domain, and return details. While it packs valuable information, it is slightly verbose but every sentence adds value and is front-loaded with 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?

Given a single parameter, rich annotations, and no output schema, the description covers all necessary aspects: purpose, usage, behavior, return format, and data source. It is complete for effective tool selection and invocation.

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

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

The input schema fully describes the 'claim' parameter with examples. The description further enriches by specifying the domain (company-financial) and providing usage examples, adding meaning beyond the schema's description.

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

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

The description uses specific verbs ('verify', 'fact check') and identifies the resource ('natural-language claim verification against authoritative sources'). It clearly distinguishes from siblings by noting it replaces 4-6 sequential calls, making its unique purpose evident.

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 'Use whenever the agent needs to check whether something a user said is factually correct.' While it provides clear context and domain scope (company-financial claims), it lacks explicit when-not-to-use instructions or direct alternatives among siblings.

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