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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description is consistent with that, adding that it aggregates several data categories into one call. It does not mention caching or freshness, but the safety profile is already covered by annotations.

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

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

The description is compact and front-loaded: a one-sentence value proposition, per-argument definitions, and a single example. It avoids restating schema fields or annotations and every sentence contributes to correct selection and invocation.

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 output schema and read-only/idempotent annotations, the description sufficiently explains what the tool aggregates, why it exists, and how to call it. An explicit sibling-routing condition would be a small enhancement, but nothing critical 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 0%, so the Args block carries the documentation burden. It defines method as an HTTP verb with the allowed values, path with a concrete example, and includes a full invocation example, though it does not add constraints 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?

States it produces a one-shot endpoint profile composed of schema, error codes, code examples, and release-note mentions. This makes it clearly distinguishable from the granular get/list sibling tools such as get_vipmp_schema, list_vipmp_error_codes, and get_vipmp_code_examples.

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 frames the tool as the alternative to chaining four separate tool invocations, which gives a clear when-to-use rationale. It stops short of naming the specific sibling tools or stating when a narrower sibling should be used instead.

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

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

Beyond the safe readOnly/idempotent annotations, the description discloses the body fallback behavior: supplied bodies are used as-is, omitted bodies on POST/PATCH/PUT are built from the schema with dummy values, and the snippet shows the minimum valid shape. It also makes language behavior explicit. No contradictions with 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?

Well-structured: purpose first, then usage context, then inline parameter docs, then a compact example. No filler; the extra sentences all add actionable 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 3-parameter code-generation tool with an output schema, the description covers all inputs, the placeholder-body behavior, and language options. It doesn't discuss invalid endpoint handling or authentication, but those are edge concerns given the clear scope.

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

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

Even though schema description coverage is 0%, every parameter is explained with format or behavior: endpoint as 'METHOD /path', body_json with its fallback rule, and language with the full enum list and default. The example demonstrates a valid invocation.

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?

Opening sentence names a specific verb ('Emit') and resource ('runnable code snippet for a VIPMP endpoint'), and the example anchors it to a concrete call like 'POST /v3/customers'. This makes it easy to distinguish from documentation/validation siblings such as get_vipmp_code_examples or describe_vipmp_endpoint.

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 'Useful for "give me a starting point for calling POST /v3/customers"' line gives a clear situation for using the tool. It doesn't explicitly list when-not-to-use or name alternatives, so it stops short of full routing guidance.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral detail by explaining that extraction targets `<code>` elements and that language filtering matches the `language-<x>` class.

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

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

The description is compact and well-structured: a one-sentence overview followed by concise per-argument details. There is no fluff or unnecessary repetition of schema-only 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?

With only two parameters, one required, plus annotations and an output schema, the description covers what is needed to invoke the tool correctly: path format, language semantics, and filtering behavior. 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 0%, but the description fully compensates: docs_path gets a concrete path example, and language gets optionality, allowed value examples, and the underlying matching mechanism. This adds real meaning beyond the bare schema.

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

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

The description states a specific verb ('Extract') and resource ('code examples') from a 'specific docs page', making it clear what the tool returns. This resource focus distinguishes it from siblings like get_vipmp_page, list_vipmp_docs, and search_vipmp_docs even without naming them.

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

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

It gives clear usage context: call with a known docs_path to retrieve code examples and optionally narrow by language. It does not explicitly provide exclusions or name alternative tools for full-page retrieval, so it stops short of the top tier.

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 safety profile is well covered. The description adds that it fetches 'full content' and relies on a path, but it does not describe invalid-path behavior, caching effects, or response characteristics. For a read-only retrieval tool this is acceptable but not rich.

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

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

The description is compact: one clear opening sentence, a short Args block, and a practical example. Every sentence earns its place, and the most important information is front-loaded.

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

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

With a single parameter, an output schema, and annotations covering the operational safety profile, the description provides everything an agent needs to invoke the tool correctly. It also explains how to discover valid paths, which addresses the main practical uncertainty.

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 has 0% description coverage for the only parameter, so the description must compensate. It does so by naming the parameter's purpose and giving a concrete example path, while also directing agents to list/search tools for valid values. This is sufficient for a single parameter, though it relies on an example rather than stricter format rules.

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 ('Fetch') and a specific resource ('full content of a specific Adobe VIP Marketplace documentation page'), which clearly distinguishes it from list/search siblings and from content-specific siblings like get_vipmp_schema or get_vipmp_code_examples. The title reinforces the same message without ambiguity.

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

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

