Prayer Times

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

Annotations already mark readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds important behavioral details: costs for Anthropic calls, per-model return structure (score, confidence, signals, raw_response), and combined view. 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 coherent paragraph that front-loads the action and return type. It is informative without being verbose but could benefit from slightly more structured formatting for quick scanning.

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

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

Given 4 parameters (all described), no output schema, and sibling tools, the description adequately covers return format, usage context, and parameter behavior. It is sufficiently complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds extra value by explaining default model, cost implications for _apiKey, and how the 'context' parameter helps disambiguate. This goes beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for brand/topic knowledge and provides a visibility score. It distinguishes itself from sibling tools (e.g., deep_research, entity_profile) by focusing on AI visibility scoring, not general search.

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

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

The description explicitly mentions use cases (marketing audits, pre-launch checks, competitive monitoring) and default behavior. It lacks explicit 'when not to use' guidance but provides sufficient context for appropriate invocation.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond annotations: it reveals that the tool is a router that fills arguments, picks the right underlying tool, and returns structured answers with stable citation URIs. It does not mention rate limits or auth, but given the annotation coverage, the added transparency is strong.

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 and front-loaded with the most important instruction: 'PREFER OVER WEB SEARCH.' Every section serves a purpose: scope, behavior, usage triggers, examples, and alternatives. Some redundancy exists between 'Use whenever' and the examples, but overall it is efficient for the complexity of the tool.

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

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

For a high-complexity router tool with no output schema, the description explains what the return value looks like (structured answer with pipeworx:// citation URIs), what kinds of questions are appropriate, and how to choose between this and related tools. The input schema covers the parameters, so nothing essential is missing for an agent to select and invoke the tool correctly.

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

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

The input schema covers 100% of the parameters, including the aliases q, text, input, query, prompt, and question, all documented as natural-language question inputs. The description adds helpful examples but no fundamentally new parameter semantics; the schema already carries the burden. A 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 states a clear verb and resource: it routes questions to one of 5,798 tools across 1,517 verified sources and returns structured answers with pipeworx:// citations. It explicitly positions itself as preferable to web search for factual/current/historical data, and it names sibling alternatives like ask_pipeworx_grounded and deep_research, making its role distinct.

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 detailed when-to-use guidance: prefer over web search, use for factual questions about real-world entities, events, or numbers, with concrete example queries. It also provides exclusion/alternative conditions: use ask_pipeworx_grounded for exact-citation single-answer questions and deep_research for broad/multi-part questions, so an agent knows when not to pick this tool.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds substantial context: candidate routing improvements may be live, no candidate is active as of 2026-07-26, so it currently matches ask_pipeworx exactly, and it is a full working router with no fallback. This temporal and experimental detail is genuinely useful 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?

The description is well-structured: it front-loads the beta relationship, then gives the current state, usage guidance, and a caveat against treating it as a fallback. Each sentence contributes meaning; there is only minor redundancy between 'currently matches ask_pipeworx exactly' and 'Falls back to nothing'.

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

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

With full schema coverage and annotations covering safety and idempotency, the description is sufficient for correct invocation. It states how to use it, its current state, and that the response shape matches ask_pipeworx, which mitigates the lack of an output schema. Nothing about selection or invocation 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?

The input schema already documents all six parameters with 100% coverage, including the note that question accepts aliases. The tool description only says 'same arguments' without adding any parameter-specific semantics, so it adds no value beyond the schema.

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

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

The description states it is the beta version of ask_pipeworx, an identical universal router with the same 5,798 tools, arguments, and response shape. This clearly positions it as an experimental routing tool for user questions, though the exact function still relies on knowing what ask_pipeworx does. It differentiates from the stable ask_pipeworx sibling by being the experimental edge.

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

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

It explicitly instructs to use it exactly like ask_pipeworx when the newest routing is desired and notes results are compared against the stable router to decide merges. The 'experimental edge' language implies it is not for stable/production use, though no alternative beyond ask_pipeworx is explicitly named.

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

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

Beyond the annotations, the description discloses substantial behavior: it returns a structured success object with verbatim evidence and confidence, and an explicit refusal object with enumerated refusal reasons when the data doesn't directly answer. It also reveals the cost tradeoff of one extra LLM call. No contradiction with the readOnly, openWorld, idempotent, or non-destructive hints.

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

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

The description is dense but every sentence earns its place: function, routing, success shape, failure shape, use cases, and cost tradeoff. The key differentiator ('Hallucination-resistant answer mode for high-stakes reads') is front-loaded, and the refusal reasons are compactly enumerated.

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

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

With no output schema, the description compensates by fully specifying the return shape for both success and refusal paths, including refusal reason enums. Combined with a self-documenting input schema and comprehensive annotations, nothing critical is missing for an agent to invoke this tool correctly.

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

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

The input schema already documents the question parameter and all its aliases with 100% coverage, so the description doesn't need to add parameter-level detail. The description adds no new semantics about how to phrase the question, but that is acceptable because the schema is fully self-sufficient.

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 a specific capability: hallucination-resistant, grounded answer extraction for high-stakes reads. It explicitly contrasts itself with ask_pipeworx by describing the same routing but with stricter evidence-only extraction, and it names sibling alternatives with differentiating 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 gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also tells the agent when not to use it: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call.

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 (readOnly, idempotent), the description covers safety short-circuits, closed market handling, wide spread warnings, resolution-rule risk, and resolver contract. These details are critical for safe invocation and go far 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 very long (over 600 words) and includes extensive examples, lists, and edge cases. While well-structured with clear sections, it lacks conciseness and could be trimmed without losing essential meaning.

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

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

Given no output schema, the description explains every part of the response (market, analysis, evidence), resolver contract, parent event, news fields, safety, and resolution rules. It is exceptionally complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline 3. The description reinforces parameter meanings (e.g., depth enum, include_raw default) but adds no fundamentally new information beyond the schema.

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

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

The description clearly states 'Research a Polymarket bet by pulling the relevant Pipeworx data' and specifies input formats (slug, URL, question). It differentiates from siblings like polymarket_arbitrage or polymarket_edges by emphasizing evidence gathering and classification.

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 use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). While it does not provide explicit when-not-to-use guidance, 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?

