GoodBarber

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

Annotations already indicate that the operation is read-only, idempotent, and non-destructive, which lowers the burden on the description. However, the description does not mention what is returned, whether missing ids produce errors, or any other behavioral details, leaving some uncertainty.

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 repeats the same sentence twice and includes an odd 'Guidance:' and '| context: id' fragment. This redundancy and inconsistent formatting hurt clarity and make the description less concise than it should be.

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 getter, the description combined with annotations covers the core purpose and parameter. It does not describe the output shape or error behavior, but these are less critical given the simple nature of the tool and the high schema coverage.

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 required parameter 'id' has 100% schema coverage and its description adds useful provenance by stating it is returned by cms_list_articles. This goes beyond the basic schema and clarifies where the id comes from.

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 retrieves one CMS article by article id, which is a specific verb and resource. It is distinguishable from sibling getters by the 'article' resource, though it does not explicitly contrast with getters for paragraphs or other CMS 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 gives a usage hint ('after cms_list_articles discovery when needed'), but it does not clearly explain when not to use this tool or how it differs from related getters. The guidance is present but minimal and somewhat ambiguous.

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 says 'Read' and 'Retrieve', which aligns with the readOnlyHint, idempotentHint, and non-destructive annotations. It adds a small amount of context about how the paragraph is identified (by paragraph id) but does not describe error behavior or side effects, which are already covered by 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 short but somewhat redundant: 'Read one paragraph' and 'Retrieve one paragraph by paragraph id' convey the same idea. The 'Guidance' and 'context' fragments add a slightly awkward structure, but the overall length is acceptable.

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 operation with fully described parameters and annotations covering safety, the description is adequate. It does not explicitly explain the relationship between the article id and paragraph id, but the parameter descriptions make this clear enough. No output schema exists, so no details are missing there.

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 provides full coverage of both parameters with clear descriptions ('Article id' and 'Paragraph id'). The tool description mentions 'by paragraph id' and references the context of id and paragraph_id, but adds little beyond what the schema already states. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Read') and resource ('one paragraph'), and the tool name clarifies the article context. It is distinguishable from sibling tools like cms_get_article or cms_get_event_paragraph because it explicitly targets a paragraph, though it does not explicitly say 'article paragraph' in the description itself.

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 does not provide any guidance on when to use this tool versus alternatives such as cms_list_article_paragraphs. There is no mention of conditions that would favor retrieval of a single paragraph over listing all paragraphs, leaving the agent to infer the appropriate use case.

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

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

The annotations already declare read-only, idempotent, and non-destructive behavior. The description adds no extra behavioral detail such as error cases, return format, or side effects, so it provides only baseline 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 short but contains significant redundancy: 'Retrieve one CMS agenda event by event id after cms_list_events discovery when needed.' is repeated verbatim as 'Guidance:', followed by an unclear '| context: id' fragment. The repeated sentence does not earn its place.

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

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

For a simple single-event retrieval tool, the description provides sufficient context: it identifies the resource, the required id, and the recommended discovery flow. It does not mention output shape or error behavior, but the absence of an output schema makes this acceptable for such a straightforward read operation.

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 parameter schema is fully covered by the description in the schema itself, but the description adds helpful context by specifying that the id is returned by cms_list_events. This gives the agent a clear source for the parameter 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 action (retrieve), the resource (one CMS agenda event), and the key identifier (event id). It is immediately obvious what the tool does.

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

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

The description gives practical guidance to use this tool after cms_list_events discovery and only when needed. It does not explicitly contrast with sibling tools like cms_get_event_paragraph, but the resource type is clear enough to avoid confusion.

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 is consistent with the annotations (readOnlyHint, idempotentHint, destructiveHint) and does not contradict them. However, it adds no extra transparency beyond the annotations, such as potential side effects or error conditions.

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, using only two short sentences, and is well-structured with a separate 'Guidance' line. It is easy to read and does not contain fluff, though it could be slightly more informative without losing 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?

The description covers the basic purpose and parameters, but it does not mention any output format, prerequisites, or related list tools (e.g., cms_list_event_paragraphs). Given that there is no output schema, the description could still benefit from a note about what is returned or when to use this after listing paragraphs.

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

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

The schema already provides descriptions for both parameters ('Event id returned by cms_list_events' and 'Paragraph id returned by cms_list_event_paragraphs'), covering 100% of parameters. The tool description adds no additional semantic information beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'read' and identifies the resource as an 'event paragraph' with a specific identifier. It is distinct enough given the tool name includes 'event' and the description mentions 'agenda event paragraph.' However, it is terse and does not elaborate on what a paragraph is.

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 basic guidance line ('Retrieve one agenda event paragraph by paragraph id') but does not explicitly explain when to choose this over other paragraph getter tools (e.g., cms_get_article_paragraph). The distinction is implicit via the resource type, but no explicit selection criteria are given.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior; the description only repeats retrieval semantics and adds no extra behavioral detail such as error or not-found 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 contains an exact duplicate under 'Guidance:' and a stray '| context: id' suffix, which makes it redundant and noisy despite being short.

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

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

For a simple single-parameter getter, the description provides enough purpose and usage context, but the redundancy and lack of return/error detail keep it from being fully polished.

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 only parameter is fully described in the schema as an ID returned by cms_list_maps, so the description adds little beyond reinforcing the source of the ID.

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

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

Clearly states it retrieves a single CMS map item by ID, distinguishing it from listing maps and map paragraphs. The verb 'Retrieve' and resource 'CMS map item' are specific.

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

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

Explicitly frames usage after cms_list_maps discovery, giving a clear when. It does not name alternative tools or state when not to use it, but the context is sufficient.

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

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

Annotations already declare readOnly and idempotent hints, so the bar is lower. The description adds no further behavioral context—no mention of side effects, error cases, or data returned. It simply repeats the read intent without additional 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?

The description is extremely concise—two short sentences—with no redundant fluff. The 'Guidance' prefix is slightly odd but does not harm clarity. It is well-structured and to the point.

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

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

Given the tool's simplicity and lack of output schema, the description still omits essential context: it does not explain the relationship between the two ids (map item id and paragraph id) or clarify that both are required. It also lacks any situational context, making it incomplete for an agent deciding to use this tool.

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

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

Schema coverage is 100% because both parameters have descriptions in the input schema. The tool description itself does not add any semantic detail beyond listing 'id, paragraph_id', so it neither enhances nor detracts from the parameter meaning. Baseline 3 applies.

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

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

The description clearly states the action ('Retrieve') and the resource ('one map paragraph'), which is specific enough to distinguish from other get_* tools. However, it only mentions 'paragraph id' without explicitly referencing the map id parameter, so it is not fully explicit about the required input combination.

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 no guidance on when to use this tool versus alternatives like cms_list_map_paragraphs or cms_get_map. The 'Guidance' section merely restates the purpose rather than offering selection criteria or exclusions, leaving the agent without direction on tool choice.

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, which cover the safe read behavior. The description's 'Retrieve' aligns with these annotations but adds no extra behavioral context such as error handling or response format, so the bar is partially met.

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 contains significant redundancy: the main sentence and the 'Guidance' sentence are nearly identical, and the trailing '| context: id' appears to be a template artifact. This bloats the text and distracts from the core message.

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

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

With no output schema, the description does not need to explain return values. The parameter is well-covered and annotations handle safety. However, the ambiguous 'when needed' and lack of context about when to prefer this over list_photos leaves some gaps, though it is adequate for a simple get operation.

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 sole parameter 'id' is described as 'Photo item id returned by cms_list_photos', which gives clear provenance and meaning. This adds value beyond the schema's type and requirement, though it could be more explicit about the id being the specific photo identifier.

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

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

