Arcgis Tempe

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: the default model is free, probing Anthropic requires a BYO API key with direct payment, and the return structure includes per-model fields. 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 three sentences, front-loaded with the core purpose, followed by key details and use cases. Every sentence adds value, no fluff.

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

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

Despite lacking an output schema, the description explains the return format (per-model score, confidence, signals, raw_response plus combined view). Combined with rich annotations, it fully informs an agent of expected behavior and 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?

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning by specifying the default model, the necessity of _apiKey for Anthropic, and the role of context for disambiguation. 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 verb 'probe', the resource 'LLMs for what they know about a business/brand/product/topic', and the outcome 'score visibility (0-100) per model'. It is specific and distinguishes from siblings by detailing the probing mechanism and scoring.

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

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

The description provides clear usage context with examples like 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It does not explicitly mention when not to use or compare to sibling tools, but the context is sufficient.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds significant behavioral context: it routes to one of 4,552 tools, returns structured answers with pipeworx:// citation URIs, works on every tier, and is fast. This fully characterizes the tool's behavior.

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

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

The description is lengthy but front-loaded with the key directive. It is well-structured with clear sections (preference, routing, examples, alternatives). Every sentence contributes value, though a few redundant examples could be trimmed without loss.

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

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

Given the tool's complexity and the presence of many siblings, the description covers all essential aspects: purpose, usage context, behavioral traits, and return format (structured answer with citations). No output schema is needed as the description clarifies what is returned.

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

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

While the input schema already describes all 6 parameters (aliases for question) with 100% coverage, the description does not add further semantic details about parameter format, constraints, or behavior beyond the schema. The examples illustrate usage but do not enhance parameter understanding.

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

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

The description clearly states that the tool routes questions to a vast set of authoritative sources and returns structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its purpose and scope unambiguous.

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

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

The description provides explicit guidance on when to use this tool (prefer over web search for factual questions) and when to use alternatives (e.g., ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad queries). It also lists example query types and advises starting here as the default entry point.

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

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

Annotations already indicate safe, non-destructive, idempotent behavior; description adds rich behavioral details: routing, argument filling, extraction only from tool result, explicit return structure with evidence and refusal reasons, and cost implication.

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 relatively long but efficient, front-loaded with purpose and usage. Each sentence adds value; however, it could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (routing over 4,552 tools, refusal handling) and absence of output schema, the description covers behavior, return format, and error conditions well. Minor gap: does not explicitly mention how to structure questions.

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 does not add significant meaning beyond the alias list already present in the schema.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes it from sibling 'ask_pipeworx' by highlighting the refusal mechanism and extra LLM call.

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

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

Explicitly provides when-to-use (high-stakes, quoted/cited answers) and when-not-to-use (casual lookups, prefer ask_pipeworx), with direct sibling alternative 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?

Description goes far beyond annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing resolution process, classifier fan-outs, response shapes, resolver confidence, parent events, news fallbacks, safety checks, wide spread handling, and resolution-rule risk. 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 very long and dense, covering many details but lacking clear structure (no bullet points or sections). While informative, it could be more concise and better organized 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 the tool's complexity, description covers all aspects: resolution, classifiers, fan-out examples, response shapes, confidence handling, parent events, news fallbacks, safety, wide spread, and cancellation rules. No output schema, but return shapes are well described.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by explaining depth parameter (quick vs thorough), market input variations, and include_raw's implications (size, use cases for raw data). 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?

Description clearly states it researches a Polymarket bet by pulling Pipeworx data, specifying input types (slug, URL, question text) and output (evidence packet + comparison). Distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on single bet research.

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

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

Provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and handles various input formats. Does not explicitly state when to use alternatives like polymarket_edges, but the context is clear.

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

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

Beyond annotations (readOnlyHint, not destructive), the description reveals behavioral details: it pulls specific financial data from SEC EDGAR/XBRL for companies, handles off-calendar fiscal years, and for drugs pulls FAERS data. It also mentions sorting by primary metric and returning citation URIs.

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

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

The description is a single dense paragraph that front-loads example queries, then states the tool's purpose, then provides detailed behavior. Every sentence adds essential information with 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?