The description explicitly instructs agents to use list_vipmp_docs() or search_vipmp_docs() to find valid paths, which provides clear prerequisite guidance. It does not mention when not to use this tool, but the sibling names and the first sentence make the intended use case fairly obvious.

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 non-destructive behavior. The description adds behavioral value beyond those annotations by disclosing case-insensitive substring matching, the data source ("Resources & Fields reference page"), and the behavior of omitting resource_name ("get every documented resource"). There is no contradiction with 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 compact and well-organized: one sentence for purpose and source, then a short Args block. Every sentence earns its place, and the main purpose is front-loaded with no unnecessary detail.

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

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

For a single-optional-parameter lookup tool with an output schema and rich read-only/idempotent annotations, the description covers purpose, source, filtering behavior, examples, and default behavior. Nothing needed to call it correctly is missing.

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

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

The input schema only gives the type and default, so the description carries the full burden. It fully compensates by explaining that resource_name is optional, matches case-insensitively as a substring, gives concrete examples ("customer", "linkedMembership"), and states what happens when omitted. This is exactly the meaning an agent needs beyond the raw schema.

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

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

The description uses a specific verb and resource: "Return structured field schemas (name, type, required, description) for VIPMP resources." It clearly identifies the output and the source page, and the resource-schema focus distinguishes it from docs/endpoint/cache siblings in practice. It stops short of an explicit "use this instead of X" statement, so it is clear but lacks explicit sibling differentiation.

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

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

The description provides clear context: use this tool when VIPMP resource field schemas are needed, and the source is the Resources & Fields reference page. It also explains the omit-to-get-everything behavior. However, it does not explicitly state when to prefer a sibling tool or call out exclusions, so the usage guidance is implied rather than fully explicit.

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

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

Adds substantial behavioral detail beyond the annotations: case-insensitive and punctuation-tolerant matching, verbatim markdown return, and graceful placeholder behavior for empty or missing topics. The readOnly and idempotent hints are consistent with the description, with no contradiction.

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

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

The description is front-loaded with the core purpose, then adds matching semantics, argument documentation, and return behavior. Every sentence earns its place without redundant fluff or restating the schema.

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

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

Covers purpose, parameter semantics, matching behavior, return format, edge cases, and a pointer to the topic-listing sibling. For a one-parameter read-only tool, 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 coverage is 0%, so the description fully compensates by defining `topic`, giving concrete examples like 'customer lifecycle', 'ordering flow', '3YC', and explaining matching semantics. It also routes to `list_vipmp_tip_topics` for valid topic discovery.

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?

States a specific verb and resource: 'Return SoftwareOne-authored operational tips for topic' — naming them as rules, gotchas, and field notes that complement Adobe's reference docs. This clearly separates it from sibling tools like list_vipmp_tip_topics or get_vipmp_page.

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?

Offers clear usage context: use it to fetch operational tips for a topic, and use `list_vipmp_tip_topics` to discover available topics. It does not explicitly state when to prefer other siblings like search_vipmp_docs, but the purpose is specific enough that an agent can select it correctly.

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 safety profile is covered. The description adds that the result is the full sitemap and can be used for browsing or path discovery, but says little about output size, pagination, or other operational behavior. This is adequate but not rich.

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

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

The description is two sentences with no filler. The key action (returning the full sitemap) is front-loaded, and the follow-up sentence adds immediate practical use.

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?

This is a zero-parameter, read-only tool with an output schema, so the description fully covers what an agent needs to select and invoke it correctly. The purpose and use cases are stated clearly, and no additional prerequisites or edge-case warnings are needed.

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

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

The tool has zero parameters and the schema has 100% coverage, so parameter documentation is unnecessary. The baseline of 4 applies because no parameter semantics are needed.

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 the full sitemap of Adobe VIP Marketplace API documentation, which is a specific resource and action. This distinguishes it from search_vipmp_docs, get_vipmp_page, and list_vipmp_endpoints by emphasizing the complete sitemap rather than individual pages or endpoint details.

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

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