The description clearly states the tool retrieves a single CMS photo gallery item by photo id, using the specific verb 'Retrieve' and identifying the resource. It also mentions discovery via cms_list_photos, which helps differentiate it from list and other get tools, though the wording is slightly indirect.

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 hint to use this after cms_list_photos discovery, but the guidance is vague ('when needed') and does not explicitly contrast with alternatives like list_photos or other get_* tools. There is a redundant 'Guidance' statement that adds little.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds no contradictions and the note about 'discovery' provides a small amount of behavioral context. Since annotations carry the main safety info, the description meets the lowered bar.

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 extremely concise, with the core action in the first sentence and only one additional qualifying phrase. 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 simple single-parameter getter with no output schema, the description sufficiently covers what it does and where the id comes from. It could mention the return shape, but given the tool's simplicity and the provided annotations, it is complete enough.

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 only parameter 'id' is described as 'Sound item id returned by cms_list_sounds', which adds a clear origin and validates the type and minimum. With full schema coverage, this extra context elevates it above the baseline.

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

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

The description clearly states the action ('Retrieve') and the resource ('one CMS sound item'), distinguishing it from other getters for different content types. It also notes a typical usage flow via 'after cms_list_sounds discovery', which adds specificity.

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 guidance on when to use the tool ('after cms_list_sounds discovery when needed'), which implies a sequential context. It doesn't explicitly name alternatives like 'use cms_list_sounds for multiple items', but the mention of discovery is a useful pointer.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the behavioral profile. The description adds no further details about side effects or constraints, but it does not contradict the annotations either.

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 brief and to the point, but the 'Guidance' segment partially repeats the main sentence and the 'context' field is somewhat cryptic. Still, it remains compact without unnecessary 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 adequately covers the core retrieval action and parameter origins, but it omits any mention of output format, error behavior, or relationship to similar getter tools. Given the simplicity of a getter, this is acceptable but not fully complete.

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

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

The schema descriptions for both parameters are meaningful ('Sound item id returned by cms_list_sounds' and 'Paragraph id returned by cms_list_sound_paragraphs'), providing context that links to list operations. The main description itself adds no extra parameter detail, but the high schema coverage warrants a score above the baseline.

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

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

The description clearly states 'Read one paragraph' and 'Retrieve one sound paragraph by paragraph id', which unambiguously identifies the action (retrieve) and the resource (a single sound paragraph).

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

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

No guidance is provided on when to use this tool versus sibling tools like cms_list_sound_paragraphs or cms_get_sound. The description only restates its function without clarifying conditions or alternatives.

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

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

The description accurately reflects a read-only, idempotent retrieval operation. Annotations already declare readOnlyHint and idempotentHint, and the description adds no contradictory or misleading behavioral claims.

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 front-loads the core action. The repeated 'Guidance' sentence is slightly redundant, but it does not harm 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?

The description provides enough context for a simple get-by-id operation and references the discovery tool. It does not specify the output shape, but that absence is acceptable for this tool type.

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 only parameter, id, is well explained: it is a video item id returned by cms_list_videos. This gives the agent clear guidance on how to obtain a valid 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 retrieves one CMS video item by video id, with a specific verb and resource. It also distinguishes this from listing operations by referencing cms_list_videos for 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 advises using cms_list_videos first for discovery, which provides useful sequencing guidance. It does not explicitly contrast with related get/paragraph tools, but the intent 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, idempotentHint, and non-destructive behavior. The description's 'Read' and 'Retrieve' align with these hints but add no further behavioral detail such as error handling or return format, which is acceptable given 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 extremely concise, consisting of a single sentence plus a short guidance line. It contains no redundant information and is well-structured for quick parsing.

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 is a simple get operation, and the description sufficiently explains what it does and how to invoke it. The lack of an output schema is not a major gap, though specifying that it returns a paragraph object could have added slight completeness.

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

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

Schema coverage is 100% with both parameters described referencing their source lists (cms_list_videos and cms_list_video_paragraphs). The description's mention of 'paragraph id' and the context list reinforces but does not add 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 function: 'Retrieve one video paragraph by paragraph id.' It uses a specific verb ('retrieve') and resource ('video paragraph'), and distinguishes itself from sibling tools like cms_get_video and cms_list_video_paragraphs.

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 direct usage guidance: retrieve a single video paragraph given the paragraph id, with context on the required ids. It does not explicitly mention alternatives, but the specificity makes the appropriate use case 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 readOnly, idempotent, and non-destructive behavior, so the description needs no extra safety caveats. The description adds context that it lists body paragraphs for one article, but no additional side-effect info is needed given 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 extremely concise, using only two short phrases. Every word adds value, and the guidance is separated clearly with a pipe separator. No redundancy or 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?

Although there is no output schema, the description provides enough context for a simple read operation: it lists body paragraphs for a given article. The absence of output details is acceptable for a tool whose purpose is obvious from the name and parameter description, but a note on what each paragraph contains could slightly 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?

The only parameter 'id' has a schema description that fully explains its role: 'Article id returned by cms_list_articles.' Schema coverage is 100%, so the description does not need to add further detail. It correctly points to the source of the id.

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 ('List') and the resource ('paragraphs' for one CMS article), distinguishing it from other paragraph-listing tools like cms_list_event_paragraphs. The guidance reinforces the specific 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 guidance explicitly says 'for one CMS article', making the intended use clear. While it doesn't name alternatives, the tool name and sibling context make the choice obvious. It could benefit from saying 'use this when you need paragraphs belonging to a specific article' but that is well implied.

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

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

The annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description does not add behavioral details beyond the annotations, but there is 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 brief and to the point, with no redundant information. It clearly lists the filter options without excessive 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?

The description is sufficient for a read-only list operation. It does not specify output structure, but that is not required for a list tool without an output schema. The guidance sentence is somewhat redundant but not harmful.

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 descriptions cover all parameters. The tool description adds value by explaining that category ids come from cms_list_cms_sections, and clarifies the 'status' filter behavior. This goes beyond the schema.

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

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