Discloses data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and citation URIs. Annotations (readOnlyHint, etc.) are already positive; description adds valuable behavioral context 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?

Every sentence adds value, but the description is a dense block of text. Could be slightly more structured with line breaks, 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?

Given no output schema, the description mentions return type ('paired data + citation URIs'), covers edge cases (off-calendar fiscal years), and is sufficient for a 2-parameter comparison 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% coverage with descriptions for both parameters. Description enhances by specifying the exact financial metrics for company type and count types for drug type, and confirms min/max items.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs, using examples of user queries. It distinguishes from siblings like entity_profile by specifying the multi-entity comparison scope.

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. Also implies when not to use (e.g., single entity lookup).

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, destructiveHint=false, so the tool is safe. The description adds no behavioral details beyond the conversion action, such as handling of invalid dates or output format. It relies on annotations for safety but provides no extra 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?

Two sentences with no unnecessary words. The purpose is stated first, making it easy for an agent to quickly understand the tool's function.

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 conversion task, good annotations, and clear parameter schema, the description is generally adequate. However, it lacks information about the return value (e.g., format of Hijri date), which is a gap since there is no output schema.

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

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

Schema coverage is 100% with a clear description of the date parameter format (DD-MM-YYYY). The tool description does not add extra semantic information beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states it converts a Gregorian date to the Hijri calendar date, with a specific verb and resource. This purpose is distinct and well-defined.

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

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

The description says 'Useful for Islamic calendar date conversion,' which implies usage context but does not specify when to use this tool versus alternatives like hijri_calendar. No explicit guidance on prerequisites or when not to use it.

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

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

Even with strong readOnly/openWorld/idempotent/non-destructive annotations, the description adds substantial behavioral context: it produces a findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and never invents answers. It also discloses auth requirements, paid-tier limits, citation fetchability guarantees, semantic excerpting, and expected latency.

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

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

The description is front-loaded with the account requirement and the alternative tool, and nearly every sentence adds useful behavior. However, it is overly long and contains redundant guidance such as the repeated 'For a single lookup use ask_pipeworx instead' and depth-mode details already present in the schema, which hurts conciseness.

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

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

With no output schema present, the description carries the full burden of explaining return values, and it does so thoroughly: findings packet fields, gaps[], contradictions[], hop field, citation_uri, semantic excerpting, latency, auth, and depth behavior. For a research tool of this complexity, no critical invocation or interpretation information appears to be 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% and the schema already documents both parameters in detail, including depth facet counts, iteration hops, and the paid requirement. The description adds latency expectations and examples, but it mostly restates the schema rather than providing new parameter syntax or deeper field semantics.

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

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

The description clearly states a specific verb and resource: grounded multi-source research across Pipeworx's 1,517 structured data sources, decomposing a question into facets and routing them across 5,798 tools in parallel. It also differentiates itself from open-web search and from ask_pipeworx, which makes the tool easy to pick out among siblings.

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

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

The description explicitly says when to use it: 'Best for broad/multi-part questions over structured data' and gives example queries. It also explicitly names the alternative and the condition to choose it: 'For a single lookup use ask_pipeworx instead' and 'If you are not signed in, use ask_pipeworx instead'.

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

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

