Merriam Webster

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds that it probes Workers AI free and optionally Anthropic with BYO key, returns per-model {score, confidence, signals, raw_response} plus combined view—useful context beyond annotations.

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

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

Two sentences with no waste: first sentence covers core action and output; second provides usage context and parameter clarification. Front-loaded and efficient.

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

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

Given the tool's complexity (multiple models, optional auth, structured output), description covers purpose, parameters, and typical use cases. Lacks error handling details but is sufficient for a non-destructive read tool.

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

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

Schema has 100% description coverage (baseline 3). Description adds value: explains default model, that '_apiKey' is required only for Anthropic, and 'context' helps disambiguate entities.

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 precise verb+resource ('probe LLMs for entity knowledge and score visibility'), and distinguishes from siblings (e.g., ask_pipeworx) by focusing on AI visibility across models.

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

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

Explicit usage contexts: AI-marketing audits, pre-launch brand checks, competitive monitoring. However, it does not explicitly state when not to use it or list alternatives among siblings.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond that: it routes queries, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and makes one fast call. This is useful, though it doesn't mention failure modes or rate limits, which are not required given the strong annotation coverage.

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 each sentence carries value: it explains the routing mechanism, gives usage examples, and provides contrasts with alternatives. It is front-loaded with the key directive 'PREFER OVER WEB SEARCH'. Some repetition could be trimmed, but it remains structured and purposeful, earning a 4 rather than a 5.

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 high-complexity meta-tool, the description is remarkably complete. With no output schema, it explains that the tool returns structured answers with stable citation URIs. It covers the open-world nature, examples, tier compatibility, and how it relates to sibling tools. The context is fully sufficient for an agent to invoke this tool effectively.

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

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

The input schema has 100% coverage with clear descriptions for each parameter, all being aliases for 'question' and documented accordingly. The description reinforces that the tool accepts natural language questions and lists aliases, but adds no additional parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a router that connects questions to the appropriate tool among thousands, returning structured answers with citations. It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx_grounded and deep_research, and over web search. The specific verb 'ask' plus resource 'Pipeworx' plus the routing behavior makes 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 gives explicit guidance on when to use: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and when to step up to alternatives like ask_pipeworx_grounded or deep_research. It also states the types of queries and provides examples, giving the agent clear decision criteria.

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, and idempotent hints. The description adds valuable context beyond these: it is a live experimental edge with candidate routing improvements enabled only when under test, no candidate is currently active (last retired 2026-07-26), and it currently matches ask_pipeworx exactly. It also clarifies it is a full working router, not a fallback wrapper, and that results are compared against the stable router. This goes well beyond the annotations.

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

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

The description is a single paragraph of four sentences, front-loaded with the key fact ('Beta version of ask_pipeworx') and then efficiently explains the experimental nature, current state, and usage. Every sentence adds useful information, with no redundant filler. The structure is clear and to the point.

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 an experimental router with no output schema, the description is remarkably complete: it defines the tool as a universal router, states the exact relationship to ask_pipeworx (same tools, arguments, response shape), explains the live testing mechanism and that no candidate is active now, and provides usage guidance. The cross-reference to ask_pipeworx's response shape compensates for the missing output schema. This is sufficient for an agent to decide whether and how to use it.

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

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

Schema description coverage is 100%, with all parameters documented including aliases (q, text, input, query, prompt, question). The description only says 'same arguments' without adding new parameter semantics or examples beyond what the schema provides. Since the schema fully covers parameter meanings, 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 identifies this as a beta variant of ask_pipeworx, a universal router that routes questions to tools. It explicitly states it is identical to ask_pipeworx in tools, arguments, and response shape, and distinguishes itself by being the experimental edge with live candidate routing improvements. The verb+resource is specific and differentiates from the stable sibling.

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 instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide what merges. This provides a clear when-to-use context and names the alternative (ask_pipeworx), though it doesn't explicitly state when not to use it, the 'when you want the newest routing' is a clear sufficient condition.

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

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

Adds substantial behavioral context beyond annotations: explains that it uses ONLY what the tool result contains, details the exact success return shape with evidence as a verbatim quote, enumerates possible refusal_reason strings, and notes the extra LLM call cost. This goes far beyond the readOnlyHint to set accurate expectations for refusal behavior and output guarantees.

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

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