The description clearly states the tool lists CMS articles and mentions specific filters (category, status, title, pagination, ids, sorting). It is distinct from sibling list tools for other entity types.

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 indicates when to use this tool (listing articles) and references cms_list_cms_sections for category ids, providing context. It does not explicitly compare with alternatives but the entity-specific naming makes usage 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 cover the key behavioral traits (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description does not contradict them—'List' is consistent with read-only semantics. The description adds minor context (app-scoped, by content type) but no significant behavioral disclosure 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 compact and front-loaded with the primary purpose, but the second sentence largely repeats the first ('List CMS content sections... by CMS content type' vs. the enum in sentence one), with only 'for the current app' as genuinely new information. The trailing '| context: type' fragment is also awkwardly formatted.

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

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

For a simple one-parameter read-only list tool with no output schema, the description conveys the core operation, but it leaves ambiguity around what 'sections and categories' separately mean and does not clarify how this tool relates to the nearly identical sibling cms_list_sections. These gaps prevent a higher completeness score.

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

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

Schema description coverage is 100% with the 'type' parameter already described as 'CMS content type to discover' plus a full enum. The description reinforces the parameter role ('by CMS content type') but adds no new meaning, such as what each enum value returns or how the result differs by type, so the baseline of 3 applies.

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

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

The description states a specific verb ('List') and resource ('CMS content sections and categories'), and scopes it by content types (article, maps, video, photo, agenda, sound). This implicitly distinguishes it from the plain cms_list_sections sibling, though the distinction is not explicit and 'sections and categories' is slightly ambiguous.

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 guidance sentence ('List CMS content sections for the current app by CMS content type') provides clear context on when to use the tool: when you need sections filtered by a specific content type, scoped to the current app. However, it does not explicitly state when not to use it or name alternatives like cms_list_sections or the per-type cms_list_* 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 read-only, idempotent, non-destructive behavior. The description adds no further behavioral details such as ordering, pagination, empty results, or errors.

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 short and mostly to the point, though 'List paragraphs.' and 'Guidance: List body paragraphs...' are somewhat redundant.

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 is sufficient to identify the operation and required id, but it lacks any indication of the output shape, ordering, or result details, especially given no output schema is provided.

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 fully describes the only parameter (id) with a clear source ('returned by cms_list_events'), so baseline applies. The description contributes no additional parameter meaning.

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

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

The title and guidance clearly identify the action (list) and resource (body paragraphs for one CMS agenda event). However, the first sentence 'List paragraphs.' is vague on its own.

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 does not explain when to use this tool versus alternatives like cms_get_event_paragraph or other list paragraph tools, nor does it contrast with related event tools.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds detail about default behavior (listing non-deleted items) and filtering options, but does not mention error cases or response structure.

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

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

The description is concise and to the point, covering the main functionality and filters without extraneous detail. The guidance duplicates the description but does not harm 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?

While the description does not specify the response format (no output schema is provided), it adequately describes the input parameters and the operation's purpose. The lack of response details is a minor gap given the absence of 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?

All 8 parameters have clear descriptions, including enum values and repetition behavior. The schema coverage is 100% and the descriptions add meaningful context beyond the basic type information.

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: listing CMS agenda events, with optional filters. It is a specific verb-resource pair that distinguishes it from other list tools for different entity types.

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

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

The description implies usage for event listing but does not explicitly contrast with sibling list tools. The guidance repeats the description, providing no additional decision context, though the resource-specific naming makes the intended use 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?

The annotations already declare readOnly, idempotent, and non-destructive behavior, so the description does not need to restate safety. It adds the map-item scoping but no further behavioral details.

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 short but redundant: 'List paragraphs.' repeats the guidance that follows. The pipe-delimited 'context: id' fragment is also cryptic and adds clutter.

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 listing tool, the description adequately states what is returned. It does not mention output format or ordering, but these are not critical for this operation.

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 sole parameter 'id' is already described in the schema as 'Map item id returned by cms_list_maps.' The description adds no additional parameter meaning beyond that.

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 specifies the action ('List') and the resource ('body paragraphs for one CMS map item'), which distinguishes it from sibling paragraph-listing tools for articles, events, sounds, and videos.

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 clearly implies when to use it: when needing the body paragraphs of a specific map item. It does not explicitly mention alternatives or exclusions, 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?

Annotations already cover read-only, idempotent, non-destructive, and open-world behavior. The description adds little beyond restating filters; it does not describe default response behavior or pagination defaults.

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

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

The main sentence is concise, but the appended 'Guidance:' sentence is redundant and truncated mid-phrase. This duplication and incompleteness prevent the description from being 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?

With no output schema, the description could benefit from a brief note about return shape or defaults. The schema and annotations fill many gaps, but the truncated guidance leaves the description feeling incomplete.

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 descriptions cover 100% of parameters, so the baseline is 3. The description mostly restates filter names already present in the schema; only the reference to cms_list_cms_sections adds cross-tool context, but that is also in the category 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 explicitly states the action ('List'), the resource ('CMS map (point of interest) items'), and the optional filtering dimensions. It clearly distinguishes this from single-item retrieval and paragraph listing 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?

It explains when to use the tool by describing optional filters (category, status, search, pagination, ids, sorting) and points to cms_list_cms_sections for category ids. It does not explicitly contrast with alternatives like cms_get_map, but the list-vs-get distinction is strongly implied.

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 no behavioral details beyond listing the resource, such as rate limits, authorization requirements, or response format. It does not contradict annotations, but it also doesn't provide extra context, so a 3 is appropriate.

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 contains two sentences, but the second sentence is a near-verbatim repetition of the first part: 'Guidance: List CMS photo gallery items, optionally filtered by one photo gallery section.' This redundancy wastes space and could confuse the agent. A concise single sentence would suffice.

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 list tool with no output schema, the description covers the action and main filters but does not explain the structure of returned photo items or how filters combine (e.g., AND vs OR). However, given that the sibling cms_get_photo likely describes a single photo object, and the parameters are well-documented, it is reasonably complete, though not exhaustive.

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%, meaning every parameter has a description in the schema. The tool description lists the filter categories but adds no additional meaning beyond what the schema already provides. For instance, the schema already explains that 'section' is returned by cms_list_cms_sections. The description is redundant here, so a 3 is given.

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 'List' and the resource 'CMS photo gallery items', and enumerates the available filters (section, status, search, pagination, id, sorting). It is unambiguous and distinguishes from sibling list tools for other content types (e.g., cms_list_articles, cms_list_events) by naming the specific resource.

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 conveys that this tool lists photo gallery items, which is appropriate when a list of photos is needed. It does not explicitly mention alternatives like cms_get_photo for single photo retrieval, but the context is clear. There is no explicit guidance on when not to use it, so a 4 is given.

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

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

The annotations already indicate readOnly, idempotent, and non-destructive behavior, and the description's 'list' wording matches this. It does not add much behavioral detail beyond the annotations, but there is 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 first sentence is concise, but the appended 'Guidance: ... | context: type' is redundant and awkwardly repeats the same information. This hurts the overall structure and focus.

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 listing tool with one parameter and no output schema, the description is mostly complete. It explains the scope, mentions content and non-content sections, and points to the more specific CMS section tool, giving enough context for an agent to select 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 parameter schema already covers the 'type' parameter thoroughly with common values and the distinction from cms_list_cms_sections. The description only adds 'by section type', so it contributes little beyond the existing schema 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 clearly states the tool lists the generic app section catalog by type, including content and non-content sections. It also distinguishes itself from cms_list_cms_sections by using the word 'generic' and referencing CMS-only alternatives.

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 and parameter guidance indicate when to use this tool versus cms_list_cms_sections, especially through the parameter description instructing to prefer cms_list_cms_sections for CMS-only sections. The main description could be more explicit but still gives useful direction.

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=true, destructiveHint=false) already indicate a safe read operation. The description's 'List' is consistent with these annotations and adds no further behavioral information, but there is 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 extremely short and to the point, containing only the essential verb and resource. Every word serves a purpose, and the format is clean and easy 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?

With no output schema provided, the description does not explain return fields or pagination behavior. However, the purpose is clear enough for a simple list operation, and the sibling tools follow a similar pattern, so it is adequate but not 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 only parameter 'id' is fully described in the schema as 'Sound item id returned by cms_list_sounds.' The tool description adds no additional meaning beyond this, so it meets the baseline but does not exceed it.

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

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

Description clearly states the action ('List') and the resource ('body paragraphs for one CMS sound item'), and the title/name disambiguates from sibling paragraph-listing tools by specifying 'sound'. It also notes the 'id' context from cms_list_sounds, making the 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?

No explicit guidance on when to use this tool versus alternatives (e.g., cms_get_sound_paragraph or cms_list_sounds). It implies the id must come from cms_list_sounds, but does not describe scenarios where this tool is preferred or not recommended.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds transparency by clarifying default behavior (e.g., 'Omit to list every non-deleted item in scope' and 'Omit to list across all categories'), which goes beyond the annotations and helps set expectations.

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, but it contains slight redundancy with the 'Guidance' line repeating the core filtering idea. It is still compact and front-loaded with the primary action, so minor redundancy does not detract much.

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

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

Given the complexity of 8 optional parameters and no output schema, the description adequately covers all relevant aspects by naming each filter type and referencing the schema for details. It does not describe return format, but that is not required without an output schema, and the filter semantics are complete enough for an agent to invoke correctly.

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

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

Schema descriptions cover 100% of parameters with clear explanations for each (e.g., 'Optional sound category ids returned by cms_list_cms_sections'). The tool description does not add significant meaning beyond summarizing these filters, so it meets the baseline but does not elevate it.

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

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