Annotations already declare safe, idempotent, non-destructive. Description adds valuable context: returns tools with full schemas and examples ready to call, no second lookup needed. 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?

Concise, front-loaded with purpose and usage, every sentence adds value. 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?

Describes what is returned (tools with schemas), default/max limits, and usage context. Lacks error handling or no-match scenario, but overall sufficient for a discovery tool.

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

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

Schema coverage is 100%, so baseline 3. Description acknowledges aliases and limit default, but does not add significant new meaning beyond schema.

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

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

The description clearly states it discovers tools by describing data or task, lists many domains, and explains it returns top-N tools with schemas. It is distinct from sibling tools as the 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?

Explicitly says 'Call this FIRST when you have many tools' and provides clear use cases. Lacks explicit when-not-to-use, but positive guidance is strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes well beyond that by explaining the parallel fan-out across sources, the semantics of sources_used/sources_failed, the meaning of empty sections ("a real 'no data', not a bug"), the GDELT→GNews fallback, and the private-company notes response. This is rich behavioral context with no contradiction.

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

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

The description is long but information-dense; each sentence adds a distinct detail about sources, output, edge cases, or input format. It is front-loaded with user examples and the key "ONE parallel call" concept. It could be slightly better organized with separate paragraphs, but it is far from bloated given the tool's complexity.

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

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

Given no output schema and two simple params, the description covers essentially everything an agent needs: what the tool is, when to use it, what sources it queries, what main fields are returned, how to handle empty results, how to pass inputs, and what happens for private companies. No critical gap is 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% and the schema descriptions are already strong. The description adds value by clarifying that type accepts "company" or "ticker" interchangeably and that value can be a ticker, CIK, or company name with resolution via SEC EDGAR, which reinforces and slightly extends the schema without repeating it verbatim.

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

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

The description states a specific verb and resource: "full cross-source profile of a US public company in ONE parallel call." It gives concrete example user intents ("Tell me about X", "research Acme") and enumerates the data sources and return fields, making the tool's function unmistakable and distinct from single-source 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 says "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view," which tells the agent when to choose this tool over alternatives. It also clarifies behavior for private companies (resolved:false), but it doesn't explicitly name sibling tools like resolve_entity or compare_entities or state when not to use this tool for narrower 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 indicate destructiveHint=true. Description adds context about staling and sensitive data, but doesn't mention error handling for missing keys. Still, bulk of behavioral info is covered.

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

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

Two sentences, no wasted words. First sentence states action, second gives usage context. Ideal front-loading.

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?

Simple tool with one parameter and destructive annotations. Description covers purpose, usage, and sibling relations. Slightly missing mention of what happens on failure, but sufficient for the complexity.

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

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

Schema coverage is 100% with a clear description for 'key'. Description does not add further semantics beyond what the schema provides, so baseline of 3 is appropriate.

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

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

The description uses a specific verb 'delete' and resource 'stored memory by key', clearly distinguishing it from siblings 'remember' and 'recall' by explicitly pairing them.

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

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

Explicitly states when to use: when context is stale, task done, or clear sensitive data. Also suggests pairing with remember and recall, guiding when not to use alone.

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 false, which the description does not contradict. The description adds behavioral details: fetches the page, extracts title/description/links, and emits markdown format. No rate limit or error handling mentioned, but for an idempotent read tool, this is adequate.

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 two efficient sentences plus a short list of use cases, with no redundant words. Every sentence adds value, and the purpose is front-loaded.

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

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

For a simple tool with two parameters and no output schema, the description explains inputs, process, output format, and use cases. It is fully complete given the tool's straightforward nature.

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

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

Input schema has 100% coverage, describing both parameters (url and max_links) fully. The description does not add significant new meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

Title and description clearly state the tool generates llms.txt files, specifying the verb 'generate', the resource 'llms.txt file', and context for AI crawlers. It distinguishes itself from related siblings like 'scan_competitor_ai_presence' by focusing on this specific output 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?