The description is dense but every sentence earns its place: it defines the tool's purpose, explains the mechanism, specifies the return/refusal contract, gives concrete usage cases, and includes a cost trade-off. It is front-loaded with the most critical information and structured logically.

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 there is no output schema, the description fully compensates by specifying both the success return fields and the refusal reasons. It also addresses cost and when to use the cheaper sibling, making the tool's behavior and decision context complete for an agent.

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

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

Schema description coverage is 100%, with all parameters documented as aliases for 'question.' The description does not add extra parameter context beyond what the schema provides, which is acceptable since the schema fully covers the single logical parameter. Baseline 3 applies because the description repeats no parameter details but also adds no additional semantic nuance.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific verb ('extracts') and resource (tool results from 5,462 tools across 1,419 sources). It distinguishes itself from the sibling ask_pipeworx by noting same routing but grounded extraction, making its unique 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?

Explicitly states when to use: whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements). Also gives an explicit alternative preference: 'prefer ask_pipeworx for casual lookups.' This provides clear when-to and when-not-to 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 (readOnlyHint, etc.) are not contradicted. The description goes far beyond annotations, detailing resolution process, response structure, resolver contract, safety mechanisms (low-confidence short-circuit, closed markets), tradeability warnings, and news fallback fields. Very transparent.

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

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

The description is lengthy but well-organized with sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and examples. Every sentence adds value for a complex tool. Slightly verbose but justified by content richness.

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

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

Given the tool's complexity (multiple classifiers, fan-out, response fields, resolver behavior, safety checks), the description is very complete. It covers all critical aspects without an output schema. Thorough and actionable.

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

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

Schema coverage is 100% (all parameters described). The description adds significant value: examples for market parameter, depth enum explanation, and include_raw behavior. It enriches 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 title and description clearly state the tool researches a Polymarket bet by pulling Pipeworx data. It specifies multiple input types (slug, URL, question text) and distinguishes itself from sibling tools by focusing on bet research with data fan-out.

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

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

Explicit usage examples are given: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. While it doesn't explicitly state when not to use, the guidance is clear and contextual. No alternative tool is mentioned, but siblings exist.

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, idempotent behavior. The description adds vital details: for companies, pulls latest 10-K data from EDGAR/XBRL with correct off-calendar fiscal year handling; for drugs, pulls FAERS, FDA approvals, trial counts. No contradictions.

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

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

Description is comprehensive but efficient. Each sentence provides useful information, front-loads example queries, and avoids redundancy. Slightly longer than minimal but justified by explanation of data sources.

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

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

Given the lack of output schema, the description adequately covers return structure (paired data + citation URIs) and behavior for both entity types. Some details about output format might be helpful but are not essential.

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

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

Schema covers both parameters with descriptions. The description enriches by giving concrete examples (tickers/CIKs for company, names for drug) and specifying min/max items, 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?

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, pulling specific financial or regulatory data. It uses concrete trigger phrases and distinguishes from siblings like entity_profile.

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

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

The description explicitly advises to prefer this tool over sequential single-entity lookups, provides example queries, and explains when to use it (e.g., 'compare', 'vs', 'rank'). It also mentions replacing 8-15 sequential lookups.

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 readOnly/openWorld/idempotent hints, and the description adds substantial behavior: gaps[] when unanswered, contradictions[], hop and citation_uri semantics, only-fetchable citations, excerpts, and timing expectations. No contradiction with annotations.

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

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

The description is long but dense, with each clause adding useful facts. It is front-loaded with account requirements and purpose. Slight redundancy (ONE call and IN PARALLEL) but not excessive.

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

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

Given no output schema, the description thoroughly explains output shape, gaps and contradictions, edge cases (breaking news leads to empty results), latency, citation resolvability, and alternatives. It is exceptionally 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 already describes both parameters (100% coverage), but the description deepens semantics by explaining depth tiers (quick/standard/thorough), hop recovery behavior, paid plan requirement for thorough, and the natural-language scope for the question parameter.

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

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

The description precisely states it performs 'grounded multi-source research' across 1419 structured data sources and returns a findings packet. It clearly distinguishes itself from open-web search and from sibling tool ask_pipeworx by specifying the research/parallel-tool approach vs. a single lookup.

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

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