The description clearly states the tool lists CMS sound items, which is specific and unambiguous. It distinguishes from sibling tools like cms_list_videos or cms_get_sound by naming the resource type, and the reference to cms_list_cms_sections for category ids further clarifies 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 implies usage for listing sound items with optional filters, and the reference to category ids from cms_list_cms_sections provides a practical hint. However, it does not explicitly contrast with alternatives (e.g., when to use cms_get_sound vs. cms_list_sounds), though the context of sibling tools makes this largely inferable.

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, covering the safety profile. The description adds no additional behavioral context such as ordering, filtering, pagination, or what fields each paragraph contains. The 'context: id' note is unhelpful.

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 short but poorly structured with a redundant 'Guidance:' prefix and a cryptic '| context: id' suffix. The phrase 'List paragraphs' is vague and not front-loaded with the specific scope.

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 list tool with no output schema, the description fails to describe what a paragraph contains or the structure of the returned list. It also omits any details about ordering or pagination, leaving an agent without enough information to anticipate the response.

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 id parameter is well described as 'Video item id returned by cms_list_videos.' The description does not add any extra meaning beyond the schema, so the baseline 3 applies.

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

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

The description states 'List body paragraphs for one CMS video item,' which specifies the verb (list), the resource (body paragraphs), and the scope (one video item). This is clear and not a tautology, though it does not explicitly contrast with sibling list tools like cms_list_article_paragraphs.

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?

There is no guidance on when to use this tool versus alternatives such as cms_get_video_paragraph or other cms_list_*_paragraphs tools. The cryptic 'context: id' offers no practical usage direction.

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 a meaningful behavioral detail by noting that omitting the status filter lists 'every non-deleted item in scope', which clarifies the default behavior. 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 consists of two sentences, but the second sentence (under 'Guidance:') repeats the first nearly verbatim, adding no new information. This redundancy makes it less concise than it could be, though it is still brief overall.

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?

There is no output schema, and the description does not state what the response format will be (e.g., array of video items, pagination metadata). It implies a list but leaves the return shape unspecified, which is a notable gap given the absence of 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% — every parameter (id, page, sort, order, search, status, category, per_page) has a description. The tool description adds no new parameter information beyond what the schema already provides, so baseline 3 applies.

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

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

The description clearly states the verb 'List' and the resource 'CMS video items', and it enumerates optional filters (category, status, search, etc.) that distinguish this from other list tools. The name and title align perfectly, and the reference to cms_list_cms_sections for category IDs adds precision.

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

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

The description specifies when to use the tool: to list videos with optional filters, and it provides concrete guidance on the status filter ('Omit to list every non-deleted item in scope'). It does not explicitly contrast with cms_get_video or cms_list_video_paragraphs, but the resource and filters make the use case 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?

The annotations (readOnlyHint, idempotentHint, destructiveHint) already cover safety traits. The description adds value by specifying the response content (guidance, sequence, failure policy), which goes beyond the annotations. No contradiction 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?

The description is a single, well-structured sentence with no fluff. It front-loads the action and object, making it easy 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?

The tool has a single parameter and no output schema, so the description sufficiently covers what it does and what it returns. No additional context is needed for correct 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 schema already describes the parameter, but the example 'shop_create_product' adds concrete meaning and clarifies the expected format. This exceeds the baseline for high schema 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 clearly states the verb 'Retrieve' and the object 'full guidance for one tool name', distinguishing it from sibling tools that perform domain operations. It is specific and unambiguous.

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

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

The description explains what the tool returns (discover/call/verify sequence and failure policy) but does not explicitly state when to use it versus alternatives. Since it is a meta-tool with no sibling guidance tools, the usage context is implicit but not clearly articulated.

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

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

Annotations already declare readOnly, idempotent, and not destructive. The description is consistent with these, adding no further 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?

The second sentence is redundant and awkward, repeating the purpose and appending 'context: collection_id' without value. The first sentence alone would have been sufficient and clear.

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 getter with one well-described parameter, the core functionality is covered. However, the redundant guidance adds noise and no additional context.

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

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

Schema provides a clear description for collection_id ('Collection Unique ID.'), covering 100% of parameters. Description adds no extra semantic detail 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?

Clearly states 'Returns the details of a specific collection', identifying the verb and object. Distinguished from list_collections by the word '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?

No explicit guidance on when to use this tool instead of alternatives like shop_list_collections. The 'Guidance' line merely restates the purpose without adding selection criteria.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds no extra behavioral context (e.g., side effects, errors, or scoping) but does not contradict 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 redundant, repeating the same sentence under 'Guidance:' and appending '| context: customer_id'. This awkward structure detracts from 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?

The tool is simple with one input and no output schema. The description states it returns 'details' but does not specify what details, which is somewhat vague; however, it is adequate for a basic get operation.

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 full coverage of the single parameter customer_id with a clear description ('Unique ID of the customer'). The tool description adds no additional semantic meaning beyond the schema.

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

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

The description states a specific verb ('Returns') and a specific resource ('details of a given customer'), clearly distinguishing this tool from list tools such as shop_list_customers by using singular 'a given customer'.

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 no explicit guidance on when to use this tool versus alternatives like shop_list_customers. It only implies the need for a customer_id, without stating conditions or comparing to other tools.

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

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

Annotations (readOnlyHint, idempotentHint, non-destructive) already cover the behavioral profile, and the description adds no contradictory side effects or permissions requirements. It neither enhances nor undermines transparency, so a neutral 3 is appropriate given the 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 core sentence is concise, but the description contains redundant repetition ('Returns the loyalty points...' twice) and includes a misplaced 'Guidance:' and 'context: user_id' suffix that disrupts structure and adds noise without 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 getter with a single parameter, the description sufficiently explains the operation and input. No output schema is present, but for such a straightforward retrieval, the provided information is complete enough for an agent to use it correctly.

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

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

The only parameter, user_id, has a schema description ('Unique ID of the user') providing full coverage (100%). The description repeats 'context: user_id' but adds no additional semantic meaning beyond the schema, so the baseline score for full coverage is maintained at 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 it 'Returns the loyalty points details of a user', which specifies the verb and resource. It distinguishes from shop_update_loyalty among siblings, but the duplicate phrasing and the odd 'Guidance:' and 'context: user_id' appendix create slight confusion, preventing a 5.

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

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

The description implies usage is to retrieve loyalty points for a user, but it does not explicitly state when to use it over other getter tools or any prerequisites. The context is self-evident, but no direct guidance or alternative contrast is provided.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to repeat this. The description provides no additional side-effect information, but none is required given 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 short and to the point, but it contains a slight redundancy: 'Returns the details of a given order.' is repeated in the 'Guidance' clause. This does not harm clarity but could be trimmed.

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 is sufficient for a simple getter operation. There is no output schema, but the tool name and parameter indicate it returns order details, which is typical for such getters in this API family.

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 fully describes order_id as the unique ID of the order, and the description echoes that. Since the schema coverage is 100% and the description adds no extra semantic detail, the baseline of 3 is appropriate.

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

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

Clearly states the tool returns details of a specific order identified by order_id. This distinguishes it from sibling tools like shop_list_orders, which list multiple orders, and other getters for different resources (products, customers, etc.).

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

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

The description implies usage when a single order's details are needed by ID. While it doesn't explicitly contrast with alternatives such as shop_list_orders, the function name and parameter make the appropriate context 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 indicate readOnly and idempotent, and the description adds no extra context about side effects, authentication, or rate limits. The operation is a simple read, so the annotation covers the main safety profile.

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 one concise sentence with no redundancy or irrelevant detail, making it 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?

Although no output schema is provided, the description explicitly names the return fields (status, shipping number, shipping URL), which fully conveys what the tool returns. No additional context is necessary for this straightforward read operation.

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 order_id has full schema coverage and its description 'Unique ID of the order' is clear. Since schema coverage is 100%, the baseline applies and the description adds no further semantic depth.

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

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