The description provides a clear use case: browse all topics or find exact page paths. It does not explicitly name alternatives or say when not to use this tool, but the stated purpose is enough to guide selection among the 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 signal read-only, idempotent, non-destructive behavior. The description adds valuable beyond-annotation context: it discloses the pre-built index fast path, the fallback to live extraction with realistic latency estimates (~30s cold, ~5s warm), and how to refresh the local index. This is rich, honest behavioral detail.

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 tightly written sentences, each earning its place: outcome and output format, performance and fallback behavior, and cache refresh guidance. The most important information is front-loaded, with no redundant phrasing.

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 zero-parameter tool with an output schema and strong annotations, the description covers everything needed for correct selection and invocation: what is returned, how it is sourced, expected latency, fallback behavior, and how to improve freshness. No critical information is missing.

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

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

The tool accepts zero parameters, so there are no parameter semantics to document. The schema is empty and description coverage is effectively 100%, making this baseline appropriate; the description's scope language further clarifies what the parameterless call does.

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

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

The description states a specific action and resource: extract every HTTP endpoint (method + path) across the VIPMP docs. It also specifies the return format, a Markdown table grouped by resource area, which clearly distinguishes it from sibling tools like describe_vipmp_endpoint or list_vipmp_error_codes.

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 scope 'every HTTP endpoint documented across the whole VIPMP docs' provides clear context for when to use this tool. It doesn't explicitly name alternatives or exclusion conditions, but the phrase 'whole VIPMP docs' and the mention of calling rebuild_vipmp_index to refresh imply the appropriate usage context.

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

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

Annotations already establish read-only, open-world, idempotent, non-destructive behavior, and the description adds valuable behavioral context: the tool is served from a pre-built index with fallback to live extraction, and it points to rebuild_vipmp_index for refreshing. No contradiction with annotations exists.

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

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

Every sentence earns its place: the purpose and data scope, the parameter semantics, and the caching/refresh behavior. The most important information is front-loaded, and there is no filler or repetition of schema fields.

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

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

For a single optional-parameter read tool with an output schema, annotations, and clear behavioral notes, the description is complete. It explains what is extracted, how filtering works, and the index/fallback behavior; nothing an agent needs to invoke it correctly is missing.

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

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

The input schema provides no descriptive text beyond a nullable string with a default of null, so the description carries the full burden. It fully defines query as an optional case-insensitive substring filter that matches against code, reason, or endpoint, which is exactly what an agent needs.

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

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

The description opens with a specific action and resource: 'Extract every error code documented across VIPMP docs.' It enumerates the exact kinds of data returned (numeric codes like 1117 and symbolic reason codes like INVALID_LM_MIGRATION_LEVEL), which clearly differentiates it from sibling tools like list_vipmp_status_codes or list_vipmp_docs.

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 query parameter is explained with its match semantics ('matches against code, reason, or endpoint' and 'case-insensitive'), giving concrete guidance on how to use the tool. It does not explicitly name alternative tools or exclusion conditions, so it stops short of full when-vs-alternatives guidance.

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

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

Annotations already mark this read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: responses are served from a pre-built daily-refreshed index for millisecond latency, API and Sandbox changes are tracked separately, and `since` excludes undated 'earlier' entries. No contradiction with annotations.

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

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

The description is long but tightly organized: purpose first, return-structure summary, then Args and Examples. Every sentence adds value — the latency note, the separate-streams note, and the example calls all earn their place. The structure makes it easy for an 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?

For a read-only listing tool with an output schema present, this description covers all the ground: what is returned, how data is sourced, how filtering behaves, parameter semantics, and common usage patterns. Nothing an agent needs to select and call this tool correctly 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 0%, so the description carries the full burden for parameter meaning — and it delivers. Each of the three parameters gets precise semantics: `since` includes format, behavior, and example; `section` enumerates all four values with meanings; `limit` gets its default. This far exceeds the bare 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 opens with 'Return structured VIPMP release notes' — a specific verb, resource, and clearly stated value proposition for developers tracking API changes. It also distinguishes this tool from the many sibling doc tools by explicitly scoping it to release notes and mentioning both API and Sandbox streams.

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

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

The description gives clear context for when to use the tool ('developers tracking API changes'), explains what each section filter means, and provides practical examples for common use cases. It doesn't explicitly name sibling alternatives or say when not to use it, which keeps it just short of a 5.

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 (readOnly, openWorld, idempotent, non-destructive), the description discloses that the tool is 'served from the pre-built index when available, falling back to live extraction if not' and that rebuild_vipmp_index refreshes the index. This adds meaningful operational behavior that the annotations alone do not convey.

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

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