Explicit guidance is given: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx'. It also advises on breaking/current news to use ask_pipeworx instead, plus account requirements and a fallback if not signed in.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed.' There is no contradiction with annotations.

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

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

The description is a single paragraph of moderate length. It is front-loaded with the core purpose ('Find tools by describing the data or task'), then provides use case examples, and ends with explicit guidance. It is concise and each sentence adds value.

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

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

Given that there is no output schema, the description adequately explains what the tool returns: top-N tools with names, descriptions, and full schemas. It covers purpose, usage guidance, and return format. No gaps are apparent.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaning by explaining that query accepts aliases (task, q, description, search) and that limit controls the maximum number of results. This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It enumerates specific domains (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from sibling tools (which are domain-specific) by being a general discovery tool.

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

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

The description gives explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set.' It also notes that results are ready to call directly, eliminating the need for a second schema lookup. This clarifies when to use versus alternative tools.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive. The description adds value by detailing the fan-out across multiple sources, soft-fail behavior for patents (USPTO sunset May 2025), and specific return fields. No contradictions.

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

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

The description is somewhat long but packs useful information. It front-loads example queries and uses bullet-like structure for outputs. Every sentence adds value, but could be slightly trimmed 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 no output schema, the description comprehensively explains the return structure (cik, filings with URIs, fundamentals, patents, news, LEI) and covers edge cases like patent sunset. Parameter info is complete with schema coverage at 100%.

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 reinforces meaning: type is only 'company', value is ticker or zero-padded CIK, and explains why names are not supported, adding context beyond the schema.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company, with example queries and a list of data sources and outputs. It distinguishes itself from siblings like resolve_entity and ask_pipeworx by explicitly stating it should be preferred over chaining 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 explicitly advises to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views. It also specifies that names are not supported and directs to use resolve_entity first if only a name is available.

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

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

Description adds context about why to delete beyond the destructiveHint annotation, explaining common use cases. However, it does not mention behavior on missing keys or irreversibility, which annotations already indicate as destructive.

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

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

Two concise sentences: first states purpose, second provides usage context. No wasted words, 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?

For a simple tool with one parameter and no output schema, the description covers purpose, usage, and pairing. Lacks explicit mention of error handling or permanence, but annotations compensate for destructiveness.

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 description 'Memory key to delete.' Description does not add extra meaning beyond the schema, meeting baseline for high coverage.

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

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

Description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes itself from siblings by mentioning pairing with remember and recall.

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

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

Explicitly tells when to use (stale context, done task, clear sensitive data) and implicitly suggests to use sibling tools for other operations via 'Pair with remember and recall.' Lacks explicit 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 readOnlyHint, idempotentHint, and destructiveHint as false. The description adds process details ('fetches the page, extracts title/description/links, emits markdown') that reinforce the read-only, idempotent behavior. No contradictions.

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

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

Three sentences: first states purpose, second explains process, third lists use cases. No fluff; every sentence adds value.

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

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

Given the simple tool (2 params, no output schema, strong annotations), the description covers purpose, process, output format, and use cases. Slightly lacking details on error scenarios or input validation.

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%: both 'url' and 'max_links' are described with defaults and limits. The description repeats this information without adding new meaning, 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 uses a specific verb ('Generate') and clearly identifies the resource ('production-ready llms.txt file'). It distinguishes itself from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on generating the standard file format.

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

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

Explicitly lists three use cases (client indexing, own project, competitor audit) but does not state when to avoid this tool or mention alternatives. The context is clear but lacks 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 declare readOnlyHint, idempotentHint, destructiveHint. Description adds return field details and optional parameter behavior, with no contradictions.

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

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

Two sentences: first covers purpose and return fields, second gives usage guidance. No waste, 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?

For a simple list tool with one optional param and full annotation safety, the description provides all necessary context.

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

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

Schema coverage is 100%, and description does not add meaningful detail beyond the schema for the one parameter. Baseline 3 applies.

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

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

Clearly states 'List the caller's active subscriptions' and enumerates return fields, distinguishing from siblings like subscribe/unsubscribe.

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

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

Explicitly states when to use: 'to review what you're monitoring before adding more or to find an id to cancel.'

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 side effects (readOnlyHint=false, etc.), and the description adds valuable behavioral context: rate-limited to 5 per identifier per day, free and not counting against tool-call quota, and that the team reads digests daily. It also warns against pasting end-user prompts and restricts feedback to Pipeworx tools, preventing misuse. No contradiction with annotations.

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

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

The description is a single paragraph but well-organized: purpose first, then usage triggers, exclusions, and content guidelines. It's moderately long but every sentence carries weight; no redundancy. A bulleted structure might improve scannability, but it remains 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?

For a tool with 3 parameters and a nested context object, the description covers all critical aspects: when to submit, how to phrase the message, rate limits, quota, and exclusions. The only minor omission is the expected response/confirmation, but that is low-importance for a feedback submission tool.

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

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

The schema covers 100% of parameters, but the description goes further by clarifying enum semantics ('bug = something broke or returned wrong data', etc.) and providing message guidelines ('Be specific... 1-2 sentences typical, 2000 chars max'). This adds practical meaning beyond the schema, though a bit more direct mapping to context fields could push it higher.

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

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

The description clearly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific feedback types (bug, feature, data_gap, praise) and distinguishes itself from sibling research/query tools by centering on reporting issues with Pipeworx tools themselves.

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 triggers: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion for tools from other MCP servers, directing the agent to file elsewhere, fully covering 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description reveals that data is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This adds significant 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 compact, front-loaded with the core purpose, and every sentence serves a purpose. No wasted words, and the structure efficiently conveys use cases and caveats.

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

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

Given the simplicity of the tool (one optional parameter, no output schema), the description is complete: it explains the return structure, caching policy, and data source. No gaps remain for an AI agent to guess.

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

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

The schema already covers the single parameter (window) with full enum descriptions. The description adds value by explaining the trade-off between shorter and longer windows, providing semantic guidance beyond the schema.

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

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

The description clearly states it returns top tools, top packs, and total call volume over recent windows. It uses specific verbs ('returns') and resource ('trending signals'), and distinguishes itself from sibling tools like 'discover_tools' by focusing on what other AI agents are calling.

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 lists three explicit use cases (discovering hot sources, confirming canonical choice, seeing alignment) and explains how window choice affects results. It does not explicitly state when not to use it, but the context is clear enough for an AI agent to decide.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint=true, but the description adds critical behavioral details: monotonicity checks, partition-sum deviation thresholds (3pp), similarity thresholds (0.30 Jaccard), placeholder filters, fill check with book depth, and warnings not to trade when realizable_edge_pp <= 0. This goes well 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 dense and informative, but could be more concise. It packs many details into a single paragraph without subheadings, which might overwhelm some agents. However, every sentence adds value, and core information is front-loaded. Loses one point for lack of structural 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 no output schema, the description compensates by detailing response fields (opportunities[], partition_check, fill_check) and conditions for safe trading. It covers input modes, behavioral rules, threshold limits, and even what not to do. For a complex tool with two optional parameters, this is remarkably 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?

Both parameters (event, topic) have schema descriptions, but the tool description adds substantial meaning: it explains the mode each parameter activates, provides examples of valid values (URLs, slugs), and clarifies the different behaviors (single-event vs cross-event scanning, partition_check details). This significantly enhances the agent's 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 verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This directly states the tool's purpose and distinguishes it from sibling tools like polymarket_edges, which focus on different aspects. The multiple modes are explained, covering all usage scenarios.

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 guides when to use each mode: no args for trending scan, event for single-event, topic for cross-event. It recommends event mode and explains why cross-event catches patterns single-event misses. It also directs users with custom sizing to a sibling tool (polymarket_fill_risk), providing clear 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 extensively discloses behavioral traits: caching (1h KV level keyed on knobs), response structure (by_segment with diagnostics), what happens when segments are empty, slippage handling, and edge computation. This goes well beyond the annotations (readOnlyHint, idempotentHint) without contradiction.

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

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

The description is comprehensive but overly verbose, with detailed model family explanations. It is front-loaded with purpose but could be more concise. Well-structured with clear sections, but length reduces readability.

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

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

Given 9 parameters with full schema coverage and no output schema, the description thoroughly explains the response structure (by_segment with diagnostics, Fed candidates, funnel counters) and caching behavior, making it complete for complex tool usage.

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

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

Schema coverage is 100% with parameter descriptions. The tool description adds value beyond the schema by explaining how parameters interact (e.g., min_kelly doesn't filter partitions, min_partition_leg_kelly applies to per-leg Kelly, tradeable-edge knobs).

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, explicitly targeting 'what should I bet on today' use case. It distinguishes from sibling tools by its focus on Pipeworx data and specific model segments.

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

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

The description provides clear context for when to use this tool (discovering betting opportunities) and describes three model segments with their use cases. However, it does not explicitly mention when not to use it or compare directly to sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: response structure (tracked[], expired[], snapshot_dates[]), trend classification, decay calculation, and data gaps. No contradiction with annotations.

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

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

The description is well-structured but verbose, containing over 150 words. While every sentence adds value, it could be more concise without losing information. Front-loading the purpose is good.

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

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

Given no output schema and moderate complexity (time-series, multiple arrays), the description is highly complete. It details every field in the response, explains data gaps and limitations, and provides sufficient information for an agent to use the tool effectively.

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 both parameters fully described. The description reiterates defaults and clamps, but adds no significant new meaning. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. This distinguishes it from sibling tools like polymarket_edges (which likely lists current edges) by focusing on time-series behavior.

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 the use case (comparing fresh vs. old edges) and includes limitations (60-day TTL, daily snapshots). It does not explicitly list alternative tools or when not to use it, but the context is clear enough for an agent.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false, so the description is not required to repeat these. However, the description adds significant behavioral context: it 'walks the ladder', computes fill details, and warns about forced directional risk and partial fills. This goes beyond annotations without contradicting them.

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

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

The description is relatively long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). It front-loads the core purpose and immediately states requirements. Every sentence provides useful information, though some minor repetition could be trimmed without loss.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description thoroughly covers inputs, return values (listing each field like top_of_book, vwap_fill_price, slippage_pp, etc.), and important risks. It also explains the problem it solves (theoretical vs. realizable edge) and warns about the dominant loss mode in arb-bots. This is a near-complete 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 description coverage is 100%, and the description adds substantial meaning beyond the schema. It explains how `size_usd` is interpreted differently in each mode (max spend vs. target proceeds vs. settlement notional), the default side logic for basket mode, and the meaning of each return field. This greatly aids correct parameter usage.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and explicitly distinguishes between single-market and basket modes. It provides specific actions (walks the ladder, returns top_of_book, vwap_fill_price, etc.), making it easy to understand what the tool does.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns about when not to rely on theoretical values due to thin books, and mentions the risk of partial fills converting arb into unhedged positions.

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

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

Annotations already indicate read-only, idempotent, open-world behavior. The description adds substantial context: explains the response structure, safety fields, skipped comparisons, and temporal alignment checks, going well beyond annotations without contradiction.

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

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

The description is dense and front-loaded with the purpose, but some sentences are lengthy. However, every sentence contributes essential information, making it efficient for the tool's complexity.

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

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

Despite lacking an output schema, the description thoroughly explains the response fields, safety warnings, and edge cases. It covers modes, parameters, output structure, and caveats, making it self-sufficient for agent 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?

Schema has 100% coverage of parameter descriptions. The description adds value by explaining the two modes, providing concrete examples for topic values, and clarifying how explicit parameters override the topic-mapped side.

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

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

The description clearly defines the tool as computing the cross-venue spread between Kalshi and Polymarket for the same question, specifying two modes (topic shortcuts and explicit tickers). It distinguishes from siblings like polymarket_arbitrage by emphasizing the inter-venue comparison.

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

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

The description details two usage modes and provides explicit safety fields (compatibility_warning, temporal_alignment) that indicate when spreads are not meaningful. It advises that pre-mapped topics are not always tradeable, but does not directly contrast with 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds scoping and pairing context, which is useful beyond annotations. No contradictions.

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

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

The description is a single paragraph, front-loads the main action, and is fairly concise. Could be slightly shorter but no wasted words.

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

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

No output schema, but the description explains what to expect (value or list of keys). The tool is simple, and the description provides adequate context for an agent.

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

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

Schema coverage is 100% and already describes the 'key' parameter well. The description reinforces the omitting behavior but adds little new. 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 retrieves a value by key or lists all keys, with specific verbs (retrieve/list) and resource (saved memories). It distinguishes from siblings like 'remember' and 'forget'.

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

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

Explicitly says to use for retrieving stored context and mentions pairing with remember/forget. Scoping info is provided. While it doesn't explicitly state when not to use, the context is clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds valuable behavioral context about the mark_read parameter, explaining that flagging events read will cause subsequent calls to show only newer ones. This goes beyond what annotations provide.

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

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

Description is three sentences, front-loaded with the main purpose. Each sentence adds distinct information (returns fields, filtering, mark_read behavior, polling suitability). No wasted words.

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

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

Despite no output schema, description adequately explains return shape (fields: source, citation_uri, payload). It covers parameters, usage guidance, and alternative access method. For a tool with 5 optional parameters, this is comprehensive.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning by explaining the semantics of 'type' (example 'sec_8k'), 'since' (ISO timestamp), and 'mark_read' (flags events as read). It does not add much for 'limit' or 'unread_only' beyond schema descriptions, but the added context is useful.

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

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

Description clearly states the tool pulls fired events from the subscription feed, specifies the returned fields (source, citation_uri, payload), and mentions filtering options. It distinguishes itself from sibling tools by focusing specifically on recent alerts from 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?

Description indicates polling works fine and mentions an alternative endpoint (GET registry.pipeworx.io/alerts.json) for scripts/dashboards. It implies when to use this tool, but does not explicitly state when not to use or compare with siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description goes beyond by detailing the multi-source fan-out (SEC EDGAR, GDELT→GNews, USPTO), parallel execution, soft-failure for USPTO, and the structured return format. 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 concisely structured: it opens with user-facing query examples, then explains the behavior, parameters, and alternatives. Every sentence adds necessary information without redundancy. Appropriate length for the tool's complexity.

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

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

Given the tool's moderate complexity and lack of output schema, the description covers return fields (changes[], total_changes, pipeworx:// URIs), the parallel call nature, and source-specific details. Minor gaps: no mention of result limits or pagination, but overall sufficiently complete for agent 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the `since` parameter formats with examples and a recommended default, clarifying that `type` only supports 'company', and detailing acceptable `value` formats (ticker or zero-padded CIK). This practical guidance raises the score above baseline.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, with specific example queries. It distinguishes itself from the sibling 'entity_profile' tool by contrasting temporal vs. static profiles. The verb-resource relation is explicit and unambiguous.

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

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

The description provides explicit when-to-use guidance, including when to prefer alternatives ('Use entity_profile instead when you want the static profile'). It also gives practical advice for parameters (e.g., 'Use "30d" or "1m" for typical monitoring') and explains the fallback behavior between GDELT and GNews.

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

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

Adds beyond annotations: key-value scoped by identifier, authenticated users get persistent memory, anonymous sessions 24h. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true).

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

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