The description clearly states the tool retrieves status, shipping number, and shipping URL for an order, which is specific and distinguishes it from broader tools like shop_get_order or shop_update_order_shipping in the sibling list.

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

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

No guidance is provided on when to use this tool versus alternatives such as shop_get_order or shop_update_order_shipping. The description lacks explicit context for selecting it.

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

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

The description indicates a read operation returning details, which aligns with the readOnlyHint and idempotentHint annotations. It does not add much behavioral detail beyond the annotations, but there is 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 short but contains redundancy: the 'Guidance' line repeats the first sentence almost verbatim. The appended 'context' fragment feels bolted on and the overall structure is not clean.

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 tool with no output schema, the description is reasonably complete in stating that it returns details for the identified media. However, it does not clarify what 'paragraph media' is or what the returned details contain, relying on context from sibling tools.

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 three parameters are covered by the schema with clear descriptions like 'Unique ID of the media' and similar. The tool description adds no extra semantic information beyond the schema, so it meets the baseline but does not exceed it.

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

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

The description clearly states the tool returns details of a paragraph media and identifies the key object. It is slightly generic and does not elaborate on what 'details' includes, but the core purpose is 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?

No guidance is provided on when to use this tool instead of the many sibling get/list tools. The 'Guidance' text merely repeats the description, and the appended context line does not offer decision guidance.

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

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

The annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds no extra behavioral context, but it also does not contradict 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 repeats the same phrase twice and includes an awkward stray 'Guidance: ... | context: product_id' fragment, which reduces clarity and wastes space.

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 get-by-ID operation, the description is mostly sufficient. It would benefit from mentioning what kind of details are returned, but the lack of an output schema makes this less 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?

The input schema already defines product_id as an integer with 'Product Unique ID.' The description adds no further semantic detail about the 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 ('Retrieves') and the resource ('details of a specific product'), making the tool's purpose unmistakable even among many sibling getters.

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

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

No guidance is provided about when to use this tool instead of sibling tools like shop_get_variant, shop_get_collection, or shop_get_order. The description does not distinguish it from alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds no extra transparency about side effects, errors, or edge cases, so it meets the baseline given 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 short and to the point, but it contains redundancy with the 'Guidance:' line repeating the same information. This minor repetition prevents a perfect score.

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 does not mention what happens if the promocode does not exist, whether it returns a specific schema, or how it fits into the broader shop context. It is minimally complete but lacks helpful context that could guide an agent.

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

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

The parameter promocode_id has a clear description in the schema ('Unique ID of the promocode'), and the tool description reinforces its role. Since schema coverage is 100%, this is above baseline.

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

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

The description clearly states that the tool returns details of a single promocode identified by its ID, making its purpose distinct from list and mutation tools for other 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 implies usage for retrieving a single promocode by ID but does not explicitly guide when to prefer this over other promocode-related tools (e.g., shop_list_promocodes_*) or how it differs from them.

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

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

The annotations already convey that the operation is read-only, idempotent, non-destructive, and broadly accessible. The description adds no additional behavioral context such as possible error conditions or data scope, but it does not contradict 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 repeats the same statement twice: 'Returns the details of a given prospect of your shop app.' followed by 'Guidance: Returns the details of a given prospect of your shop app.' It also includes a confusing trailing fragment '| context: user_id,' making it less concise than it should be.

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-by-ID operation, the description is adequate, but it is vague about what 'details' are returned and there is no output schema to clarify the response structure. It does not fully cover expected return content or error behavior.

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 only parameter, user_id, is already documented in the schema as 'Unique ID of the User.' The description does not add further meaning beyond referring to a 'given prospect,' so it provides no extra value beyond the existing schema 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 clearly states the tool returns details of a specific prospect, using a specific verb and resource. It is distinct from sibling tools like shop_list_prospects and shop_get_customer because it targets a single prospect.

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 no guidance on when to use this tool versus alternatives such as shop_list_prospects or other shop_get_* tools. It does not mention prerequisites, conditions, or exclusions.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds no meaningful behavioral detail beyond the annotations, but it does not contradict 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 text is short but includes a misleading first sentence that should be removed. The remaining content is minimal but the contradictory sentence makes it poorly 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?

The description is incomplete due to the contradictory first sentence and lacks any output expectations. Since there is no output schema, more context about what the tool returns would be valuable.

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

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

The input schema already provides clear descriptions for product_id and variant_id. The description adds no extra semantic value beyond the schema.

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

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

The description opens with 'Return a list of all products,' which directly contradicts the tool's name and parameters, then partially corrects itself with 'Returns the details of a specific product variant.' The conflicting first sentence makes the purpose ambiguous.

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

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

No guidance is given about when to use this tool versus sibling tools like shop_get_product or shop_list_products. The 'context' phrase is not actionable usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context by stating that results are paginated with a default of 20 per page, going slightly beyond the annotation-only information.

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 contains redundant and truncated content, repeating the same sentence under 'Guidance:' and cutting off mid-phrase. This harms clarity and does not earn each sentence's place.

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

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

Given the simple list operation, all parameters are described, pagination behavior is mentioned, and annotations cover safety semantics. However, the truncated duplicate text and lack of any output shape details leave minor room for 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?

All four parameters are documented in the schema with meaningful descriptions, including enum meanings and keyword syntax. The description itself does not add further parameter semantics beyond the schema, so baseline coverage 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?

States a specific action and resource: 'Returns a list of the collections of the shop.' This clearly distinguishes it from single-collection retrieval and from sibling list tools for other resource types.

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 pagination details but gives no guidance on when to use this tool versus alternatives such as shop_get_collection or other shop_list_* tools. No explicit conditions or exclusions are mentioned.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the key behavioral traits. The description adds no extra context about side effects, rate limits, or return details, but it does not contradict the annotations. Given the annotations are present, the bar is lower, and the description is neutral.

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

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

The description is very short, but it contains redundancy: the first sentence and the second sentence starting with 'Guidance:' are essentially the same. This duplication wastes words without adding information. It could be condensed to a single sentence, which would be more efficient.

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

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

For a simple list operation, the description is adequate but not rich. It does not mention that the tool returns a list of customer objects, nor does it explain pagination behavior or ordering. Since there is no output schema, a bit more context about the expected return could be helpful, but the core function is clear.

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

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

Both parameters (page and per_page) have descriptions in the schema, so coverage is 100%. The descriptions are minimal but accurate: 'Page number.' and 'Number of customers displayed on each page.' The description does not add any extra detail such as defaults, minimums, or how pagination interacts with the result set, so it remains at the baseline for fully documented 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 function: 'Returns the list of customers of your shop app.' This is a specific verb-resource pairing that distinguishes it from other list tools like shop_list_orders or shop_list_products. The tool name itself reinforces the purpose.

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

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

The description provides no guidance on when to use this tool versus alternatives such as shop_get_customer for a single customer, or shop_list_prospects for prospects. There is no mention of scenarios where listing customers is appropriate, nor any indication of pagination usage or filters beyond the basic parameters.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already establish that this is a safe read-only operation. The description adds minimal behavioral context, such as the fact that it returns a history and is filtered by date/platform. It does not contradict annotations and provides some context beyond them, but it does not disclose any additional traits like pagination or data volume. A score of 3 is appropriate given the strong annotation coverage.

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

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

The description is extremely short but redundant: it repeats the identical sentence twice, once prefixed with 'Guidance:'. This adds no value and wastes the agent's attention. The first sentence is sufficient and front-loaded, but the duplication harms conciseness and structure. A score of 2 reflects this unnecessary 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?

For a simple list operation with fully documented optional parameters and comprehensive safety annotations, the description provides the core functionality. However, it lacks any guidance on usage context or edge cases (e.g., what 'downloads' specifically refers to, whether results are ordered). Given the low complexity and complete schema, the description is minimally adequate but not thorough. A score of 3 aligns with 'adequate but with clear 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?