The description is compact and every sentence adds value: purpose/scope, distinction from error codes, parameter semantics, and index behavior are all covered without redundancy. The Args section is cleanly separated and the whole definition reads efficiently.

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

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

The tool has a single optional parameter, rich annotations, an output schema, and a clearlist-style behavior; the description covers purpose, parameter semantics, sibling differentiation, and refresh behavior. Nothing an agent needs to invoke it correctly is missing.

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

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

The input schema provides no property description beyond title/default, so the description carries full weight for the query parameter. It clearly states query is optional, a substring filter, case-insensitive, and matches against code, description, or applicable resources — fully compensating for the 0% schema description coverage.

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

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

The description uses a specific verb ('Extract') and resource ('resource status code documented across VIPMP docs'), and further pinpoints the scope with the numeric range 1000-1026. It explicitly contrasts these with 'request-failure error codes surfaced by list_vipmp_error_codes', clearly distinguishing it from the nearest sibling.

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

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

The description says these are lifecycle status codes 'as opposed to the request-failure error codes surfaced by list_vipmp_error_codes', which is an explicit when-not-to-use and alternative pointer. It also notes when the built-in index is used, when live extraction happens, and when to call rebuild_vipmp_index, giving practical invocation context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by explaining that entries map to H2 sections in the tips file, which tells the agent how the list relates to the file structure and the subsequent call.

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, with the primary purpose front-loaded and each subsequent sentence adding meaningful navigation or usage context. No filler or repetition of schema/annotation data.

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?

This is a simple, parameterless listing tool with rich annotations and an output schema. The description fully covers what the tool returns, how entries map to the tips file, and how the tool fits into the workflow with `get_vipmp_tips`.

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 tool has zero parameters, so there is nothing for the description to clarify. Schema coverage is effectively 100% since the input schema is empty, and the parameter-less baseline of 4 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 states a specific verb and resource: "Return the list of topics for which SoftwareOne tips are available." It further clarifies that each entry maps to an H2 section and is linked to `get_vipmp_tips(topic)`, distinguishing it from sibling listing tools like `list_vipmp_docs`.

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 frames this as a discovery call — "what tips do you have?" — before narrowing to a specific topic, and directs the agent to `get_vipmp_tips(topic)` as the follow-up. This is clear when-to-use guidance with an explicit alternative.

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

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

The description discloses the actual side effect—writing to a specific cache file path—and the performance profile (60s cold, 15-20s warm). This goes beyond the annotations by explaining why readOnlyHint is false and what the idempotent rebuild actually does.

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

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

The description is front-loaded with the core action, followed by tightly scoped bullets and a timing note. Every sentence earns its place, and the structure makes the when-to-use guidance easy to scan.

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

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

For a zero-parameter tool with an output schema, the description covers what it does, why an agent would run it, how long it takes, and what it modifies. No critical operational detail is missing.

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

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

The tool has zero parameters and 100% schema coverage, so there is no parameter semantics to add. The baseline for a zero-parameter tool is 4; the description appropriately contains no irrelevant parameter details.

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 and resource: rebuild the pre-extracted index of endpoints, error codes, status codes, and schemas by walking the sitemap. It clearly identifies what the tool produces and where it saves the result, distinguishing it from related sitemap and cache tools.

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

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

The 'Run this if' section explicitly lists the three concrete conditions for using the tool, including stale structured data, after refreshing the sitemap, and when the baseline index is outdated. It gives clear decision criteria with no ambiguity.

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

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

Beyond the annotations, the description discloses meaningful behavior: it fetches external Adobe content, merges hand-curated tags, persists to sitemap.json, affects future server startups, takes about 30 seconds over ~80 pages, and is safe to run repeatedly. These details align with the annotations (idempotent, not read-only, not destructive) without contradicting them.

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

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

