AXL MCP

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

Annotations already mark it read-only, and the description adds meaningful behavioral detail: the overview contains only the first two traps per area, while passing an area returns full trap lists and module recipes. This clarifies an important limitation an agent could not infer from the schema alone.

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

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

The description is dense but every sentence earns its place: the imperative call-first rule, the tool's purpose, the module-name warning, and parameter behavior. It is front-loaded and structured, though slightly long-winded in the middle.

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

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

For an orientation tool with one optional parameter, no output schema, and a read-only annotation, the description covers what an agent needs: when to call it, what it contains, why it is necessary, and how to use 'area' to get deeper details. Nothing critical is missing 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?

Schema coverage is 100% and the schema already documents the 'area' parameter and its allowed values. The description adds extra meaning by explaining that omitting it yields the overview and that passing it returns that area's modules, gotchas, recipes, and full trap list, going beyond the schema's basic wording.

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 explicit: this is an orientation map of the whole Admin API, with platform-wide conventions, six task areas, and first-call recommendations. It clearly distinguishes itself from the sibling operation tools by saying it must be called first and that module names alone are misleading.

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

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

It gives an explicit ordering instruction: 'CALL THIS FIRST, before any other tool.' It also tells the agent when to pass 'area' versus omit it, and warns that routing by module name fails, which is direct guidance for choosing this tool over searching or invoking operations directly.

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

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

Beyond the readOnlyHint annotation, the description adds meaningful behavioral detail: nothing is created or changed, it reports unknown/misspelled properties and type mismatches, it returns normalized JSON, and it warns that the server silently accepts broken payloads when validation=NONE. This gives the agent a realistic model of the tool's behavior without contradicting any annotation.

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

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

Three sentences with no fluff: the first sentence states the action and results, the second states safety, and the third gives concrete usage guidance. The most important information is front-loaded.

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

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

For a low-complexity tool with two simple parameters, present annotations, and no output schema, the description covers purpose, behavior, return value, and usage context. An agent has enough to decide whether and how to invoke it correctly.

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

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