The schema describes all three parameters (end_date, start_date, platform) with formats and defaults, achieving 100% coverage. The description essentially restates that downloads are filtered by timestamps and platform, adding no new information beyond what the schema provides. With full schema coverage, the baseline of 3 is correct; the description does not elevate it.

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

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

The description clearly states the tool returns download history filtered by timestamps and platform. It uses a specific verb ('Returns') and resource ('history of downloads'), which is distinct from the sibling 'shop_list_downloads_global' even though it doesn't explicitly name the sibling. The repetition of the same sentence does not detract from clarity.

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

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

No guidance is provided on when to use this tool versus alternatives. The sibling list includes 'shop_list_downloads_global', but the description does not mention it or any criteria for choosing one over the other. The description only restates the core function without contextualizing its scope relative to other download-related 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?

Read-only and idempotent annotations already establish safety; description adds functional behavior (returns totals and distribution) and optional platform filtering without contradicting annotations.

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

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

Core description is concise but the trailing 'Guidance' sentence repeats the same content, adding redundancy without new 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 read-only aggregate tool with no output schema, the description gives enough context about what is returned and how platform filtering works, though it does not specify exact output format.

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 fully describes the platform parameter with enum values and default; description adds little beyond stating the platform is used for filtering.

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 aggregate all-time download counts and version distribution for a specified platform, distinguishing it from the similarly named sibling shop_list_downloads by indicating global aggregation.

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

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

No explicit guidance about when to choose this tool over alternatives such as shop_list_downloads; the 'Guidance' text merely restates the description without adding decision criteria.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) fully cover the operational safety profile, and the description's 'Returns' aligns with these. The description adds no contradictory information; it is a simple read operation.

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 core description is a single clear sentence, but the repetition of the same sentence under 'Guidance' is redundant and detracts from conciseness. It could be streamlined.

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 is sufficient for a simple list operation with optional filters, but it lacks contextual information about what 'launches' represents and does not clarify the distinction from 'unique launches' (sibling tool). No output schema is provided, but that is not a major gap for a list operation.

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 each parameter (start_date, end_date, platform) has a meaningful description with format hints and enum values. The description does not add extra explanation beyond the schema, which is adequate given the high coverage.

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

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

The description clearly states the tool returns a history of launches with optional filters for timestamps and platform. The verb 'Returns' and the resource 'history of launches' are specific, and the tool is distinguishable from the sibling shop_list_unique_launches by the absence of 'unique' in the 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?

No explicit guidance is given about when to use this tool versus alternatives like shop_list_unique_launches. It does not state that this returns all launches or when the unique variant is more appropriate. The description only mentions the parameters, not 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 (readOnlyHint=true, destructiveHint=false) already indicate a safe read-only operation. The description adds useful pagination context, and 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 concise and direct, using two clear sentences with no unnecessary detail or redundancy.

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

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

The description covers the core behavior and pagination, and parameters are well-documented. Although no output schema is provided, the simple list nature and clear parameter descriptions make the tool sufficiently understandable for an agent.

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

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

All three parameters (page, search, per_page) have meaningful descriptions, and schema coverage is 100%. The descriptions clearly convey their purpose and expected effects.

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 a list of options belonging to the shop catalog, and mentions pagination. It is easily distinguishable from sibling list tools (e.g., shop_list_products, shop_list_collections) by name and 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 does not explicitly mention when to use this tool over alternatives or provide conditions for selection. It is implied by the name and context, but lacks the explicit guidance seen in higher-scoring examples.

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 behavioral details beyond the annotations: it mentions pagination with a default of 20 orders per page, status filtering, and the exclusion of orders without delivery slots when date filters are applied. These are not captured in the readOnly/idempotent/destructive annotations, increasing 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?

The description contains a duplicated 'Guidance:' section that repeats the first sentence and is truncated ('...C...'). This redundancy and unfinished fragment makes the text less concise and structurally messy, detracting from its 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?

For a list-orders tool, the description covers the essential context: the resource type, pagination default, status constraints, and the behavior of date filters (including delivery-slot exclusion). It is not exhaustive (e.g., no output schema), but it provides sufficient operational context for an agent to use the tool effectively.

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

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

The input schema already covers all parameters thoroughly, so the baseline is 3. The description adds a small but useful clarification: the default page size (20) is not stated in the per_page parameter description, and the description reinforces the status filter behavior. This extra context raises the score slightly.

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 verb and resource: 'Returns a list of the orders that belong to the specified shop.' This directly differentiates it from sibling tools like shop_get_order (singular retrieval) and other shop_list_* tools, making the primary purpose 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 explains what the tool does and its filtering capabilities, but it does not explicitly say when to use it compared to alternatives such as shop_get_order or other list tools. An agent can infer usage from the purpose, but there is no direct comparative guidance.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds no new behavioral details beyond what the schema and annotations provide; it does not mention pagination, rate limits, or response format. It is consistent with annotations, so 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 consists of two nearly identical sentences, repeating the same information. This is redundant and wastes space; a single sentence would suffice. The duplication makes it less concise and poorly 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?

The tool lacks any mention of its relationship to shop_list_page_views_per_weekday, which is a likely alternative for aggregated weekday data. It also does not clarify the output format (e.g., individual events vs. counts per day), which is ambiguous. Given the annotations cover safety, the main missing context is the differentiation and output nature, making it incomplete.

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 complete descriptions for all three parameters, including formats, defaults, and the platform enum, giving 100% coverage. The description adds no additional parameter semantics or interaction details. With such high schema coverage, the baseline score of 3 is appropriate.

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

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

The description states a clear verb and resource: it returns the history of page views within a time range and platform. It is distinct from sibling shop_list_page_views_per_weekday by its name, but the description does not explicitly differentiate them. Overall the purpose is clear, though not as strong as it could be with an explicit alternative.

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?

There is no guidance on when to use this tool versus shop_list_page_views_per_weekday or other list tools. The description merely repeats the function without any usage context, exclusions, or alternative recommendations. This is a significant gap given the existence of a closely related sibling.

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, and non-destructive behavior, and the description adds relevant behavioral details: aggregation across all platforms, date filtering, and weekday grouping. It does not describe the output format, but the core side-effect profile is well covered by 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 opens with a clear first sentence, but it then repeats the same content under 'Guidance:' and appears truncated mid-sentence. The duplication and typo reduce conciseness and make the description feel unfinished.

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 aggregation tool, the description explains the main behavior and date-range inputs, but it omits the expected output structure and does not guide the agent on when to choose this sibling over shop_list_page_views. The absent output schema increases the need for such detail, so the description is only partially 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 input schema provides full descriptions for both start_date and end_date, including format and defaults, so the parameter coverage is already strong. The description adds no further parameter-level detail, which is acceptable given the 100% schema 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 clearly states the tool returns total page views across all platforms within a date range, grouped by weekday, and the tool name reinforces this. Minor issues like the typo 'platformsand' and the truncated guidance do not obscure the core purpose, but it does not explicitly contrast with sibling shop_list_page_views.

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 does not explicitly say when to use this tool versus alternatives such as shop_list_page_views or shop_list_session_times. It implies usage through the date-range parameters and weekday grouping, but it lacks direct guidance on selecting this tool over similar analytic list 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?

The annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds the sorting-by-position detail, which is useful, but does not elaborate on return format or potential edge cases. 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, using only two sentences to convey the purpose and ordering behavior. There is no redundant information, and the structure is direct.

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 is sufficient for a simple list operation, but it does not specify what fields are returned or whether pagination is involved. Given the lack of an output schema, this minor gap prevents a perfect score, but the core functionality is clearly conveyed.

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 provides a clear description for product_id (Unique ID of the Product), covering 100% of the parameters. The tool description does not add further parameter guidance, so the baseline score of 3 applies.

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

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