Four sentences, front-loaded with purpose. Every sentence adds value: what it does, when to use, how it works, pairing with siblings. No fluff.

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

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

Given 2 params, no output schema, 100% coverage, the description covers usage, persistence scope, and sibling tools. Completely adequate for the tool's simplicity.

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 100% with descriptions. Description adds context that it's a key-value pair and gives examples for key formatting (e.g., 'subject_property', 'target_ticker'). Adds 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?

Clearly states the tool saves data for reuse across conversations/sessions. Provides specific examples (resolved ticker, target address, user preference) and distinguishes from siblings recall and forget by explicitly naming them.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and 'so you don't have to look it up again.' Mentions pairing with recall and forget. Does not state when not to use, but context is clear enough.

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

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

Even with annotations (readOnlyHint, idempotentHint) already declaring the safety profile, the description adds substantial behavioral context: it details the exact data returned (ticker, CIK, company name; RxCUI, ingredient, brand), cites citation URIs, notes auto-disambiguation, and mentions internal cascading through multiple lookup endpoints. This goes well beyond annotation defaults.

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

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

The description is long but information-dense, with examples front-loaded and a clear logical structure: purpose, usage guidance, then per-type details. Every sentence contributes meaningful information, and the complexity (two entity types with different return schemas) justifies the 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 there is no output schema, the description effectively explains return values (e.g., 'returns ticker + 10-digit CIK + company_name' and citation URIs). It also covers input variations, disambiguation, and internal behavior, making the tool usable without further documentation.

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

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