The description is compact and well-structured: the lead sentence captures the core behavior, the bullet list makes usage conditions scannable, and each sentence adds distinct value such as duration, side effects, or safety. There is no filler or redundant restating of the tool name.

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 zero-argument maintenance tool, the description covers why to run it, what it does, how long it takes, what it affects, and that it is safe to repeat. Since an output schema exists and the annotations are rich, the description does not need to explain return values or safety annotations.

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 tool has zero parameters and 100% schema coverage, so there are no undocumented arguments for the description to clarify. The description still explains the implicit inputs it relies on (Adobe's published sitemap and hand-curated search tags), which is useful context.

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

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

The description states a specific operation ('Rebuild the sitemap'), a concrete source (Adobe's published /sitemap.xml), and a clear outcome (persisting to sitemap.json so future server startups use the refreshed list). It also names the actual processing steps, making it easy to distinguish from sibling tools like warm_vipmp_cache or rebuild_vipmp_index.

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

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

The description gives explicit 'Run this if' bullets covering 404s, newly-added pages, and stale sitemaps, which clearly signal when the tool is appropriate. It does not name alternatives or explicitly state when not to run it, but the trigger conditions are concrete enough for an agent to select it correctly.

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

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

The description adds valuable behavioral detail beyond the annotations: it explains the ranking algorithm (title/tag matches plus content matches), the dependency on the local cache, and the response style (query-relevant sections rather than a blunt character cutoff). This is genuinely transparent about how the tool behaves, and it does not contradict the readOnly/openWorld/idempotent annotations.

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

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

The description is well-structured and appropriately sized. It front-loads the core purpose, then adds ranking and return behavior, then documents parameters. Every sentence contributes useful information — from the cache recommendation to the result-shape clarification — with no filler or repetition.

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

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

Given the tool's moderate complexity, the annotations, output schema, and sibling context, the description is complete. It explains how to maximize result quality, what kind of results are returned, and the parameter constraints. There is no missing information an agent would need to decide on and invoke this tool correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It does this well: 'query' is explained as search terms with concrete examples, and 'max_results' is given a default and an upper bound. This adds substantial meaning beyond the raw schema definitions.

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

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

The description states a specific verb ('Search'), a clear resource ('Adobe VIP Marketplace API documentation'), and a method ('by keyword or topic'). It also differentiates the tool from siblings by explaining how results are ranked and what is returned — page titles, paths, and relevant sections — rather than just repeating the tool 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 provides clear context for when to use this tool: search documentation by keyword or topic, with an explicit recommendation to call warm_vipmp_cache once for best results. It does not name sibling tools as alternatives or list exclusion criteria, but the usage context is clear and actionable.

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

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

Beyond the readOnly and idempotent annotations, the description discloses meaningful behavior: it checks types, required-ness, constraints, unknown fields, and deprecated fields, and explicitly states that nested objects are not recursively validated. This gives the agent a clear model of what the tool will and will not do.

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 a clear purpose statement, scope note, argument definitions, and an example. It is detailed without being bloated, and every section adds operational 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 two required parameters, the output schema, and the safety annotations, the description includes everything needed to invoke the tool correctly: purpose, input format, scope limitations, and an example. It even routes the agent to the right sibling for nested validation.

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

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

Schema description coverage is 0%, so the description fully carries the parameter documentation burden. It defines endpoint as 'METHOD /path' with a concrete example, and body_json as the request body as a JSON string, also shown in the example. This is sufficient for correct invocation.

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

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

The description states a specific verb and resource: 'Cross-check a JSON request body against the documented VIPMP schema.' It clearly distinguishes itself from siblings like get_vipmp_schema and generate_vipmp_request by describing validation behavior and explicitly noting its top-level field scope.

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

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

The description gives concrete guidance on when to use the tool and what it does not cover: 'Scope: top-level fields only' and nested objects should be checked via get_vipmp_schema. It also specifies how to format the endpoint argument with 'METHOD /path' and provides an example call.

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

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

Annotations already mark the operation destructive and idempotent. The description adds meaningful scope details: invalidating a single entry vs wiping the entire cache, and the fact that omitting the path clears everything. It does not contradict any annotation and gives enough behavioral framing around the destructive scope.

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

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

The description is compact and front-loaded, with the core behavior stated in the first sentence. The parameter documentation is minimal and directly useful, containing every necessary detail with no filler.

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

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

For a single-parameter cache-clearing tool with destructive and idempotent annotations and an output schema present, the description provides everything needed to invoke it correctly. The two possible behaviors are fully specified, and the output schema removes the need to describe return values.

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 is sparse (single nullable string, 0% coverage), but the description fully compensates. It explains what 'path' means, gives a concrete example, and explicitly states the effect of None (clearing everything). This is exactly the compensation needed for a minimally documented parameter.

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

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

The description clearly states the action ('Clear the docs cache') and the exact two operating modes: invalidate a specific path or wipe the entire cache. This distinguishes it from sibling cache-related tools like warm_vipmp_cache and vipmp_cache_stats without needing to inspect their schemas.

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

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

It gives clear guidance on when to pass a path versus omitting it, which is the main invocation decision. However, it never references sibling tools or explains when clearing is preferable to warming, refreshing, or rebuilding the cache, leaving context-based selection to inference.

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 safety profile is handled. The description adds the useful context that the tool inspects the on-disk cache and reports freshness/TTL, but it does not disclose additional behavioral traits such as cost or staleness of stats themselves; with strong annotations, this is adequate but not rich.

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

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

The description is two sentences, with the core action and output fields front-loaded and the diagnostic use cases in the second sentence. There is no filler, and every clause adds useful 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?

This is a simple, zero-parameter, read-only tool with an output schema and full annotations. The description covers what it returns and why an agent would use it, so an agent has enough context to select and invoke it correctly without further documentation.

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

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

The tool has zero parameters, so the description bears no parameter-documentation burden. The baseline of 4 applies because there are no inputs whose semantics need explanation; the description instead clarifies what the returned statistics will contain.

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

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

The description states a specific verb and resource: 'Return statistics about the on-disk docs cache,' and enumerates the key outputs (entries, fresh/stale split, TTL, cache file path). It is clearly a read-only stats operation and is not likely to be confused with cache-warming or cache-clearing siblings, though it does not name an alternative explicitly.

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

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

It provides explicit use cases: debugging 'why did it return stale content' or checking 'is the cache being used at all.' This tells an agent when to call it, but it does not mention when not to use it or contrast it with warm_vipmp_cache/vipmp_cache_clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by enumerating the specific diagnostic data returned, giving the agent a concrete expectation of what the tool exposes. It does not describe any additional behavioral nuances, but none are needed given the annotations and simple nature of the tool.

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

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

Two sentences, front-loaded with the core purpose and use case, followed by a compact list of the returned fields. Every sentence contributes directly to helping the agent decide to call and interpret the tool. No filler or redundant 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?

For a zero-parameter, read-only diagnostic tool with an output schema and comprehensive annotations, the description covers purpose, use context, and return contents. The agent has all necessary information to correctly select and invoke the tool without 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?

The tool has zero parameters, so the schema already fully covers this dimension (100% coverage trivially). The description does not need to add parameter meaning, and the return-value list provides helpful context. Baseline 4 is appropriate for a zero-parameter tool.

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

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

The description states a specific verb and resource: 'Dump diagnostic info about the running server'. It clearly distinguishes itself from sibling tools focused on docs, cache operations, or endpoints by emphasizing server-wide diagnostics and version information. The explicit output list ('package version, Python version, index age + counts...') further defines its scope.

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

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

Provides explicit use cases: 'useful as the first call when debugging...' and 'what version am I actually on'. This tells the agent when to use the tool, but it does not mention alternatives or explicitly state when not to use it, so it falls short of the highest score.

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 idempotence and non-destructiveness, and the description adds meaningful behavioral details: the ~30 second first-run duration, the near-instant subsequent runs, disk cache + ETag revalidation with 304 responses, and the returned summary. There is no contradiction with 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 compact, front-loaded with the core purpose, and every sentence contributes useful information. Timing, mechanism, and output summary are each given one focused sentence or short paragraph with 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?

For a zero-parameter, non-destructive, idempotent operation with an output schema, the description is complete. It covers purpose, expected duration, behavior on subsequent runs, and the nature of the return value, so an agent has enough to decide when and how to invoke it.

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

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

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to add about parameter meaning. The baseline of 4 is appropriate for a no-parameter tool.

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

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

The description states a specific action ('Pre-fetch every page in the sitemap') and a clear purpose ('so subsequent searches can do content-level matching'), which differentiates it from sibling tools like search or list operations. It is not a tautology and names the resource it acts on.

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 makes clear when to use the tool: before running searches that need content-level matching. It also sets expectations about first-run vs. subsequent-run cost, but it does not explicitly mention alternatives or conditions where this tool should not be used. 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.