The description clearly states the action (Returns), the resource (description paragraphs), and the scope (of the specified product). It also mentions the sorting order, leaving no ambiguity about the tool's purpose.

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

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

The description does not explicitly mention when to use this tool versus alternatives, such as shop_create_paragraph or shop_get_paragraph. However, the straightforward list operation is self-explanatory given the sibling context, but the lack of explicit guidance prevents a higher 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 provide readOnlyHint and idempotentHint, and the description consistently indicates a read-only operation by stating it 'returns' a list. No side effects are mentioned, and no contradictions exist.

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 short and to the point, but the same sentence about returning products and pagination appears twice, and a repeated 'Guidance:' line adds redundancy. This makes it less concise and structurally messy.

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 provides essential details (returns products, pagination default) and the schema covers filtering options. Though there is no output schema, a list operation typically returns product objects, which is implied. No critical information is missing for basic usage.

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

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

Schema descriptions cover all parameters (100% coverage), and the tool description adds a default page size (20 per page) that is not explicitly in the schema. This extra context slightly enhances understanding of pagination behavior.

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 a list of products created in the shop. The verb 'Returns' and resource 'list of products' make the purpose unambiguous, and it naturally distinguishes from sibling tools like shop_create_product or shop_get_product.

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 pagination and defaults but does not explicitly contrast with alternative list tools (e.g., shop_list_orders, shop_list_collections). It implicitly suggests usage when a product list is needed, but lacks explicit 'use when' or 'use instead of' guidance.

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

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

The annotations already declare readOnly, idempotent, and non-destructive behavior, so the description does not need to restate safety. It adds minimal behavioral context by indicating that results are based on order amount, but it does not mention pagination behavior or output shape; the annotations cover the main side-effect concerns.

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

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

The description is very short and front-loaded, but the 'Guidance' line exactly repeats the description, adding no new information. This mild redundancy prevents a higher score, though the overall length is appropriate.

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

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

For a simple list operation with no output schema and two well-documented pagination parameters, the description is mostly adequate. However, the lack of differentiation from sibling promocode list tools and the ambiguous 'based on order amount' filter leave some contextual gaps for an agent choosing among alternatives.

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 provides complete descriptions for both parameters (`page`, `per_page`), so the description adds little beyond the schema. The phrase 'based on order amount' hints at an implicit filter but is not connected to any parameter, leaving the exact filtering semantics unspecified.

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

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

The description clearly identifies the action ('list') and resource ('promocodes'), and adds a specific qualifier ('based on order amount') that distinguishes it from sibling promocode-listing tools. However, it does not sharply contrast with alternatives like collections, product, or tags beyond the phrase 'order amount', which is somewhat implicit.

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?

There is no explicit guidance on when to use this tool versus sibling promocode-listing tools. The description implies an amount-related filter but does not explain scenarios, prerequisites, or how it differs from shop_list_promocodes_collections, shop_list_promocodes_product, or shop_list_promocodes_tags.

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

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

The annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context (e.g., no mention of side effects, but there are none). It does not contradict 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 redundant, containing the same sentence twice. This is not concise and adds no value; the second sentence is an exact duplicate. It should have been a single, clear statement.

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 paginated list tool, the description gives the basic purpose but omits any hint of return format or edge cases. Given the lack of an output schema, a bit more detail on what is returned would improve completeness, but it is adequate for a straightforward list.

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

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

The schema already provides descriptive parameter names and per-parameter descriptions (page, per_page). The tool description adds no additional meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states the tool lists promocodes based on dedicated collections, but the term 'dedicated collections' is vague and the repeated sentence adds no clarity. It does not explicitly say it returns a list, but the intent is understandable.

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

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

No guidance is provided on when to use this tool versus the sibling promocode listing tools (e.g., shop_list_promocodes_amount, shop_list_promocodes_product). The description does not differentiate the use case.

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 no behavioral details beyond the annotations. It repeats the purpose without mentioning side effects, read-only behavior, or any constraints. The annotations indicate readOnlyHint=true and destructiveHint=false, but the description itself provides no additional 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?

The description is brief but repetitive, essentially stating the same phrase twice. It could be condensed to a single sentence without loss of information. The structure is acceptable but the redundancy detracts from 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?

The description lacks essential context such as what 'dedicated product' refers to, whether a product identifier is required (though absent from schema), and what the output format might be. There is no output schema, and the description does not compensate by explaining expected results or error conditions.

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 parameters (page, per_page) are clearly described as pagination controls, but the tool description mentions 'dedicated product' without any corresponding product parameter. This creates a mismatch between the described function and the actual input schema, leaving the agent uncertain how to specify the product.

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 'List of promocodes based on dedicated product' but does not clarify what 'dedicated product' means or how it is specified. The verb 'list' and resource are present, but the scope is ambiguous, especially given sibling tools like shop_list_promocodes_amount and shop_list_promocodes_collections which differentiate by type.

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

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

No guidance is provided on when to use this tool versus alternatives. The description repeats the same phrase twice without mentioning that this tool is specifically for product-based promocodes or how it differs from other promocode listing 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?

The annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is known. The description does not contradict these and adds no additional behavioral details beyond an ambiguous domain note about 'applied before order payment,' which is not clearly a tool 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 short and to the point, but it contains a redundant duplicate sentence (the 'Guidance:' line repeats the description). This redundancy wastes a little space but overall the structure is acceptable and not verbose.

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?

There is no output schema, and the description does not mention what fields will be returned (e.g., promocode details, pagination info). For a list operation, this lack of output context leaves the agent uncertain about the response shape, making the description incomplete.

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 describes both parameters ('page' as 1-based page number, 'per_page' as number per page) with full coverage, so the description does not need to add parameter meaning. Since coverage is 100%, the baseline score of 3 is appropriate, and the description adds no extra insight.

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 verb 'List' and resource 'promocodes tags' are clear, and it distinguishes from sibling tools like shop_list_promocodes_amount and shop_list_promocodes_collections by focusing on tag-based promocodes. However, the phrase 'based on dedicated tags' is slightly ambiguous about whether it lists tags or promocodes filtered by tags.

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

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

The description implies usage for listing promocodes related to tags, but it does not explicitly state when to use this over alternatives (e.g., when you need promocodes filtered by tags rather than by amount or collection). It also includes a redundant second sentence ('Guidance:' that repeats the description), which adds no new usage direction.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds no further behavioral detail about pagination defaults, ordering, filtering, or result shape, so it only partially meets transparency expectations.

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 short but contains a redundant 'Guidance:' line that repeats the same sentence. It is front-loaded but could be more concise by removing duplication.

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

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

No output schema is provided, and the description only says 'returns the list' without detailing pagination response, item fields, or any additional context needed to fully understand the tool's 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 covers both parameters with basic descriptions. The description provides no additional semantic detail beyond the schema, so it stays at the baseline for high schema 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?

Clearly states the tool returns the list of prospects for the shop app, using a specific verb and resource. It is distinguishable from shop_get_prospect and other list 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?

No explicit guidance on when to use this tool instead of alternatives such as shop_get_prospect or shop_list_customers. The description implies listing behavior but does not state conditions or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, which the description accurately reflects by stating it 'returns' data. The description does not add additional behavioral details (e.g., response size, error cases) but does not contradict 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 but is duplicated verbatim, creating unnecessary redundancy. It lacks structured usage notes or examples, though it is brief and to the point.

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

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