Schema coverage is 100%, and both parameters have descriptive text in the schema. The description adds only minor extra detail ('auto-disambiguated', 'accepts ticker, CIK, or company name') but largely repeats schema content. Baseline of 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical identifier, with concrete examples ('What's the ticker for…', 'find the CIK for…'). It distinguishes itself from siblings by noting the identifiers are required by other tools, making its purpose and scope unambiguous.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also specifies supported entity types and input formats. However, it does not name alternatives or explicitly state when not to use the tool, so it falls short of the highest bar.

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 internal behavior (uses ai_visibility_check per entity, ranks results) and return format (ranked list with score, confidence, signal density). This adds significant detail beyond annotations, which already mark it as read-only, idempotent, and non-destructive. 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 three sentences with no waste. First sentence states core purpose, second explains process, third gives use case and return format. Information density is high 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?

Given the tool's complexity (4 parameters, no output schema, but rich annotations), the description covers purpose, usage, parameter nuances, and behavioral details. It lacks examples or error handling notes but is sufficient for an agent to select and use it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning: 'First entry treated as subject for narrative; rest are competitors' and clarifies model options ('workers-ai' default, 'anthropic' requires _apiKey). This improves selection and invocation 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 compares AI visibility side-by-side, using verbs like 'compare', 'probes', 'ranks', 'surfaces'. It specifies the resource (AI visibility of entities) and distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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

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

The description provides a concrete use case: 'competitive AI-marketing audits' and a sample question. It implicitly suggests when to use this over siblings (side-by-side vs single probe). However, it doesn't explicitly mention when not to use it or list alternative tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive hints. The description adds valuable context: it calls external APIs, bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully, and it lists exactly what is returned. 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 dense but every sentence carries meaning. It front-loads the main idea, then usage, then returns, then limitations. Slightly long but justified by the tool's complexity.

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

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

Given the tool's complexity (composite call, multiple sources), schema coverage 100%, and no output schema, the description fully covers purpose, usage, behavior, parameters, and return values. It explains partial failures and ecosystem limitations.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds extra value: clarifies scoped packages (e.g. '@types/node') are accepted, and version defaults to latest. This goes 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 is a composite 'should I add this npm package' check, specifying it fans out across deps.dev and bundlephobia. It distinguishes itself from siblings by focusing on npm packages and providing a bundled check.

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

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

The description provides explicit usage guidance: 'Use whenever an agent asks...' with examples, and notes alternatives for non-npm ecosystems (PyPI/Maven/Cargo/Go) via deps.dev directly. It also warns about potential timing issues and partial failures.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds significant details: embedding model (BGE-base-en), similarity metric (cosine), chunking (500-char overlapping windows), character cap (200K chars with truncation flag). No contradiction with annotations.

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

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

A single well-structured paragraph, front-loaded with the core action and purpose. Every sentence adds value: explains when to use, the output format, pairing hint, and technical details. No filler or repetition.

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

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

Despite no output schema, the description explains the return value (top-N passages with character offsets and similarity scores). It also includes the embedding model and chunking details, plus the pairing with ask_pipeworx_grounded for grounding. Complete for a semantic search 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% (all three parameters described in schema). The description adds usage examples for 'query' and reminds about the text max length, but does not add substantial new semantic meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states it performs semantic search inside a fetched record, with concrete examples (SEC 10-K body, article). It mentions pairing with ask_pipeworx_grounded but does not explicitly contrast with other sibling tools like deep_research or recall, so it slightly lacks differentiation.

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

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

Explicitly says when to use: 'when the record is too big to cram into the prompt'. It also explains the benefit: saves context and returns only relevant passages. However, it does not state when not to use or provide alternatives beyond the mentioned pairing.

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 OAuth requirement, subscription creation behavior, delivery verification (SMS/email/webhook), rate limits (10/day SMS), and webhook signing secret one-time return. Annotations already indicate idempotentHint=true and readOnlyHint=false, but description adds useful behavioral context beyond annotations.

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

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

Description is fairly long but well-structured: overall purpose, prerequisites, type details, delivery channels. Each sentence adds value; no filler. Slightly verbose with repeated type info, but overall concise given complexity.

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

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

Covers all types and delivery channels, authentication requirements, and limits. Despite no output schema, mentions return value. Complete for a subscription creation tool with complex parameter options.

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%, yet description adds substantial value: concrete examples for each type's params (e.g., sec_8k with items codes, polymarket_edge with topic), delivery channel details with constraints, and specific JSON structures. Enhances understanding beyond schema.

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

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

Description clearly states verb 'Create', resource 'proactive monitoring subscription to a live-data event stream', and output 'Returns the new subscription id'. It distinguishes from siblings like list_subscriptions and unsubscribe by specifying creation of new 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?

Provides explicit context: requires Pipeworx OAuth account, lists supported types with parameters, and details delivery channels with constraints. Lacks explicit when-not-to-use or alternatives, but context is comprehensive.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds rich behavioral context beyond annotations: it returns category-bucketed examples with live catalog information, explains the optional focus parameter, and describes the tool's role as an onboarding guide. 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 a single paragraph but efficiently packs purpose, example inputs, return format, usage instructions, and context. It is front-loaded with the tool's synonyms and use case. Slightly long but every sentence is necessary. Could be more structured, but it's concise.

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

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

Given no output schema, the description thoroughly explains return format (category-bucketed examples with tool+argument shape). It covers parameter behavior, use cases, and even mentions the live catalog. The tool's role as a first-stop is fully conveyed. Context appears complete for an onboarding tool.

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

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

Schema covers the single 'topic' parameter with description and valid values (finance, pharma, etc.). Description adds meaning by explaining the effect of omitting vs. providing a topic ('full spread' vs. focus). It reinforces the schema's enum values. With 100% schema coverage, baseline is 3; the description adds moderate value.

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

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

The description clearly identifies the tool as an onboarding entry point for a connected agent to discover what questions to ask. It lists many example queries ('what can I ask', 'give me ideas') and describes the return format of category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings by explicitly 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 when-to-use guidance: first when unsure of Pipeworx capabilities or to learn meta-tools. It explains how to use it (no arguments for full spread, topic parameter for focus). It could be more explicit about when not to use, but the context is sufficient.

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

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

Annotations already indicate idempotency and non-destructive nature, but the description adds critical behavioral details: ownership enforcement and the deactivation vs deletion distinction. This provides clarity 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 two sentences, front-loaded with the main action, and every word adds value. It is concise, clear, and well-structured.

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

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

For a simple one-parameter tool with no output schema, the description provides sufficient context about behavior (ownership, deactivation) and references sibling tool recent_alerts. It could mention the return behavior or error cases, but given the simplicity, it is mostly complete.

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

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

The schema covers the single parameter 'id' with a full description. The description adds no new information about the parameter beyond referencing it by 'id'. With 100% schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource (subscription). It distinguishes itself from sibling tools like subscribe and list_subscriptions by specifying the effect (deactivation, not deletion).

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

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

The description implies when to use (to cancel a subscription) and provides important context: ownership enforcement and that historical events remain. However, it does not explicitly mention when not to use this tool, though the purpose is clear enough given the sibling context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds rich behavioral context: it uses two verification paths, returns specific verdicts (confirmed, approximately_correct, refuted, etc.), includes citations with pipeworx:// scheme, and notes it replaces multiple sequential calls. 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 well-structured, front-loaded with natural-language examples for easy understanding. Every sentence adds value: intent, verification paths, verdicts, citations, efficiency claim. However, it is somewhat verbose; could be slightly tighter without losing substance.

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

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

Given the tool's complexity (two verification paths, multiple verdict types, handling of company vs other claims) and lack of output schema, the description is complete. It covers what the agent needs: purpose, when to use, how it works internally, return values (verdict, actual value with citation, reasoning). Nothing essential is missing.

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

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

Schema description coverage is 100%; both parameters are described in the schema. The description adds meaning beyond schema by explaining default tolerance behavior ('implied by wording, capped at 5') and override use case ('set 1–2 for hallucination detection'). This enhances understanding of parameter usage.

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

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

The description uses clear verbs like 'validate', 'fact check', 'verify the claim' and explicitly states it checks factual claims against authoritative sources. It distinguishes itself from siblings by detailing two verification paths: SEC EDGAR for company financials and grounded pipeline for other claims.

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

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

The description explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two verification paths and what claims each handles. However, it does not explicitly mention when not to use or provide alternatives among sibling tools.

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