The schema already describes both parameters clearly and completely (payload string and actionType string), so the baseline is 3. The description ties the parameters to the tool's purpose, calling payload 'the payload JSON you intend to send' and actionType 'Node type (C# class name)', but does not add substantially beyond the schema's descriptions.

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

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

The description uses a specific verb, 'Dry-run', and clearly identifies the resource: a scenario node payload checked against its config class before writing. It also distinguishes itself from siblings by stating exactly what it reports and what it returns, so an agent can tell it apart from schema and operation 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 gives explicit guidance on when to call the tool: before writing a payload, especially for nodes whose get_scenario_node_schema card says validation=NONE. It explains the consequence of not calling it in that situation, though it does not explicitly state when not to use it or name an alternative tool for validation.

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 are minimal generic hints (readOnly=false, openWorld=true, idempotent=false, destuctive=false). The desciption adds the load-bearing behavioral facts: the operation is Billed, requires confirmSpend=true only after a REAL human yes in a SEPARATE message, stores the result, and must not be retried on spending exhaustion. 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?

Front-loaded purose, then the billing gate, then the two mode branches, then failure handling and quality. Scannable typography (caps, arrows, em-dashes) keeps dense information parseable. Every clause carries operational weight and none of it repeats what the input schema already states.

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 desciption discloses the return (image_url + markdown preview). For a billed 6-parameter mutation it also covers storage location, the human-approval sequence, post-success actions (SHOW / place URL on page), and the spending-exhaustion path. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The desciption adds meaning above the schema by explaining interdependencies: the forPage/sitePageId pair resolves the storage path, confirmSpend has an ordering requirement (separate-message human approval of prompt+quality+charge), and quality tiers are restated. Genuine added value, though not every param (e.g., style) is elaborated.

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?

Opens with a specific verb+resource+output: 'Generate a BRAND-NEW image via Gemini; stores it and returns image_url (+ markdown preview).' It names the engine, the side effect, and the return shape, and the 'BRAND-NEW' phrasing explicitly contrasts with the sibling regenerate_image so an agent can distinguish them without opening either 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?

Carves out the two usage modes explicitly: STANDALONE (omit sitePageId → account-root AI folder; SHOW the image after success) and PAGE/SITE (forPage=true AND sitePageId=<page id> → Sites/{site}/{page}/AI; propose prompt+quality+charge first). It also gives a when-not: 'On aiSpendExhausted: warn + Billing — do not retry.' The only implicit branch is regenerate_image for existing images, but 'BRAND-NEW' already signals that boundary.

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

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

Annotations already mark it read-only; the description adds meaningful behavioral detail: the output changes based on arguments, the no-argument case returns a full catalog, and 'filterType' returns a JSON schema. This goes beyond what annotations alone convey.

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

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

A single dense sentence that front-loads the core purpose and then lists the three usage modes without wasted words. Every clause earns its place.

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

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

For a read-only schema-introspection tool with no output schema, the description fully covers what an agent needs: what the tool returns, how to request each variant, and how parameters affect the response. Minor details like error handling for unknown filterType are not essential given the tool's simplicity.

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

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

Schema coverage is 100% with clear parameter descriptions and examples. The description adds value by explaining how each parameter transforms the result (catalog vs. filtered list vs. single-type schema), which the schema alone does not fully convey.

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 resource ('extendedFilter' property of list filters) and the tool's job: returning a type catalog, filtered catalog, or per-type payload schema. It clearly distinguishes this introspection tool from unrelated sibling tools like image generation and operation listing.

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

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

The description explicitly explains the three invocation modes: no arguments for the full catalog, 'search' for filtering, and 'filterType' for a single type's payload schema. It does not name alternatives, but no sibling tool offers this functionality, so the usage context is sufficiently 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 mark the tool as read-only, but the description goes well beyond that: it discloses that the result respects the current admin's rights, root entities return full scalar fields, nested entities are stubs with expandable=true, and expansion requires re-calling with 'path'.

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

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

Two sentences deliver the core purpose, syntax example, permission sensitivity, return behavior, and expansion workflow. Every sentence carries necessary information, and the key concept is front-loaded.

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

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

For a two-parameter introspection tool with read-only annotations and no output schema, the description adequately covers what the tool returns, how nested expansion works, and how it respects permissions. No critical behavioral gap remains.

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

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

Schema coverage is 100%, so both parameters are already documented. The description adds meaningful context, particularly explaining how 'path' relates to re-calling for nested expansion and reinforcing the syntax style. This goes slightly beyond the schema's literal property descriptions.

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

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

The description names a specific resource ('the operation's 'fields' selector') and states the exact behavior: returning the supported field set with GraphQL-like syntax. It is clearly distinguishable from sibling tools like get_operation_schema or get_extended_filter_schema because it focuses exclusively on the 'fields' selector and its expansion mechanics.

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

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

The description implies when this tool is relevant—when a caller needs the exact fields for an operation's selector and wants to expand nested entities—but it never explicitly names alternatives or states when not to use this tool. The contrast with siblings is not articulated, so the agent must infer routing from the narrow wording.

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

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

Beyond the readOnlyHint annotation, the description discloses concrete truncation and inlining behavior: nested schemas are inlined up to depth 4, deeper objects are marked truncated, and large schemas are trimmed. This is exactly the kind of non-obvious behavior an agent needs before relying on returned data.

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

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

Two sentences front-load the primary purpose and follow with essential caveats. Every clause adds information; there is no filler or repetition of the schema.

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

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

For a read-only introspection tool with no output schema, the description covers what the agent receives, how deep nested schemas go, and how to retrieve trimmed content in full. Combined with the annotated parameters, nothing critical is missing 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?

Schema description coverage is 100%, so the schema already documents operationId and section thoroughly. The description only restates the request/response section usage without adding new parameter-level semantics, so baseline 3 is appropriate.

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

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

Description names the resource ('Full schema of one operation') and enumerates exact content: parameters, request body with schema and example, responses, hints, and recipes. This clearly distinguishes it from sibling schema tools like get_fields_schema by anchoring to an operationId.

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 conditional usage guidance: when schemas are trimmed, use section='request'/'response' to get a complete part, and the input schema ties operationId to list_operations/search_operations. It does not explicitly name alternative tools or exclusions, but the intended 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 only declare readOnlyHint=true and openWorldHint=false; the description carries the real behavioral burden and does so thoroughly. It discloses the server's verbatim storage, absence of defaults/validation, the HTTP-200-with-broken-browser failure mode, and the never-null/empty constraint even for separators. It also reveals what each call mode returns, including the ready-to-send example and system contact attribute bindings for itemType.

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

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

The description is a single dense paragraph of roughly 130 words, which is justified given the subtle failure modes it must convey. It is front-loaded with the core purpose and every clause earns its place (storage trap, null/empty rule, invocation modes). Slight penalty for the wall-of-text structure; short section breaks or bullet-like phrasing would improve scannability.

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 full responsibility for explaining return values — and it does, covering the shared base settings/conventions/traps, the type-listing modes, and the full settings card with example and bindings. It also covers the critical failure behavior and constraints. For a read-only introspection tool with this complexity, nothing essential is missing.

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

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

Schema coverage is 100% (search, category, itemType all have descriptions), so the baseline is 3. The description adds value on top by explaining what each parameter mode returns: category/search list types, while itemType returns a full settings card with example and contact-attribute bindings. This semantic mapping is not present in the schema descriptions.

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

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

The description identifies a specific resource (quiz/form item types and their SettingsJson shape) and a distinct purpose: retrieving the schema needed before creating or updating form items. The directive 'CALL THIS BEFORE creating or updating ANY form item' anchors the tool's role clearly, and its focus on the opaque SettingsJson string distinguishes it from the sibling schema tools like get_fields_schema and get_operation_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?

Provides an explicit when-to-use directive with a concrete rationale: the server stores SettingsJson verbatim, never validates keys, and accepts bad blobs with HTTP 200, so this tool must be called before any form-item write. It also documents the three invocation modes (no args, category/search, itemType). It does not name sibling alternatives or give exclusions, but the context and prerequisite nature are unambiguous.

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

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

Beyond the readOnlyHint annotation, the description discloses important runtime behaviors: actions come back with null default payloads, only 13 of 137 node types are type-checked, guessed payloads are stored with HTTP 200 and fail later, and each argument mode changes what is returned. It also clarifies the critical link-type routing detail for actionType. 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 dense but every sentence earns its place: purpose, critical usage warning with rationale, and per-parameter behavior are all covered in a tight structure. The most important call-before guidance is front-loaded ahead of optional parameter details.

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

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

Given that no output schema is present, the description supplies the needed return behavior for the main invocation modes: no arguments returns the graph model and workflow; outputs='fail' identifies error-handling targets; actionType returns payload schema, default payload, and link types; scenarioId returns accepted trigger events. It also explains the key risk that motivates the tool. No critical gap remains.

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 100% description coverage, so the baseline is 3. The description adds meaningful semantics beyond the schema: outputs='fail' maps to attachable error-handling steps, actionType returns the payload schema plus default payload plus routed link types, and scenarioId returns accepted trigger events for that scenario.

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 names the resource: scenario node types and the JSON schema of their polymorphic payload configuration. It immediately distinguishes this from sibling schema tools by focusing on scenario nodes and explains why the OpenAPI schema cannot cover the payload shape. The imperative 'CALL THIS BEFORE creating or configuring ANY scenario node' makes the purpose immediately actionable.

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 a clear, explicit when-to-use instruction: call before creating or configuring any scenario node, with concrete reasons involving default payloads, type-check coverage, and silent HTTP 200 failures. The description does not explicitly compare against sibling tools such as check_scenario_node_payload, so alternative selection is left partly implicit.

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 meaningful behavioral context beyond annotations: it is SSRF-guarded, incurs no Gemini charge, stores at account-root or sitePage-specific path, and returns image_url plus preview. These details help an agent anticipate side effects and constraints without contradicting any annotation.

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

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

The description is three concise sentences with no wasted words, front-loding the core action and key differentiator (external, no Gemini charge) before optional routing details.

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

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

For a simple 3-parameter tool with a full schema and no output schema, the description covers purpose, return value, storage behavior, security guard, and cost implication. It could name sibling alternatives explicitly for fully complete routing, but nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters accurately. The description adds a useful routing explanation for sitePageId but does not need to expand the url or name parameters further.

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

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

The description uses a specific verb and resource: imports an external http(s) image into account storage, and distinguishes itself from sibling generation tools via 'EXTERNAL' and 'no Gemini charge'. It also states the return value, image_url + preview, and the optional storage routing.

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 defines when to use this tool: to import an external image rather than generate or regenerate one. It provides context about account storage and the no-Gemini-charge benefit, but it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations only provide destructiveHint: true and readOnlyHint: false. The description adds valuable behavioral detail: caller's token/account context/permissions apply, success returns {success: true, body: ...}, API errors return a structured errors array, and guard refusals return {error, details?}. This goes well beyond the annotations without contradicting them.

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

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

The description is a single dense, well-structured sentence that front-loads the core purpose and then compactly specifies the three possible return shapes. Every clause earns its place; there is no filler or repetition of schema 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?

There is no output schema, so the description correctly carries the return-contract information. It covers success, API errors, guard refusals, statusCode nuance, caller context, and the destructive/confirmation flow via the confirm parameter. Together with the schema, an agent has enough to call this tool correctly in most scenarios.

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

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

Schema description coverage is 100%, and each parameter has a meaningful description already (e.g., confirm's safety rules, guideAck's requirements, operationId's look-up workflow). The main description does not add parameter-level semantics 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 a clear action ('Execute') and a clear resource ('an Admin API operation'), and adds that it goes through the standard HTTP pipeline with the caller's token and permissions. It is not as specific as sibling tools like 'get_operation_schema' or 'list_operations', but it accurately identifies itself as the generic execution entry point. It earns a 4 rather than a 5 because it does not explicitly contrast itself with the listed sibling 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 gives solid context: this is the tool for running Admin API operations, and the operationId parameter description reinforces the workflow by pointing to capability_map -> list_recipes -> search_operations and warning that a recipe intent is not an operation id. It does not explicitly state when to avoid this tool or name alternatives, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context beyond that: the tool returns a flat index, includes metadata like area and ownership, and surfaces a 'known trap' per module. It also clarifies its role in the navigation flow. Slight deduction for not describing the exact response shape, since there is no output schema.

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

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

Two sentences carry substantial information: what the tool returns, its role, and the routing rule. The core purpose is front-loaded, and every clause earns its place. No filler or repetition of the name.

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

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

With zero parameters and a readOnly annotation, the only open question is what results look like; the description answers that by listing the elements of the index and by linking the tool into the larger workflow (capability_map first, list_operations for a single module). An agent can invoke and interpret this correctly without additional information.

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

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

The tool has zero parameters, so schema-only semantics are irrelevant. The description correctly focuses on what the tool returns rather than inputs, which is the right burden given the empty schema. A 4 matches the baseline for parameterless tools.

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

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

The description opens with a specific verb and resource: 'Flat index of every Admin API module,' and enumerates exactly what it provides (operation count, area, ownership, known trap). It also explicitly contrasts itself with sibling tools (capability_map, list_operations), making it unmistakable what this tool is for.

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 direct routing guidance: it is a drill-down, NOT the entry point, and tells the agent to call capability_map first. It also names the alternative for per-module operation listing (list_operations(module)), so when-to-use vs. when-not-to-use is fully explicit.

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

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

Adds concrete behavior beyond the readOnlyHint annotation: page size of 100 and the strict search matching rule (every word must match operationId, path, or summary). Also points the agent to capability_map for module ownership and trap locations, which is actionable context.

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

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

Three dense sentences with no filler; the core output fields and pagiation are front-loaded, followed by filtering behavior and module-name provenance. Every sentence contributes 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 read-only list tool with 100% schema coverage, the description supplies output shape, pagiation behavior, search semantics, and module-name source. No critical invocation information is missing, and there is no output schema that would otherwise document return values.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by defining search word-matching semantics and clarifying that module names come from capability_map/list_modules. This meaningfully disambiguates 'search' beyond the schema's generic phrasing.

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 lists operations of one API module and enumerates the returned fields (operationId, HTTP method, path, summary). The 'one API module' scoping distinguishes it from sibling search_operations without needing to open the 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?

Provides clear context: use on a single module, paginated by 100, optional in-module search. It names capability_map as the source of valid module names and notes what each module owns and where its traps are. It does not explicitly say when to prefer search_operations over this tool, but the module-scoped wording implies 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?

Beyond the readOnlyHint annotation, the description discloses rich behavior: AND-over-words search, full recipes for close matches with an exact-intent guarantee, stubs for other matches, the deadUnless field on creating recipes, and the note that the same text appears on invoke_operation results. This is substantial value added over the annotations and schema.

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

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

The description is dense but front-loaded with the core purpose and the most critical search contract. Later sentences add distinct behavioral facts about output format and deadUnless. The single long paragraph with several parenthetical asides makes it slightly heavier to parse than ideal, but every sentence earns its place.

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

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

Given there is no output schema, the description fully covers what an agent needs: input semantics, search behavior, result shape, exact-match guarantee, and the meaning of deadUnless. It also ties the tool into the larger workflow by referencing capability_map and invoke_operation, so the agent can use it correctly without external documentation.

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

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

The only parameter, search, is thoroughly explained: it is optional, one intent per call, every word must match, empty returns all, and the presence or absence of search changes the result shape between full recipes and stubs. This goes well beyond the schema's 'search over recipe intent/title/notes' description.

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

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

The description opens with 'Ready-made, VERIFIED recipes: intent -> operationId + a correct example body + notes...', naming the exact verb, resource, and output. It also distinguishes itself from capability_map by explaining that capability_map merely names 'recipe:<intent>' and that the actual recipe is fetched here.

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

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

It gives explicit when-to-use guidance: 'fetch it here with search=<intent> before building that call by hand.' It also provides a firm constraint: ONE intent per call because search is AND-over-words, preventing a common misuse. It does not explicitly enumerate alternatives to prefer in other cases, 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 only declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false and say nothing about cost. The description discloses the two most critical behavioral traits: this is a BILLED operation that REQUIRES confirmSpend=true, and it stores a NEW file — which explains why destructiveHint=false despite the mutation. It also promises a concrete return (image_url + markdown preview) and rules out a side effect (no HTML patching). 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?

Four telegraphic sentences, each carrying a distinct fact: core behavior, return value, billing gate, and the two usage modes. The core edit/restyle behavior is front-loaded before caveats. The PAGE/SITE vs STANDALONE shorthand is dense but efficient — no sentence is redundant or filler.

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

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

For a billed, high-stakes mutation tool with no output schema, the description covers everything an agent needs to invoke it correctly: what it does, what it returns, the billing gate, the two invocation contexts, and what it deliberately does not do. The schema's confirmSpend human-approval requirement complements the workflow guidance. Missing error/rejection behavior is a minor omission against this level of 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?

Schema covers 100% of parameters with individual descriptions, so the baseline is 3. The description adds value by encoding workflow semantics: it binds forPage + sitePageId together for site edits, elevates confirmSpend to a hard gate ('REQUIRES confirmSpend=true'), and orders the flow as propose edit+quality+charge first. Minor gap: 'charge' is referenced but is not a named parameter, leaving the term slightly undefined.

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+resource pair ('Edit/restyle an existing image') and immediately differentiates from siblings: it stores a NEW file (vs generate_image creating from scratch), returns image_url + markdown preview, and explicitly says it does NOT patch site HTML. An agent can distinguish this from generate_image and import_image_from_url without opening schemas.

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

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

Provides clear invocation context for the two modes — PAGE/SITE (forPage=true + sitePageId, propose edit+quality+charge first) versus STANDALONE (show the new image) — plus the required workflow ordering (propose before confirmSpend). However, it never names a sibling like generate_image as the alternative for creating new images, so when-not-to-use is implied rather than explicit.

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

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

Annotations only declare readOnlyHint=true and openWorldHint=false, which is minimal. The description carries the burden and does a strong job: it discloses the two-phase behavior (search returns shortlist only, never bodies; reading requires a second call with slugs), the max-3-slugs constraint, the English-only limitation, and that results include title, UI section, summary, and matched snippet. This is exactly the kind of behavioral context annotations cannot convey.

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

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

The description is dense but high-value. Almost every sentence adds a distinct piece of information: scope, exclusions, two-step workflow, section listing, English-only. The 'TWO STEPS' block is clearly structured and front-loaded. It is somewhat long, but for a tool with four parameters and a non-obvious two-phase behavior, the length is justified.

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 search tool with zero required parameters, a 100% schema-described parameter set, and no output schema, the description provides everything an agent needs to decide whether to call it and how to call it correctly. It even includes the exclusion guidance needed to pick among 14 siblings. The English-only caveat is a nice completeness touch.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful value beyond the schema: it clarifies the semantic difference between query (shortlist only) and slugs (full articles), explains where slugs can come from (previous search, recipe docs[].slug, docs URL), and describes the section parameter's behavior when combined with no query. It misses only a small detail like the exact section names available, which the schema already gives examples of.

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+resource (search the AXL product documentation) and explicitly scopes what it covers (product questions, business rules, UI terminology) versus what it does NOT cover (the API). It also differentiates itself from siblings like capability_map, list_recipes, get_operation_schema, and search_operations by naming them as the correct tools for API-level questions.

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

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

The description provides explicit when-to-use guidance ('Use it for PRODUCT questions the API surface cannot answer') and explicit when-not-to-use guidance ('It does NOT document the API — for operations, bodies and field semantics use capability_map / list_recipes / get_operation_schema'). It also gives a concrete two-step invocation pattern and a no-argument/section-listing alternative.

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

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

Adds meaningful behavior beyond the readOnly/openWorld annotations: every word must match, order is irrelevant, results are relevance-ranked, and zero-result responses disclose which words didn't match. 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?

Four sentences, dense and front-loaded: scope first, then matching rules, then behavioral outcomes, then usage guidance. There is no padding or repetition; each sentence adds information the agent cannot infer from the schema alone.

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

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

Given no output schema, it would be slightly stronger to explicitly state that results are operation definitions/metadata. However, 'Search operations' plus the matched fields and ranking/zero-result behavior make the return shape sufficiently inferrable. This is a minor gap, not a functional one.

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

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

The schema already documents both parameters at 100% coverage. The description nonetheless adds real value for 'query' by defining exactly what kinds of fields must match and the all-words constraint. 'limit' receives no extra detail, but that is acceptable because its schema description is already complete.

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: 'Search operations across all API modules.' It then enumerates the exact fields matched (operationId, path, module, summary, request-body property name), which distinguishes it from generic search tools and siblings like search_docs.

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

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

Explicitly tells the agent when to use it: when no area fits or when the API's own vocabulary is already known. It also names the alternative, capability_map, and explains why user-phrased requests should go there instead. This is unusually clear routing guidance.

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