With no output schema, the description should explain what kind of data is returned (e.g., individual session timestamps, counts, or aggregates). It only says 'history of session times,' which is vague. Additionally, the 'platform' mention without a corresponding parameter adds confusion rather than 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 provides complete coverage for both parameters (start_date, end_date) with format and defaults. The description adds no extra semantic meaning to these parameters; it only vaguely references 'specified timestamps' without clarifying their role or relationship.

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 history of session times' between specified timestamps, conveying a specific verb and resource. However, it mentions 'specified platform' which is not present in the input schema, introducing minor ambiguity about the tool's exact 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 provides no guidance on when to use this tool versus sibling tools like shop_list_page_views or shop_list_orders. No exclusions, comparisons, or conditional usage hints are given, leaving the selection criteria entirely 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 clearly declare readOnlyHint, idempotentHint, and destructiveHint false, which aligns with the description's promise of returning a list. No side effects are implied or omitted.

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 short and front-loaded, but it repeats the same content in the 'Guidance' portion, creating unnecessary redundancy.

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

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

The tool's purpose and basic pagination are described, but there is no output schema and no indication of what fields each returned tag contains, leaving some ambiguity about the response shape.

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 three parameters have descriptions and the sort enum values are explained, providing good schema coverage. However, the descriptions are terse and add little beyond what the schema already conveys.

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

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

Clearly states the tool returns a list of tags used in the shop, using a specific verb and resource. The resource name and description distinguish it from the many sibling list tools.

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

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

The description implies use when needing to list shop tags and provides pagination context, but it does not explicitly contrast this tool with similar sibling tools or explain when it should be preferred.

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, and the description is consistent with those traits. No additional side-effect, authorization, or rate-limit context is added, so it stays at the annotation baseline.

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 first sentence is clear and front-loaded, but the 'Guidance:' sentence is an exact duplicate and provides no additional value, reducing overall 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?

The description is minimal and does not specify return shape, uniqueness definition, or sort/grouping behavior. Since there is no output schema, this leaves some ambiguity, though it is sufficient for a simple list query.

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 provides full coverage of all three parameters with descriptions, defaults, and the platform enum. The description adds no meaningful semantic detail beyond restating 'specified timestamps and platform.'

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 history of unique launches filtered by date range and platform, with an explicit verb and resource. It does not explicitly contrast with sibling shop_list_launches, but the phrase 'unique launches' conveys a distinct purpose.

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

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

No usage guidance is provided. The 'Guidance:' line merely repeats the description rather than explaining when to prefer this tool over alternatives like shop_list_launches or how it relates to other list endpoints.

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 destructiveHint=true and idempotentHint=true; the description adds the consequence of that destructiveness — unsaved changes are dropped — which tells the agent what it loses before calling. It does not cover behavior on an already-closed or unknown session_id (error vs no-op), which would be the last needed 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?

Two short sentences, front-loaded with the action and its data-loss consequence before the sibling comparison. Nothing redundant.

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 one-parameter, no-output-schema tool with annotations covering safety and idempotency, this is nearly complete: the agent knows what it closes, what is lost, and where to go to save instead. Only edge-case behavior on invalid sessions is unstated.

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

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

Only one parameter and schema coverage is 100%, with the schema itself explaining that session_id comes from studio_open_page. The description adds no additional meaning about the parameter, so baseline 3 applies.

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

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

States a specific verb and resource ('close the session') and immediately qualifies the scope ('without saving: its changes are dropped'). It also names the sibling studio_save so the agent can distinguish the two without opening a schema.

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?

Implies the selection rule clearly: use this to abandon changes, use studio_save to persist them (since saving also closes the session). No explicit exclusion cases such as 'do not use on a session with required unsaved state', but the alternative is named and characterized.

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 non-read-only, non-idempotent, non-destructive, so the description usefully adds the failure condition (old_text must appear exactly once) and the deferred-persistence model ('Nothing is saved before studio_save'). That is real context beyond the annotations, though it doesn't say what the tool returns or how a non-unique match surfaces.

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, no filler, ordered from what the tool does to the precondition to the persistence caveat. Every sentence carries 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 mutation tool with no output schema, the description covers the critical mechanics: unique-match requirement, where to source the text, and the save boundary. It leaves error reporting and confirmation of the applied edit unstated, which is a minor but real gap.

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 only 50% (path and session_id documented; old_text and new_text bare), so description compensation matters. The description does exactly that for old_text — uniqueness rule, source, line-number caveat, and how to disambiguate — while new_text is left to obvious inference.

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 precise verb and scope: 'Replace one exact piece of text in a file of the open page,' which is meaningfully narrower than the sibling studio_write_file. It doesn't explicitly name write_file as the alternative for whole-file replacement, so the differentiation is implied rather than stated.

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?

Gives concrete sourcing instructions ('copy it from studio_read_file, without the line numbers') and the uniqueness precondition, plus the workflow gate that nothing persists before studio_save. It stops short of saying when to prefer this over studio_write_file or studio_search_in_files.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description does add genuinely useful behavioral detail beyond that — notably that API keys are returned as names only, which signals redaction and reassures the agent this is safe to call for diagnostics. It stops short of describing cost, size, or whether the payload is cached per session.

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

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

A single compact clause with no padding, and the most discriminating items (palette/fonts, API key names, backend status) come first. It loses a point only because the fragmentary phrasing reads like a field list rather than a self-contained statement an agent can act on.

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?

There is no output schema, so the description carries the full burden of describing the returned bundle — and it enumerates every component (palette, fonts, logo, key names, files, backend status, tables) in a way that lets an agent decide whether to call it. It falls short of 5 by omitting the shape and rough size of the response.

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 single session_id parameter is fully documented in the schema, including where it comes from (studio_open_page). The description adds nothing about the parameter, so the baseline of 3 applies.

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

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

The description is a noun phrase enumerating return contents rather than a statement of what the tool does — there is no verb like 'retrieve' or 'read'. The enumeration is specific enough that an agent can infer it fetches app-level context, but it never distinguishes this from siblings such as studio_list_files, studio_read_doc, or studio_run_checks, which also surface app state.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives. An agent must infer entirely from the name and the return-content list when this is the right call versus studio_list_pages or studio_list_files.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only that sizes are returned; it says nothing about pagination, recursion into subdirectories, or behavior when no page is open.

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

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

One short sentence, front-loaded with the verb and resource, and the extra detail (sizes) is appended efficiently. No filler or 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?

There is no output schema, so the description carries the burden of describing return values; it discloses only that sizes accompany files, leaving structure, ordering, and empty-page behavior unspecified. Adequate for a simple read tool but with clear 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?

Single parameter with 100% schema coverage — the schema already explains that session_id comes from studio_open_page. The description adds no further meaning about the parameter, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (files) scoped to 'the open page', which is more precise than the bare name. It is distinguishable from studio_list_pages (pages, not files) and from studio_read_file (reads content rather than enumerating), though it does not name those siblings 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?

The phrase 'of the open page' implies a prerequisite (an open page/session) but never says so directly or routes to studio_open_page or to alternatives like studio_search_in_files. Usage is inferable from context rather than stated.

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 the safety profile (readOnly, idempotent, closed-world, non-destructive), so the description's added value is scope: only studio-editable web plugin pages. It also discloses the return payload fields and that this tool cannot create pages, both of which go 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?

Three short sentences with the scope stated first, the follow-up action second, and the misuse-prevention note last. Each sentence carries distinct information and none repeats the annotations.

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-param, non-destructive list tool with no output schema, the description supplies the scope, the returned fields, and the navigation path to studio_open_page. An agent has everything needed to select and call it correctly.

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

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

Zero parameters, so the baseline is 4; there is nothing to disambiguate. The description goes slightly beyond schema obligations by enumerating the returned fields (id, name, kind, last update).

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 (list) and a narrowly scoped resource: the web plugin pages the page studio can edit, and even names the returned fields. This separates it from the cms_/shop_ list tools, though it doesn't explicitly contrast with close siblings like studio_list_files or studio_list_sections.

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?

Gives a clear next step ('Open one with studio_open_page') and rules out creation ('New pages are created in the studio itself'), which is useful when-to/when-not guidance. It stops short of saying how this differs from studio_list_files or studio_list_sections, which an agent could confuse it with.

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