Description lists explicit use cases (getting a client's site indexed, drafting for own project, auditing competitor) that help an agent decide when to use the tool. It does not explicitly state when not to use it or mention alternatives, but the provided 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 readOnlyHint, idempotentHint, and destructiveHint=false, covering safety and idempotency. The description adds that it returns per-day dates and salah times, but does not disclose rate limits, precision of times, or any other behavioral details 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?

Single, front-loaded sentence that immediately conveys the tool's purpose. Every word earns its place; no redundancy or filler.

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

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

For a monthly calendar retrieval tool with no output schema, the description adequately explains what is returned (per-day dates, both calendars, five salah times). It could mention output format or scope but is sufficiently complete for typical use.

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

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

Schema coverage is 100% with each parameter described (city, year, month, method, country). The description does not add meaning beyond the schema; it only describes the output. 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 provides a monthly Islamic prayer-times calendar for a city, including per-day Gregorian and Hijri dates with five salah times. This distinguishes it from sibling tools like prayer_times (likely daily only), qibla (direction), and convert_to_hijri (date conversion only).

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

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

The description implies usage for obtaining a monthly prayer calendar, but it does not explicitly tell when to use this tool versus siblings like prayer_times or convert_to_hijri. No when-not-to or alternative selection guidance is provided.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds return fields and default active filter, providing 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?

Two sentences, front-loaded with purpose and return fields, then usage. No wasted words.

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

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

For a simple list tool with one optional param and no output schema, the description fully explains output fields and usage context, leaving no gaps.

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

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

Schema covers the single parameter with 100% description coverage. Description adds no extra parameter info, meeting the baseline.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Differentiates from subscribe/unsubscribe siblings.

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

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

Explicitly instructs when to use: 'before adding more or to find an id to cancel', guiding tool selection.

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

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

With annotations lacking positive safety signals (readOnlyHint false), the description carries behavioral burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token workflow, and 'doesn't count against your tool-call quota'. It doesn't explicitly state that a message is transmitted to the team, though 'telling' and 'filing' imply it.

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 each sentence earns its place, covering purpose, usage, exclusions, claim token flow, and rate limits. It is logically ordered but presented as a single long paragraph; breaking it into sections would improve readability without adding bulk.

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 behavior (claim_token), follow-up mechanism, rate limit, scope restrictions, and why not to file for other servers. It fully compensates for lack of an output schema and is complete for a feedback tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning beyond schema for claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed'), and for message ('don't paste the end-user's prompt'). This elevates parameter clarity.

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 'Tell the Pipeworx team something is broken, missing, or needs to exist' and enumerates specific feedback types (bug, feature, data_gap, praise). It distinguishes from sibling tools like ask_pipeworx by focusing on reporting issues rather than asking questions.

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

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

Provides explicit when-to-use triggers ('tool returns wrong/stale data', 'tool you wish existed isn't in catalog', 'worked surprisingly well') and a clear when-not-to-use exclusion ('ONLY for tools served by this Pipeworx connection... file it with that server instead'). Also explains how to claim tokens for follow-up.

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 value beyond annotations: explains data is derived from CF analytics-engine, no PII, and caching behavior. No contradiction with readOnlyHint or other annotations.

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

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

Three focused sentences, front-loaded with action, each sentence adds distinct value with no redundancy.

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

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

Even without output schema, description specifies return fields (top tools, packs, call volume) and adds caching and data origin details, meeting completeness needs for a simple analytics tool.

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

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

Schema coverage is 100% and description adds guidance on window selection (shorter for hot topics, longer for steady-state), enhancing parameter meaning beyond enum values.

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

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

Description clearly states the tool returns top tools, packs, and call volume over recent windows, distinguishing it from sibling tools like ask_pipeworx or discover_tools by focusing on trending data.

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

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

Explicitly lists three use cases (discovering hot sources, confirming canonical tools, alignment checking), but does not mention when to avoid or directly compare against 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?

Description adds significant behavioral context beyond annotations: explains semantic anchor (Jaccard similarity), partition filter (placeholder fraction), fill check against live CLOB depth, and that trade is not recommended when edge is only at last-trade. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent.

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 dense but well-structured: main purpose first, then mode details, then additional filters and fill check. Every sentence adds value, though length could be reduced by about 20% without losing information. Front-loading is effective.

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

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

Despite no output schema, the description thoroughly outlines the response structure (opportunities[], partition_check fields), explains the fill check, and references sibling tools. Covers behavioral nuances like Jaccard similarity threshold and placeholder filtering, making the tool fully understandable for selection and invocation.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds value by explaining that 'event' accepts full Polymarket URLs and 'topic' is a seed question, and elaborates on how each mode works. Could be slightly more concise, but adds meaning beyond schema.

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

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

Clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes between single-event and cross-event modes with specific examples. Describes response structure including opportunities array and partition_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?

Explicitly explains when to use 'event' mode (for a specific market) vs 'topic' mode (for cross-event scanning), including examples of seed questions. Provides warnings about fill check and when not to trade (realizable_edge_pp ≤ 0). References sibling tool for custom sizing.

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

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

The description provides extensive behavioral details beyond the annotations (readOnlyHint, idempotentHint, destructiveHint=false). It explains the internal models (crypto_price, news_momentum, partition_overround, concentrated_longshot), edge calculation (edge_pp_net, Kelly fractions), filters (min_liquidity, max_spread_pp), output structure (by_segment, diagnostics), and caching behavior. 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 long but densely informative, front-loaded with the main purpose and followed by structured sections on model families, response segments, and knobs. While every sentence adds value, the length could be slightly trimmed for quicker parsing, but given the complexity it is well-organized.

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

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

Given the absence of an output schema, the description thoroughly explains the response structure (by_segment, diagnostics), return fields (edge_pp_net, kelly_fraction, etc.), and caveats like Fed bets and caching. It covers all essential aspects for the agent to understand what the tool returns and how to interpret results.

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

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

The input schema has 100% coverage with detailed descriptions for all 9 parameters, providing a baseline of 3. The description adds value by explaining how parameters like min_liquidity, max_spread_pp, and min_partition_leg_kelly function as 'tradeable-edge knobs' and their interaction with the opportunity filtering, which 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and resource 'Polymarket markets', and the purpose is distinctly about edge detection, differentiating from sibling tools like polymarket_arbitrage or polymarket_fill_risk.

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 the use case: 'what should I bet on today' and that agents discover opportunities without paging. However, it does not provide explicit when-not-to-use scenarios or name specific alternatives, though the context implies it is for edge discovery rather than other Polymarket operations.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. Description adds key behavioral details: 60-day snapshot TTL, decay computed from daily closes, gaps meaning no scan, and response structure including trend and decay rates. No contradiction with annotations.

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

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

Description is well-structured with separate sections for purpose, parameters, response, and limitations. While somewhat verbose, every sentence adds value. Front-loaded with the core question it answers, making it easy to scan.

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 full parameter coverage, rich annotations, and no output schema, the description provides comprehensive details: response structure (tracked, expired, snapshot_dates), limits (TTL, decay computation), and edge cases (gaps). No significant gaps remain.

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

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

Schema covers both parameters (days, window) with descriptions. Description adds context: days default 14, max 30 (schema says clamp 2-30), window default '1wk' and explanation of 'snapshot family'. Also provides detailed response structure, which is valuable given no output schema.

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

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

Description clearly states it provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge duration and trend. It distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on historical persistence and decay.

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 answers 'how long has this edge existed and is it shrinking?' with a concrete example contrasting fresh vs. old edges. While it does not explicitly list when not to use or mention alternatives, the purpose is clear enough to guide appropriate tool selection.

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

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

Description explains it walks the order book ladder, returns top-of-book, VWAP, slippage, shares filled, verdict, and for basket mode returns theoretical vs realizable sums, capture ratio, profit, thin legs, etc. Annotations already declare readOnly, idempotent, non-destructive, so description adds behavioral context 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?

Description is long but well-structured: starts with purpose, then mode requirements, then detailed explanations. Every sentence adds value given the tool's complexity. A minor inefficiency is repetition of 'buy_yes|sell_yes...' in parameters, but overall compact for the information density.

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

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

No output schema, but description lists all return fields for both modes, including verdict values and forced_directional_risk. It explains the dominant loss mode (unhedged directional position). Missing error handling details (e.g., invalid slug), but for a tool of this complexity, coverage is high.

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

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

Schema description coverage is 100%, but description adds meaning: explains default side for basket mode, interpretation of size_usd (spend vs target proceeds vs settlement notional), clamp range 10-1,000,000, and mode selection logic (auto side based on partition sum).

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

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

The description states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and describes two modes (single-market and basket). It clearly distinguishes from siblings like polymarket_arbitrage and polymarket_edges by being a prerequisite risk 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?

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 thin books and partial fills converting arb into directional position. Requires one of `market` or `event`.

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

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

The description goes well beyond the readOnlyHint/idempotentHint annotations: it discloses that returned pairs may still carry compatibility warnings, that temporal_alignment null means 'not computed' rather than aligned, that Kalshi fees are not modeled so spreads are gross, and that skipped comparisons are exposed via counters. This is rich, honest behavioral context for a tool whose output cannot be blindly trusted.

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

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

The description is long but well-structured into labeled sections (modes, response, safety fields, codes, skipped comparisons, fee note). It is front-loaded with the core purpose and mode choice, and while dense, each sentence contributes either operational guidance or a caveat necessary for correct interpretation. It is not minimal, but the complexity 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?

With no output schema, the description carries full responsibility for explaining return behavior, and it does so thoroughly: venue prices, spread values, compatibility codes and flags, temporal alignment semantics, fee caveats, skipped-leg counters, and the candid warning that pre-mapped topics are often not tradeable. An agent has enough context to call the tool and interpret its output without guessing.

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 documents all three parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantics beyond the schema: `topic` is a pre-mapped macro shortcut list, and the explicit ticker/slug parameters override the topic-mapped side. This clarifies relationships between parameters that raw schema descriptions leave implicit.

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

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

The description opens with a precise statement of what the tool computes—cross-venue spread between Kalshi and Polymarket for the same resolving question—and immediately distinguishes its two operational modes. This makes it clearly separate from the sibling tools such as polymarket_edges or polymarket_arbitrage based on venue coverage and intent.

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 explains when to use `topic` shortcuts versus explicit `kalshi_event_ticker` plus `polymarket_event_slug` pairings, and clarifies that both modes run the same matcher. It does not explicitly name sibling tools as alternatives or state exclusions, but the within-tool mode guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds context: that it returns timings, Gregorian and Hijri dates, timezone, and method used, which helps agent understand output.

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 lists the times, second explains inputs and outputs. Every word is useful, no redundancy.

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

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

Given no output schema, the description mentions what is returned (timings, dates, timezone, method). Parameter count 5 with full schema coverage and examples suffice for agent to use 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% (all parameters have descriptions). The description further explains the relationship between city/country and lat/lon, and provides example method values, adding meaning beyond schema.

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

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

The description clearly states it returns Islamic prayer times (listing all times) for a location today, which is a specific verb-resource pair. It distinguishes from sibling tools like qibla (direction) and convert_to_hijri (date conversion).

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 two input methods (city+country or lat/lon) and mentions it's for today. It does not explicitly say when not to use it or list alternatives, but the purpose is clear and sibling tools are distinct.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, covering safety and idempotency. Description adds that output is in degrees from true north, which is behaviorally relevant. 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?

Single sentence that front-loads the key purpose and output format. No unnecessary words, every part earns its place.

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

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

For a simple calculation with well-annotated safety profile and complete schema, the description is adequate. No output schema but return value is implied; could mention precision, but not crucial.

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 clear explanations for latitude and longitude. Description does not add additional meaning beyond restating that parameters are latitude/longitude. Baseline 3 is appropriate.

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

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

Description clearly states the tool computes qibla direction (compass bearing toward Kaaba) from latitude/longitude in degrees from true north. This is specific and distinguishes from siblings like prayer_times which also use location but for different purpose.

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

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

No explicit when-to-use or when-not-to-use guidance. However, the description is self-explanatory enough that the context of needing qibla direction makes usage clear. Siblings like prayer_times and convert_to_hijri handle related but distinct tasks, but no comparison is provided.

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

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

Adds context beyond annotations: scoping to identifier (anonymous IP, BYO key hash, account ID). No contradictions with readOnlyHint and idempotentHint.

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, front-loaded with core action. Every sentence adds value: action, use case, scoping, and pairing with siblings. No redundancy.

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

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

Covers purpose, usage, scoping, and relationships. Lacks mention of error handling (e.g., key not found) but is otherwise complete for a simple retrieval 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 100% of parameters. Description adds the key usage nuance: 'omit to list all keys', which enhances semantic 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?

Clearly states the verb (retrieve/list) and resource (values saved via remember). Distinguishes from siblings 'remember' and 'forget' by explicitly naming the pairing.

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

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

Explicitly advises using to look up previously stored context without re-derivation. Mentions scoping and pairing but does not explicitly state when not to use or list alternatives.

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

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

Annotations state readOnlyHint=true, but description explains mark_read:true flags events as read, which is a mutation. This contradicts the readOnlyHint, so score is reduced.

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

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

The description is concise (~90 words), front-loaded with purpose, and efficiently covers key details without redundancy.

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

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

For a 5-param tool with no output schema, description covers what is returned, filtering, mark_read behavior, and alternative access. Slight gap on pagination beyond limit, but overall adequate.

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

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

Schema covers all 5 parameters with descriptions. Description adds specific usage context (mark_read behavior, filtering hints) 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 pulls fired events from a subscription feed, specifying the resource and verb. It distinguishes from siblings like list_subscriptions and recent_changes by focusing on alert events.

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

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

Provides clear guidance on when to use (pulling recent alerts) and filtering options. Mentions alternative endpoint for scripts/dashboards, but does not explicitly exclude usage scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant behavioral context: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO with PatentsView sunset note. 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 fairly lengthy but every sentence adds value. It starts with example queries, then details behavior, return structure, and sibling differentiation. Could be slightly more concise, but appropriate for the complexity.

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

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

Despite no output schema, the description describes the return format (changes[] grouped by source, total_changes count, citation URIs). All parameters are explained, and the tool's multi-source fan-out behavior is fully documented.

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

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

Schema coverage is 100%, but description adds meaning: explains `since` accepts ISO date or relative shorthand with examples, `type` only supports 'company', `value` can be ticker or zero-padded CIK. This helps correct usage 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 starts with natural language examples like "What's new with X" and clearly states it provides a change feed for a company in a specific time window. It explicitly distinguishes from sibling tool entity_profile, which is for static profiles.

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

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

The description gives explicit usage context: use for change feed queries (e.g., 'updates on Acme'), and advises to use entity_profile instead for static profiles. It also 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?

Annotations indicate idempotentHint=true; description adds key-value scoping by identifier, persistence details (24h for anonymous). Could mention overwrite behavior for existing keys but overall adds good 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?

Four sentences, front-loaded with purpose, then usage, then technical details. No redundancy or filler.

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

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

Simple tool with no output schema. Description covers purpose, usage, persistence, and sibling tools. Fully sufficient given annotations and schema.

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

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

Schema covers 100% of parameters. Description adds usage examples for key (e.g., 'subject_property') and clarifies value is any text. Adds meaning beyond schema definitions.

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

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

Clear verb+resource: 'Save data...reuse later'. Provides concrete examples (ticker, address, preference) and distinguishes from siblings recall/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 states when to use ('discover something worth carrying forward') and pairs with recall/forget. Mentions scoping and persistence but 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses substantial behavior: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit listing of unresolved identifiers under `unresolved`, source-labeled results, cascaded internal lookups, and the policy of returning `figi_candidates` rather than asserting a single match on ambiguous names. This goes well beyond what annotations convey.

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

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

The description is front-loaded with the core purpose and user-phrase examples, and almost every clause carries operational information. However, the supported-type sections are dense monoliths of nested parentheticals and semicolons, which makes scanning harder than necessary. It is efficient in content but not structurally clean enough for 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 tool with no output schema, the description covers input semantics, resolution behavior, ambiguity handling, source coverage, failure/degradation behavior, and the shape of results (CIK, ticker, LEI, ownership, FIGI, RxCUI, ingredient, brand). Given the tool's complexity and cascading lookups, this is thorough enough for an agent to select and invoke it correctly.

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

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

Although schema coverage is 100%, the description adds real semantic value: it enumerates accepted forms for `value` (ticker, CIK, ISIN, company name; brand or generic drug name), provides examples, and warns against passing full noun phrases like 'revenue bonds' because the FIGI lookup matches instrument names. This materially helps an agent choose correct values, exceeding the schema 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 opens with concrete user-phrase examples and states a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes this from lookup/analysis tools by emphasizing that it produces IDs for downstream consumption, and the supported type breakdown further sharpens the purpose.

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

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

The description gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also explains how ambiguity should be handled (e.g., 'asserts nothing and returns figi_candidates'). However, it does not name sibling tools or state when not to use this tool versus alternatives such as entity_profile or compare_entities, so the guidance is strong on when but lacks explicit exclusions.

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

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

Annotations already declare safe read-only, idempotent behavior. The description adds valuable context: it probes entities with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. 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, front-loaded with purpose and key capability. Every sentence adds value without redundancy.

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

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

The description fully explains the tool's behavior, parameters, and return value (ranked list with specific fields). No output schema exists, but the description compensates by detailing what is returned. Given the annotations, it is complete.

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

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

Schema provides 100% description coverage for parameters. The description adds extra meaning: clarifies that the first entity is treated as the 'subject' for narrative, and that _apiKey is passed to api.anthropic.com per probe. This 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?

The description clearly states the tool compares AI visibility across multiple entities side-by-side, ranks by score, and identifies most/least recognized. This distinguishes it from sibling ai_visibility_check which handles single entities.

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

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

The description explicitly indicates use for competitive AI-marketing audits and provides an example query. It implies that for single entity checks, ai_visibility_check should be used, but does not explicitly state when not to use this tool or list alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. Description adds significant behavioral context: composite fan-out, partial failures degrade gracefully (sources_failed listed), bundlephobia first measurement can take 5-30s, and details on return structure (summary block, per-advisory, links, alternatives). 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?

Description is comprehensive but not overly verbose. It front-loads the main purpose and then packs behavioral details, return structure, and limitations. Every sentence adds value, though slightly long. Could be trimmed slightly 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 rich annotations (readOnlyHint, openWorldHint, etc.) and no output schema, the description fully covers return values (summary block with fields, per-advisory detail, links, alternative versions) and behavior (partial failures, timing). Complete for the tool's complexity and ecosystem restrictions.

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 minor value: for 'package' mentions scoped packages accepted, for 'version' mentions defaults to latest when omitted. Baseline 3 is appropriate; schema already provides full meaning.

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

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

Description clearly states it's a composite check for npm packages combining deps.dev (license, advisories, version history) and bundlephobia (size, deps, ESM/tree-shake). Specifies verb 'scan' and resource 'dependency' (npm). Distinguishes from siblings by noting NPM-only vs. other ecosystems under deps.dev:version directly.

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: 'when an agent asks is X safe / popular / small or what does adding lodash cost me'. Also gives when-not: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing clear exclusion and alternative.

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

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

Discloses technical details beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' 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?

One well-structured paragraph. First sentence states purpose, then usage, then pairing, then technical details. No redundant sentences.

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

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

Given 3 parameters, no output schema, and comprehensive annotations, the description fully explains behavior, constraints, and usage context. 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%. Description adds value: max chars for text, range and default for limit, and query examples. Goes beyond schema alone.

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

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

The description states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes itself by noting it's for when the record is too large for the prompt, and pairs with ask_pipeworx_grounded.

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

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

Explicit when-to-use: 'Use when the record is too big to cram into the prompt.' Provides rationale and alternative pairing: 'Pairs with ask_pipeworx_grounded.'

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

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

Discloses mutating nature (creates subscription), requires auth, and adds details on webhook secret one-time return and auto-disable after failures. No contradiction with annotations. However, idempotency hinted by annotation is not reinforced.

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

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

Well-structured with clear sections for types and delivery channels. Every sentence adds value, no redundancy. Front-loaded with key purpose and requirement.

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

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

Covers all necessary context: prerequisites, type-specific params, delivery details, and behavioral notes (webhook secret, auto-disable). No output schema, but description compensates fully.

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

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

Schema covers 100% of parameters, and description adds extensive practical examples for each type and delivery channel, including constraints like E.164 format, verified phone, and webhook URL restrictions.

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 creates a proactive monitoring subscription and returns id. Lists supported types and delivery channels, distinguishing it from sibling tools like list_subscriptions or recent_alerts.

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

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

Explicitly requires Pipeworx OAuth account, and explains that feed is always on while email/sms/webhook are optional with specific prerequisites (phone verification, 10/day cap). Lack of explicit comparison to alternatives is minor gap.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds context about returning category-bucketed example questions with tool+argument shapes, which is valuable 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 front-loads common query phrases and lists categories, but it is somewhat verbose with full category list and repetition. It could be more concise while retaining key information.

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

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

For a tool with no output schema, the description adequately explains what is returned (category-bucketed examples) and context (live tool catalog). It covers the essential information for initial use, though output details could be more explicit.

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

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

Schema coverage is 100% with a description for the single `topic` parameter. The description adds usage nuance (omit for full spread) and lists valid examples, going slightly beyond the schema. Baseline 3 is surpassed.

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

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

The description clearly states it is the onboarding entry point for suggesting example questions, listing specific categories and mentioning use of live tools. It distinguishes itself from siblings by positioning itself as a meta-tool for exploration, not a domain-specific query 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 explicitly says to use this 'FIRST when you do not yet know what Pipeworx can do for you' and explains when to pass a topic vs. omit. It could improve by stating when not to use it (e.g., for direct queries), but the guidance is clear and actionable.

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 (idempotent, non-destructive), clarifies ownership check, row deactivation, and historical event availability. Consistent with annotations.

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

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

Two sentences, front-loaded with primary action, no redundant words. Every sentence adds distinct information.

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

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

For a simple cancellation tool with one parameter and no output schema, description covers action, ownership, effect, and data retention. No gaps.

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

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

Schema covers parameter fully with description; description adds 'by id' which adds minimal value. 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?

Clear verb+resource: 'Cancel a subscription by id.' Title 'Unsubscribe from Alerts' directly states the action. Distinguishes from sibling 'subscribe'.

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

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

States ownership constraint and that deactivation preserves history, implicitly guiding use of 'recent_alerts' for historical data. Could explicitly mention 'subscribe' for creation.

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

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

Beyond the annotations (read-only, idempotent), the description discloses nuanced behavior: can return could_not_verify meaning the check did not happen (carrying verification_error), unsupported meaning no source covers it, and warns not to treat could_not_verify as evidence. This is critical behavioral context not available in labels.

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 packed with necessary details, structured logically: examples → purpose → routing → return values → caveats. It front-loads user intents immediately, and while some repetition exists (e.g., explaining both paths twice), 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 the tool's complexity and lack of an output schema, the description fully explains return values (verdicts, actual value, citation, reasoning) and explains special verdict meanings. It also covers failure modes and scope (what sources are consulted), making the tool's behavior predictable in a wide range of contexts.

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 both parameters well. The description adds examples for the claim format and mentions tolerance behavior (e.g., "set 1–2 for hallucination detection"), but these are supplemental rather than essential, matching the baseline of 3.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources, with examples like "Is it true that…" and "fact check." It distinguishes itself from siblings by explicitly addressing fact-checking, and differentiates financial vs. non-financial claim paths, making its purpose unmistakable.

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

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

It explicitly says "Use whenever the agent needs to check whether something a user said is factually correct," providing a clear trigger. While it does not list when-not-to-use or alternative tools, the instruction is strong enough to guide selection, and it also mentions efficiency benefits by replacing 4–6 sequential calls.

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