Despite lacking an output schema, the description explains the return format (paired data + pipeworx:// citation URIs). Combined with annotations (readOnly, idempotent, not destructive), the description provides a complete understanding of the tool's inputs, behavior, and outputs.

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

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

Schema covers both parameters (100% coverage). The description adds semantic value by explaining what data each 'type' value retrieves (e.g., latest 10-K for companies, adverse-event counts for drugs) and how 'values' should be provided (tickers/CIKs or drug names). This enriches the schema's basic descriptions.

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

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

The description explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and provides example queries. It clearly distinguishes itself from sequential single-entity lookups, making the purpose unmistakable.

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

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

The description says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' offering explicit guidance on when to use this tool over alternatives. It also clarifies the comparison context for types 'company' and 'drug'.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: account required, paid tier for 'thorough' depth, 15-60s expected time, returns gaps[] for unanswered facets, and a note that it does not invent data. 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 longer than average at ~200 words, but it is well-structured: front-loaded with critical account requirement, then functionality, then usage guidance, then warnings. Every sentence serves a purpose, though some rephrasing could tighten it slightly.

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

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

Despite no output schema, the description fully explains what the tool returns: a findings packet with verbatim evidence, confidence, source, fetched_at, a stable pipeworx:// citation per finding, and explicit gaps[] for unanswered facets. This gives the agent a complete picture of the output.

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

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

Schema coverage is 100%, so the description doesn't need to add much. It explains the depth enum values in terms of number of facets (quick=3, standard=5, thorough=8) and clarifies that the question can be broad/multi-part. This adds meaningful context beyond the schema.

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

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

The description clearly states the tool performs grounded multi-source research across 1,160 structured data sources using parallel decomposition. It distinguishes itself from sibling tools like ask_pipeworx by explicitly stating it is not open-web search and is for broad/multi-part 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?

The description explicitly says when to use (broad/multi-part questions over structured data) and when not to (breaking news, current events, single lookup). It directly names ask_pipeworx as an alternative for those cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds value by explaining the return format: 'returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' Also conveys the 'call first' behavior. No contradictions.

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

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

Four sentences, each serving a distinct purpose: purpose, usage, return details, and best practice. No filler or redundant repetition. Information is front-loaded with the core purpose, making it efficient for the agent to parse.

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

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

Given the tool's simplicity (query in, list out) and no output schema, the description fully covers input expectations, output format, and usage context. It explains what the agent gets back (schemas, examples) and when to use it (first among many tools). Nothing essential is missing.

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

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

Schema description coverage is 100% (all 6 parameters described). The description does not add new meaning beyond what the schema provides (e.g., lists aliases, which are already in schema). For a tool with full schema coverage, 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 starts with 'Find tools by describing the data or task,' clearly stating the verb and resource. Lists many specific domains (SEC filings, financials, FDA, etc.) and distinguishes from sibling tools like search_datasets or query_layer by explicitly stating 'Call this FIRST when you have many tools and want to see the option set.'

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 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and includes a call to action: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implicitly excludes use when the agent already knows the tool.

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

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

Annotations already declare read-only, idempotent, open-world. Description adds substantial behavioral detail: parallel fan-out across multiple sources, specific return fields, patent sunset soft-fail, and URI patterns. No contradiction.

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

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

Description is detailed but front-loaded with key usage. Every sentence is necessary for completeness, though could be slightly tighter.

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

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

Despite no output schema, description lists all return components, limitations, and data sources. Provides sufficient context for an agent to understand full behavior and output structure.

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

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

Schema covers 100% of parameters; description adds meaning by explaining value format (ticker or zero-padded CIK), unsupported names, and examples. Adds value beyond schema.

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

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

The description clearly states the tool's purpose: profiling a US public company via multiple data sources in one parallel call. Example queries and explicit preference over chaining single-source tools distinguish it from siblings.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack lookups' for holistic views and warns that names are not supported, directing to resolve_entity first. Provides clear when-to-use and when-not-to-use.

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

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

Description matches annotations (destructiveHint true). Adds context on motivation for deletion (stale context, sensitive data). No contradiction.

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

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

Two concise sentences. First states action, second provides usage guidance. No superfluous content.

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

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

Simple tool with one param and no output schema. Description covers purpose, usage, and parameter adequately. Sibling tools provide context.

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

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

Only parameter 'key' has schema description. Schema coverage is 100%, so description adds no extra meaning. 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?

Clearly states the tool deletes a memory by key. Verb 'delete' and resource 'memory' are specific. Distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly states when to use: when context is stale, task done, or clearing sensitive data. Also advises pairing with 'remember' and 'recall'.

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 valuable context by explaining the process (fetches page, extracts title/description/links, emits markdown) and output format (text blob). No contradictions noted.

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, with three well-structured sentences that front-load the core purpose and avoid unnecessary words. Every sentence adds value.

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

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

For a simple, read-only tool with two parameters and no output schema, the description fully covers its functionality, process, and use cases. No gaps remain given the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add new semantic details beyond what the schema already provides for the url and max_links parameters.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the action and resource. It implies a distinct purpose from sibling tools by focusing on llms.txt generation, but does not explicitly distinguish itself from related tools like ai_visibility_check.

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

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

The description provides explicit use cases (client indexing, own project, competitor audit) that guide when to use the tool. However, it lacks exclusion criteria or alternative tool references, so it does not fully meet the highest bar.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which indicate a safe, non-destructive operation. The description adds behavioral context by enumerating the schema details returned (fields, geometry type, record count, capabilities), enhancing transparency beyond the annotations.

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

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

The description is a single sentence that front-loads the action and resource. It efficiently lists the returned items without any extraneous words. Every part of the 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 simplicity (one parameter, no output schema, good annotations), the description covers the essential output details. It lists all returned elements (fields, geometry type, record count, capabilities). While it does not discuss error handling or performance, the annotations and schema cover safety and parameter format. The description is nearly complete for this context.

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

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

The schema coverage is 100% with one parameter 'url' that has a meaningful description including an example format. The tool description reinforces the 'by url' aspect but adds no new semantic information beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the action 'Get', the resource 'schema', and the type of service 'ArcGIS Feature/Map Service layer'. It lists specific return fields (fields with name+type, geometry type, record count, capabilities), which distinguishes it clearly from sibling tools like 'query_layer' that likely query data.

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

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

The description mentions 'by url' but does not explicitly state when to use this tool versus alternatives like 'query_layer'. It provides no exclusion criteria or prerequisites. Usage is implied through the description of the tool's purpose, but explicit guidance is missing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds value by detailing the returned fields and clarifying that it's scoped to the caller's active subscriptions. 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 two sentences: first states purpose and output fields, second provides usage guidance. No unnecessary words. Highly efficient.

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

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

Given no output schema, the description compensates by listing return fields. It also explains the use case. Could mention if there is pagination or ordering, but for a simple list, this is sufficient.

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

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

Schema coverage is 100% for the single parameter include_inactive, and its description is adequate. The tool description does not repeat the parameter details, which is acceptable since the schema already handles it. 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 lists the caller's active subscriptions and specifies return fields. It distinguishes itself from sibling tools subscribe and unsubscribe by providing context on when to use it (review before adding more or to find an id to cancel).

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

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

The description explicitly guides the agent to use this tool before adding more subscriptions or to get an ID for cancellation. While it doesn't explicitly state when not to use it, the context is clear enough for a simple listing 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?

The description reveals important behavioral traits beyond the annotations: rate-limited to 5 per identifier per day, free usage, and that the team reads digests daily and signal affects roadmap. 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 concise and well-structured: it starts with the core purpose, then gives usage conditions, then provides tips and constraints. 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?

Despite no output schema, the description covers all essential aspects: purpose, usage scenarios, constraints (rate-limiting, quota-free), and expected output (team reads digests). It 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?

The description adds meaning beyond the schema by explaining the enum values in context ('bug = something broke...') and advising on specificity ('Be specific (which tool, what error, what data was missing)'). Schema coverage is 100%, but the description enriches understanding.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource ('Pipeworx team'), and distinguishes it from all sibling tools, none of which are feedback-related.

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 lists when to use the tool: for bugs, feature requests, data gaps, praise, or other. It also provides clear guidance on what not to do (not paste the end-user's prompt) and how to describe issues (in terms of Pipeworx tools/packs).

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

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

Beyond annotations (readOnlyHint, etc.), the description adds valuable context: the tool is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h. This provides transparency about data origin and freshness, complementing the annotations perfectly.

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

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

The description is well-structured with bullet points for use cases and clear delineation of behavior. It is slightly longer than absolutely necessary but every sentence adds value, justifying the length.

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

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

Given no output schema, the description explains what is returned (top tools, packs, call volume) and provides context about data derivation and caching. For a simple trending tool, this is fully sufficient and leaves no ambiguity.

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

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

With 100% schema description coverage and only one parameter, the description adds important semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This explains the effect of different choices beyond the schema enum.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window', using specific verbs and resources. It distinguishes itself from sibling tools by focusing on trending popularity rather than direct queries or tool discovery.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming popular tools, seeing alignment) and explains the window parameter's effect. However, it does not explicitly state when not to use this tool or provide alternatives for different needs.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate a safe, non-destructive tool. The description far exceeds expectations by detailing the algorithms (monotonicity, partition check), semantic anchor (Jaccard similarity), partition filter (placeholder slugs), and fill check (live CLOB depth). No contradictions with annotations.

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

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

The description is long but well-structured, with clear sections for each mode and technical details. It is informative without being wasteful, though could be slightly more concise in some technical explanations.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure: 'opportunities[]' with fields like gap_pp, suggested_trade, and partition_check details. It also covers edge cases (skipped_low_similarity, placeholder filter) and the fill check, making it complete for agent understanding.

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

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

Schema coverage is 100% with descriptions for both 'event' and 'topic' parameters. The description adds significant value by explaining the modes, providing example slugs and seed questions, and detailing the behavior of each parameter beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the resource (Polymarket arbitrage) and action (find opportunities), distinguishing it from sibling tools like polymarket_fill_risk and polymarket_edges.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, 'event' for specific market, 'topic' for cross-event scanning. It also directs users to 'polymarket_fill_risk' for custom sizing, clearly indicating when not to use this tool.

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

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

Extensive disclosure of models (crypto_price, news_momentum, partition_overround, concentrated_longshot), response structure by_segment, edge calculations, caching policy, and filter knobs. 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?

Well-structured with clear sections (purpose, model families, response fields, filter knobs, caching). Front-loaded with main intent. Slightly long but information-dense and 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?

Covers all relevant details: models, edge computation, response schema, filter mechanics, caching, diagnostics for empty segments, and special handling of Fed bets. No output schema needed as description explains response structure.

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

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

Schema coverage is 100% (9 parameters described). Description adds rationale and usage guidance for all parameters (e.g., slippage_pp explains Polymarket fees, min_liquidity explains thin-book risk). Adds value beyond schema.

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

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

Clear verb 'scan and return' with specific resource 'Polymarket markets where Pipeworx data disagrees with market price'. Distinct from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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 use case: 'what should I bet on today' and discovering opportunities without paging. Lacks explicit when-not-to-use or direct comparison to siblings, but context 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, idempotentHint, and openWorldHint, so the tool is safe. The description adds significant behavioral context: data bounds (60-day TTL), dependency on snapshot availability, non-intraday decay computation, and the meaning of sign in edge_pp_net. 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 relatively long but well-structured, front-loading the core purpose and then detailing response fields. It could be slightly more concise, but every sentence adds necessary information.

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

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

Given the complexity (time-series telemetry) and no output schema, the description fully explains the response (tracked, expired, snapshot_dates) and their semantics. It also covers limitations (60-day TTL, snapshot gaps). This is complete for agent understanding.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by specifying defaults (14 days, 1wk), clamping range (2-30), and explaining 'window' as snapshot family. It provides meaningful context beyond the schema.

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

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

The description clearly states it provides edge persistence and decay telemetry from snapshots, answering a specific question about edge duration and trend. It distinguishes from the sibling polymarket_edges tool by focusing on historical analysis rather than just current edges.

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

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

The description implies when to use this tool (e.g., to distinguish between new and old edges) and explains the response structure. It does not explicitly state when not to use it or compare to alternatives beyond the implied contrast with polymarket_edges, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds significant behavioral context: it walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, and verdict, and explains forced_directional_risk for baskets. No contradiction with annotations.

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

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

The description is relatively long but well-structured with sections for REQUIRES, SINGLE-MARKET, BASKET, and a usage note. Every sentence adds value, no fluff.

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

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

The description details return values for both modes, including edge cases like thin_legs and forced_directional_risk. It also mentions constraints (size_usd clamp). Given the tool's complexity (two modes), it is quite complete without an 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 description coverage is 100%, but the description adds meaning: it explains the difference between using market vs event, default side behavior for both modes, and interpretation of size_usd. This goes beyond the schema's descriptions.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes and specifies it is for use before acting on arbitrage signals or trades above ~$500, differentiating it from siblings like polymarket_arbitrage.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why: theoretical overround on thin books is not capturable, and partial basket fills convert an arb into unhedged directional position. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations declare readOnly and idempotent, which are consistent. The description adds extensive behavioral detail: compatibility_warning conditions (bet shape non-equivalence, semantic mismatch), temporal alignment checking, skipped counters for metric type mismatches. It sets clear expectations about output structure and edge cases.

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-organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose. While verbose, it earns its length given the tool's complexity and the need to warn about edge cases. A slightly tighter structure could improve conciseness.

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

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

Despite no output schema, the description thoroughly explains the response structure (leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It also covers error conditions like unmatched outcomes and temporal misalignment. For a tool with 3 parameters, this is exceptionally complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the two modes: topic as a shortcut with 10 pre-mapped macros, and explicit params as overrides. It clarifies the relationship between topic and explicit parameters, which is not evident from the schema alone.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison, and details two modes (topic shortcuts and explicit pairings).

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 specifies when to use the topic mode vs explicit parameters, and provides strong negative guidance: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests — most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It also explains when spreads are meaningless (e.g., temporal misalignment).

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

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

Description adds behavioral details (returns attribute rows and geometry) beyond the annotations, which already mark it as read-only and idempotent. No contradiction.

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

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

Two sentences with no wasted words. Front-loaded with purpose, followed by a practical example.

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?

Adequate for a read-only query tool with full schema coverage, but lacks details on response format or error handling (no output schema). Could be more complete for a complex tool.

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

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

All six parameters are described in the input schema (100% coverage). Description adds example values and defaults but does not provide significant new meaning beyond the schema.

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

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

Description clearly states the tool queries an ArcGIS Feature/Map Service layer by URL, with SQL-like parameters. It links to search_datasets as a precursor, distinguishing it from sibling tools like layer_info.

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 provides example usage (where='1=1', out_fields='*') and suggests scenario 'from search_datasets', but does not explicitly state when not to use or compare to siblings.

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

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

Annotations already cover safety (read-only, idempotent). Description adds minor context about scoping and listing keys, but no additional behavioral traits 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?

Three sentences, front-loaded with primary action, 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?

Adequate for a simple retrieval tool with one optional parameter. Missing details on return format and error cases, but not critical.

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 parameter meaning. Description reinforces but adds no new semantics 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?

Description clearly states the tool retrieves a stored value or lists all keys, differentiating it from siblings remember and forget.

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

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

Explicitly describes when to use: to look up previously stored context. Implied alternatives through sibling tool names, but no explicit when-not.

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

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

The description discloses the mark_read parameter as a mutation that flags events as read, which contradicts the readOnlyHint annotation (true). According to the scoring rules, a contradiction warrants a score of 1.

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 (two sentences plus a brief parameter note) and front-loaded with the core purpose. Every sentence provides valuable information without redundancy.

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

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

Despite no output schema, the description details what each event carries (source, citation_uri, raw payload). It covers all parameters, includes a real-world use case (mark_read), and mentions an alternative access method. For a list-style tool, this 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 coverage is 100%, and the description adds meaningful context beyond the schema, such as example filter values ('sec_8k'), the behavior of mark_read ('flag returned events read so the next call only shows newer ones'), and the effect of unread_only. This adds significant value.

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

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

The description clearly states the tool 'Pull fired events from your subscription feed', specifying the verb (pull), resource (events), and scope (subscription feed). It distinguishes from sibling tools like list_subscriptions (which lists subscriptions, not events) and recent_changes (which likely deals with changes to 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 provides usage context like filtering by type and since timestamp, and mentions that polling works fine. It also notes an alternative HTTP endpoint. However, it does not explicitly compare this tool to siblings or state when to use alternatives like query_layer or search_within.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details the tool's fan-out to multiple sources, fallback logic, API sunset handling, and return structure (changes[], total_changes, citation URIs). No contradiction with annotations.

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

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

The description is a single paragraph with no wasted words, front-loaded with examples. It could benefit from slight structuring (e.g., bullet points for sources or parameters), but remains efficient and readable.

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

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

Given the tool's complexity (multiple data sources, fallback, parameter formats, return structure), the description covers all necessary aspects. No output schema exists, but the description explains the output structure. Differentiates from sibling tool 'entity_profile' adequately.

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%, baseline 3. The description adds significant value by explaining acceptable formats for 'since' (ISO date or relative shorthand with examples like '7d', '30d') and clarifying 'value' can be ticker or CIK, 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 explicitly states the tool provides a change feed for a company, listing specific sources (SEC, GDELT/GNews, USPTO) and using verbs like 'fans out'. It differentiates from sibling tool 'entity_profile' by contrasting dynamic vs static data.

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

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

The description provides multiple example queries ('What's new with X', 'latest on Y') and explicitly tells when to use the alternative tool 'entity_profile'. It also explains the fallback behavior between GDELT and GNews, giving clear context for usage.

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

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

Annotations provide idempotentHint=true, destructiveHint=false, and readOnlyHint=false; the description adds significant context: key-value scoping by identifier, persistence duration (24 hours for anonymous, persistent for authenticated), and behavioral pairing with recall and forget. No contradiction with annotations.

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

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

The description is a single paragraph with clear front-loading of purpose. It is efficient but slightly verbose in the middle, though every sentence adds value. 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 and simple input, the description adequately covers storage behavior, scoping, and persistence. It could mention idempotency (update vs overwrite) but tags imply idempotent. Paired with sibling tools, 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 coverage is 100% with descriptions for both parameters. The description adds value by providing example formats (e.g., 'subject_property', 'target_ticker') and explaining the intent, but the schema already covers meaning adequately.

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 ('save data') and resource ('key-value pair'), provides concrete examples (resolved ticker, target address), and clearly distinguishes from sibling tools (recall, forget) mentioned by name.

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

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

The description explicitly states when to use ('discover something worth carrying forward') and pairs with recall/forget, but does not explicitly state when not to use or provide alternatives beyond those three tools.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds that 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups', revealing internal complexity and efficiency, which exceeds annotation coverage.

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

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

The description is well-structured, starting with examples, then purpose, then type details. Every sentence adds value, though it could be slightly more concise without losing clarity. Overall very 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 lacking an output schema, the description fully explains return values for each type (ticker, CIK, RxCUI, etc.). Both parameters are thoroughly described. For a lookup tool with 2 required params, this is complete and self-sufficient.

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 rich semantics: e.g., for 'company' type, it details returns (ticker, CIK, company_name, citation URI) and input flexibility (ticker, CIK, or name with auto-disambiguation). For 'drug' type, similar detail. This goes well beyond the schema's minimal descriptions.

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

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

Description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific examples like 'What's the ticker for…' and 'find the CIK for…'. It explicitly distinguishes between supported entity types (company, drug) and their outputs, making the purpose unmistakable.

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

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

Explicitly advises 'Use FIRST whenever you have a name but need an ID', providing clear usage context. It doesn't explicitly state when not to use or list alternative tools, but given the sibling tools, the guidance 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?

Discloses that it probes each entity with ai_visibility_check, ranks results, and returns score, confidence, signal density. Annotations already confirm read-only and idempotent; description adds procedural details beyond annotations.

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

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

Two sentences with no waste. First sentence states purpose and method; second sentence adds use case and output summary. Well front-loaded.

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

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

Given no output schema, description explicitly states return format (ranked list with score, confidence, signal density). Covers input constraints (2-8 entities) and optional parameters. Complete for the tool's complexity.

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

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

Schema coverage is 100%, and description adds meaningful context: first entity is 'subject', model options with API key requirement, and shared context disambiguation. Enhances understanding beyond schema.

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

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

Description clearly states it compares AI visibility across multiple entities, using a specific verb (compare) and resource (AI presence). It distinguishes from sibling ai_visibility_check by emphasizing side-by-side comparison and ranking.

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 a concrete use case ('competitive AI-marketing audits') and an example question. Does not explicitly state when not to use, but context is clear. Could mention alternatives like ai_visibility_check for single entities.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. Description adds crucial details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed list on timeout.

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?

Packed with value but first sentence is lengthy. Every sentence earns its place, but could be slightly more concise. Still well-structured.

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

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

Despite no output schema, description lists all return fields and covers edge cases (scoped packages, version defaults, partial failures, timeout behavior). Very 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 has 100% coverage. Description adds that package accepts scoped packages, version defaults to latest, and enumerates return fields (summary block, advisory details, links, alternative versions).

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?

Describes a composite check for npm package evaluation covering license, security, version history, and bundle size. Distinct from sibling tools by combining multiple data sources and being npm-specific.

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

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

Explicitly states when to use: when agent asks about safety, popularity, size, or cost of adding a package. Also notes NPM only in v1 and directs alternative ecosystems to use deps.dev directly.

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 specific context about the domain (Tempe GIS) and the structure of results (including record_count, url). It doesn't mention any hidden behavioral traits like pagination or rate limits, but the annotations suffice for safety.

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

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

The description is two sentences: first states the core action and scope, second lists outputs and directs to sibling tools. No extraneous information, efficiently front-loaded with key details.

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 search tool with three well-described parameters and clear annotations, the description fully covers purpose, outputs, and follow-up actions. Despite lacking an output schema, the description enumerates return fields, making it complete 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?

The input schema covers all three parameters with descriptions, and the description does not add significant new semantic meaning beyond reiterating 'by keyword' and 'City of Tempe'. Without new parameter insight, the score defaults to baseline 3.

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

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

The description clearly states the tool searches City of Tempe GIS datasets by keyword, lists return fields (name, summary, etc.), and explicitly references sibling tools (query_layer, layer_info) for next steps, distinguishing it from 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?

The description provides explicit guidance on when to use this tool (to search datasets and get a Feature Service URL) and what to do next (pass URL to query_layer or layer_info), offering clear context for usage.

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

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

Adds key technical details beyond annotations: embedding model (BGE-base-en), metric (cosine), chunking (500-char overlapping windows), cap (200K chars with truncation flag), and output structure (passages with offsets). 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?

Single paragraph with front-loaded purpose, then usage, then technical details. Every sentence adds value, though slightly verbose for the complexity level.

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 aspects: input (text, query, limit), behavior (embeddings, chunking, cap), output (passages with offsets and similarity), and usage scenario. No output schema needed as description explains return structure.

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

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

Schema coverage is 100%, so baseline 3. Description adds clarifying examples for query parameter and reaffirms text limit, providing extra context that aids 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 'semantic search INSIDE a fetched record,' specifying verb and resource. Distinguishes from siblings by emphasizing internal search vs. broader search tools, and pairs with ask_pipeworx_grounded for grounding.

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

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

Explicit guidance: 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. Also notes cap of 200K chars and truncation behavior.

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

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

Discloses important behaviors beyond annotations: authorization requirements, type-specific filters, delivery channel details (e.g., SMS cap, webhook auto-disable). The annotation idempotentHint=true is contradicted by the description implying each call creates a new subscription id, but the contradiction is minor given the overall transparency.

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: purpose, prerequisite, types, delivery. Every sentence adds value; no fluff. Efficiently packs extensive information.

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

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

Given the complexity (3 params, nested objects, multiple types) and lack of output schema, the description fully explains return value, limits, and all necessary context. No gaps.

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

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

Schema coverage is 100% (baseline 3), but description adds substantial meaning: parameter examples, required vs optional, formatting (E.164 for SMS), and type-specific details (e.g., items codes for sec_8k). Goes well beyond the schema.

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

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

The description starts with a clear verb+resource: 'Create a proactive monitoring subscription' and specifies the return value ('Returns the new subscription id'). It distinctly differentiates from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation.

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

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

Explicitly states prerequisite (Pipeworx OAuth account) and provides rich context for each subscription type and delivery channel. However, it does not explicitly mention when not to use or name alternatives (e.g., list_subscriptions for listing). Clear context but no 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?

Description adds context about returning category-bucketed examples and being an onboarding entry point, but annotations already cover readOnly, openWorld, idempotent, and non-destructive behavior. No contradiction. The description does not add significant new behavioral traits beyond what annotations provide.

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

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

Description is front-loaded with aliases and purpose, but it is somewhat lengthy. It includes a parenthetical list of topics and an explanation of return format. Most sentences earn their place, but could be slightly more concise.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description adequately covers what it returns and how to use it. It explains the onboarding context and relationship to other tools. Slightly more detail on the structure of the returned examples would improve completeness.

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

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

Schema has 100% coverage with a single optional topic parameter described as list of focus areas. The description expands on this by listing all valid topics and explaining the effect of omitting vs. providing a topic, adding meaning beyond the schema alone.

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

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

Description clearly states it returns category-bucketed example questions with tool+argument shapes, positioning it as an onboarding entry point. It includes aliases like 'what can I ask Pipeworx?' and lists specific question types, distinguishing it from siblings like ask_pipeworx and discover_tools.

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

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

Explicitly advises to use this tool FIRST when unfamiliar with Pipeworx's capabilities. Explains that calling with no arguments gives a full spread, while passing a topic focuses on a specific area. This helps the agent decide when to use this tool vs. alternatives.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses that the row is deactivated rather than deleted, and that historical events remain available via recent_alerts. It also states ownership enforcement, adding significant behavioral context.

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

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

Two sentences, each earning its place: first states the action and constraint, second clarifies the soft-delete behavior. No superfluous text, front-loaded with 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 simple tool with one parameter and no output schema, the description covers action, constraint, side effects, and link to related functionality (recent_alerts), making it fully self-contained.

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

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

Schema coverage is 100% with one parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description does not add further meaning beyond the schema, so baseline score applies.

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

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

The description clearly states 'Cancel a subscription by id', specifying the verb and resource. It distinguishes from siblings by noting ownership enforcement and the nature of the action ('deactivated not deleted'), which contrasts with subscribe and list_subscriptions.

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

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

The description provides clear context for when to use the tool (to cancel a subscription) and a key constraint (only own subscriptions). It implies not to use for listing or subscribing, but does not explicitly mention 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which indicate safe, idempotent behavior. The description adds context about return values (verdict types, structured form, citation, delta) and limitation to company-financial claims, but does not contradict annotations.

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

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

The description is a single paragraph that packs useful information (examples, scope, return types, efficiency claim) without being verbose. It is front-loaded with the purpose and examples, though a bit dense.

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

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

Given the tool has one parameter and no output schema, the description covers the input format, supported domain, return components, and even notes the efficiency benefit. It could mention error cases or limitations further, but is fairly complete.

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

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

The single parameter 'claim' has 100% schema description coverage. The description adds value by providing examples of natural-language claims and explaining how the tool processes them, going beyond the schema's generic description.

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

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

The description clearly states the tool's purpose: verifying natural-language claims against authoritative sources. It provides specific verbs ('fact check', 'verify'), a resource scope (company-financial claims via SEC EDGAR + XBRL), and distinguishes itself from siblings by claiming it replaces 4-6 sequential calls.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the scope ('v1 supports company-financial claims'). It implies when not to use (non-financial claims) but does not explicitly mention alternative tools or exclusions.

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