AXL MCP

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

Annotations already cover the safety profile (readOnly, non-destructive, non-openWorld), yet the description adds substantial context the annotations cannot: that module names are namespace segments that 'lie about their contents', that routing by name alone fails, and that the overview is deliberately truncated to the first two traps per area. This is real, non-obvious behavioral disclosure.

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 action instruction is front-loaded ('CALL THIS FIRST'), and every sentence carries distinct information (routing hazard, area-vs-overview difference). It is dense but not padded; a slightly tighter phrasing of the trap-list distinction could improve it, keeping it just short of a 5.

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

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

With no output schema, the description carries the burden and does so: it describes the return shape (platform-wide conventions plus six areas with purpose, recipes, gotchas, and traps). An agent knows exactly what it will receive and how to 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?

Schema coverage is 100% and the schema already lists the six valid area ids, so the baseline would be 3. The description adds meaning beyond the schema by explaining the consequence of the parameter choice: passing 'area' returns the modules plus the FULL trap list, whereas omitting it yields only two traps per area.

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 purpose: an orientation/overview map of the whole Admin API, and explicitly positions it as the entry point ('CALL THIS FIRST'). This clearly distinguishes it from siblings like list_modules, list_operations, and list_recipes, which return raw listings rather than routing guidance.

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

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

Explicitly says when to use it ('before any other tool') and how to choose between its two modes: omit 'area' for the overview, or pass 'area' to get that area's full detail including its complete trap list. This is explicit when/when-not guidance with no inference required.

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/destructiveHint=false, but the description still adds substance: it enumerates what the dry run reports (unknown/misspelled properties, type mismatches), states that it returns the normalized JSON (compensating for the absent output schema), and explains the silent-acceptance failure mode that motivates the tool.

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

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

Two sentences, both front-loaded with the operative information: the action and its read-only nature come first, then the conditional guidance. No filler or restatement of the tool name.

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

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

No output schema exists, but the description covers the return value (normalized JSON plus reported problems), the safety profile, and the conditions for use. Nothing material is missing for a two-parameter validation 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 description coverage is 100%, so both parameters (payload as a JSON string, actionType as a C# class name) are already documented in the schema. The description adds no format or encoding detail beyond that, 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 and resource: dry-run/validate a scenario node payload against its config class before writing. It also distinguishes itself from the sibling get_scenario_node_schema by naming it as a companion rather than a duplicate.

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

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

Explicitly says when to call it ('BEFORE writing it') and gives a precise triage rule: prioritize node types whose schema card reports validation=NONE, because the server accepts broken payloads silently there. The alternative behavior (proceeding to write without checking) is implicitly but clearly framed as the mistake to avoid.

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 declare this a safe read operation (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the safety bar is low. The description adds mode-dependent behavior — the full catalog by default vs. a filtered list vs. a single type's payload schema — which is real behavioral information, especially with no output schema. It says nothing about error handling or result limits, keeping it out of 5 territory.

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?

It is a single sentence with a parenthetical identification of the target property, then a compact three-part enumeration of behavior modes. Front-loaded and dense with no filler. Slightly packed with parenthetical clauses, but nothing is wasteful.

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

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

With no output schema, the description carries the burden of explaining returns, and it does so by mode (type catalog, filtered catalog, single payload JSON schema). For a zero-required-parameter, two-parameter read tool this is nearly complete; only finer details of the catalog contents are left implicit.

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 both parameters ('search' over names/descriptions, 'filterType' as an exact type name) are already documented in the schema. The description's restatement of these two modes adds little semantic detail (no format rules, matching behavior, or case sensitivity) beyond what the schema provides. 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 names a specific verb+resource: it returns the format/schema of the 'extendedFilter' property of list filters, including envelope, condition enum and filter types. That is far more precise than a tautology. It does not explicitly contrast itself with siblings like get_fields_schema or get_operation_schema, so it stays at 4 rather than 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?

It spells out three invocation modes: no arguments returns the full type catalog, 'search' narrows it, and 'filterType' returns the payload JSON schema for one type. That is clear usage context. It offers no explicit when-not-to-use guidance or named alternatives among the schema-lookup siblings, so it falls short of 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), but the description adds a non-obvious behavioral contract that annotations cannot express: root scalar fields come back in full while nested entities are stubs flagged expandable=true, requiring a follow-up call with 'path'. Without this, an agent would misread a partial response as complete. It also discloses rights-based filtering of the returned fields.

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 dense sentences with no filler. The core capability and its syntax example are front-loaded, and the expansion workflow follows immediately after, so the agent hits the most decision-relevant information first.

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

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

With no output schema, the description carries the return-shape burden and does so well (scalar root fields, stub nested nodes, expandable flag, rights filtering). It is complete enough to call correctly, though it says nothing about limits on selector depth/size or failure behavior for an invalid path.

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 meaning beyond the schema by showing the 'fields' selector grammar ('{id, firstName, tags{id, text}}') and explaining that 'path' is used to expand a stub on a repeat call. The schema's own path example ('orders.product') is only slightly extended, so the gain is modest but real.

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: it returns the exact set of fields an operation's 'fields' selector supports, with a concrete syntax example. That is far more precise than a generic 'get schema' statement, but it never names or contrasts with its closest siblings (get_operation_schema, get_extended_filter_schema), so the agent must infer the boundary 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?

It gives real usage context: the result respects the current admin's rights, and nested nodes are expanded by re-calling the tool with 'path'. That tells the agent how to drive the tool iteratively. It stops short of saying when to prefer this over get_operation_schema or the filter-schema tool, so no explicit exclusions are offered.

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 safe-read profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds meaningful behavioral detail beyond annotations: nested schemas are inlined up to depth 4, deeper objects are marked truncated, large schemas are trimmed to fit, and hints/recipes are included. It stops short of discussing auth, rate limits, or the ackToken gating, which appears only in the 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?

Three dense sentences, front-loaded with the tool's output scope and then the behavioral caveats. Every sentence carries information (truncation limits, trimming behavior, section workaround) with no filler.

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

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

The description is complete for a schema-fetching tool with no output schema: it describes what the response contains (parameters, request body with schema and example, responses, hints, recipes), how nested and large schemas are handled, and how to fetch full sections. Annotations cover the safety profile, so the agent has what it needs to call this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the reason for the 'section' parameter: large schemas are trimmed, so section='request'/'response' fetches one part in full. It also identifies the source of the required operationId, providing practical meaning beyond the raw schema.

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

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

The description gives a specific verb+resource: 'Full schema of one operation' and enumerates exactly what is returned (parameters, request body, responses, hints, recipes). It clearly targets 'operation' schemas, which differentiates it from sibling schema tools for fields, filters, or scenario nodes, 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?

It provides useful workflow context by noting that 'operationId' comes from list_operations/search_operations, and it explains the 'section' escape hatch for fetching one part in full. However, it gives no explicit when-to-use versus when-not guidance relative to sibling tools, leaving usage mostly 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 only declare a safe read, but the description goes far beyond: the server stores SettingsJson verbatim, never defaults and never validates keys, a guessed blob returns HTTP 200 and only fails client-side, and the value must never be null/empty even for a separator. This is exactly the failure-mode context an agent needs.

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 with the core purpose and the imperative call-before warning, and every clause carries real information. However, the long em-dash-chained sentences pack multiple ideas together, slightly taxing readability.

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 must describe returns — and it does, covering base settings, conventions/traps, type lists, and a single type's full card with example. For a zero-required-param lookup tool with high complexity, nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, but the description adds semantics the schema cannot express: omitting all params yields shared base settings/conventions/traps, 'category'/'search' list types, and 'itemType' returns a full settings card with a ready-to-send example plus bindable system contact attributes.

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 ('Quiz/form item types and the shape of their SettingsJson') and frames the exact artifact returned. It is clearly distinguishable from sibling schema lookups like get_fields_schema or get_operation_schema by scoping to form-item SettingsJson.

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 commands 'CALL THIS BEFORE creating or updating ANY form item' and gives the consequence of skipping it. It also names the three invocation modes (no args, category/search, itemType), so the agent knows which call shape to use for which need.

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

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

With annotations declaring read-only, the description adds crucial non-obvious server behavior: default payload only for events/listeners (actions null), only 13 of 137 types type-checked, and guessed payloads accepted but break at runtime. This is exactly the context annotations cannot provide.

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

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

Front-loaded with purpose and the call-before warning, and every clause carries operational detail. The long semicolon-separated argument explanation is dense and could be better structured, but there is no wasted text.

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 present, yet the description specifies the return shape for each argument mode (graph model, node type lists, one node's schema/default/link types, trigger events). That sufficiently covers what an agent needs to 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?

Schema coverage is 100%, but the description adds meaning beyond the parameter descriptions by explaining what each mode returns (no args: graph model and workflow; outputs='fail': error-branch nodes; actionType: payload schema, default, link routing; scenarioId: accepted trigger events). This adds substantial semantic value over the schema.

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

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

States the tool returns scenario node types and the JSON schema of their polymorphic 'payload' config, and explicitly notes the OpenAPI limitation (payload typed as opaque string). This is a specific verb+resource and differentiates it from sibling schema 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?

Explicitly instructs 'CALL THIS BEFORE creating or configuring ANY scenario node' and explains the consequence of guessing (HTTP 200 then runtime break). It does not name a sibling alternative or a when-not condition, so it falls short of full 5-level routing.

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 declare the safety profile (destructiveHint=true, openWorldHint=true), and with no output schema the description adds real value by enumerating the three return shapes: success, API error with {code, type, message, hint?}, and guard refusal. It also notes that the caller's token, account context and permissions apply. It does not explain when a guard refusal fires or what triggers confirmation, but it goes well 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?

Front-loads the core action ('Execute an Admin API operation') before enumerating return shapes, then spends its remaining words on genuinely useful contract details. Dense but not padded; the long second sentence earns its place because no output schema exists.

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 destructive, open-world generic dispatcher with no output schema, the description supplies the missing return contract (success/error/guard refusal) and names the pipeline semantics. It omits the confirm and guide-ack preconditions, but those are fully documented in the schema, so an agent has enough to 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?

Schema description coverage is 100%, so the rich confirm/guideAck/operationId descriptions already carry parameter meaning. The description itself mentions no parameters and adds nothing beyond the schema, so the 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?

States a specific verb and resource ('Execute an Admin API operation through the standard HTTP pipeline'), which is clearer than a tautology and tells the agent this is the generic dispatcher. It does not explicitly contrast with sibling discovery tools like search_operations or list_recipes, but the verb+resource 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?

The description gives no when-to-use or when-not-to-use guidance, and names no alternatives. The routing workflow (capability_map -> list_recipes -> search_operations) lives only in the operationId schema field, not in the description, so an agent reading the description alone gets no usage context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the one thing the annotations can't: what the index actually contains per module (operation count, owning area, known trap), which is valuable 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, zero filler, and the routing constraint ('NOT the entry point') is front-loaded before the alternatives. The dense enumeration in sentence one is information, not padding.

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

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

With no output schema, the description compensates by describing the return contents and by placing the tool correctly in the capability_map -> list_modules/list_operations workflow. Nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies a no-argument, whole-corpus listing and never invents parameter semantics.

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

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

States a specific verb and resource ('Flat index of every Admin API module') and enumerates the exact payload fields (operation count, area, ownership, known trap). It is immediately distinguishable from capability_map and list_operations, which it names.

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 itself as a drill-down and NOT the entry point, tells the agent to call capability_map first to route, and offers list_operations(module) as the narrower alternative for a single module. Both the when and the when-not are 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 establish read-only, non-destructive, closed-world behavior. The description adds useful context beyond them: pagination is fixed at 100 and search requires every word to match operationId, path, or summary. It does not discuss permissions or response metadata.

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 tight sentences, front-loaded with the core action and followed by pagination, search behavior, and module-source guidance. No sentence is wasted.

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 lists the returned fields and states pagination size and search matching. It is nearly complete, though it does not describe pagination metadata or whether total counts are returned.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning to 'search' by specifying all-words matching across operationId, path, and summary, and clarifies where module values come from; 'page' remains covered only by schema.

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

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

States a specific verb and resource: list operations of one API module, with the returned fields named. The module scope distinguishes it from the broader search_operations sibling, so an agent can tell what it does without opening 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?

Explains that module names come from capability_map and that search filters only within the selected module. It does not explicitly say when to use search_operations instead, nor mention list_modules as an alternative module source even though the schema does.

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

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

Annotations already mark this read-only, non-destructive, and closed-world, and the description is consistent with them. Beyond that it discloses real behavior the schema cannot: search matches on intent/title/notes only, exact intent match always appears in the FULL results with further matches as stubs, and creating recipes carry a 'deadUnless' surface/connection field. That is substantive added 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?

It is front-loaded with what the tool returns, then usage, then the deadUnless caveat, and nearly every sentence carries information. It is a dense single paragraph with some run-on phrasing in the deadUnless explanation, which slightly hurts scannability, but there is little pure 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?

There is no output schema, so the description must explain returns, and it does: FULL recipes vs. stubs, what an exact match guarantees, and the extra 'deadUnless' field on creating recipes. Combined with the parameter guidance, an agent has everything needed to 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?

Schema description coverage is 100% for the single 'search' parameter, and the schema already documents the AND matching, the one-intent-per-call rule, and empty-returns-all. The description largely restates that (e.g. 'upload_file, then create_landing_site') without adding syntax or format 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 a concrete verb and resource: it serves ready-made, VERIFIED recipes that map an intent to an operationId, an example body, and convention notes. It also distinguishes itself from siblings by naming capability_map and invoke_operation, so an agent knows this is the recipe lookup rather than the operation schema lookup.

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

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

Explicit routing: capability_map names a recipe as 'recipe:<intent>', and the agent should fetch it here with search=<intent> before building the call by hand. It also states the constraint (one intent per call, AND over every word) and what happens with and without 'search', leaving nothing 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 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 already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial behavior beyond them: search returns a ranked shortlist and NOT article bodies, full reads require a second call with slugs, max 3 slugs per call, English-only articles, and the no-argument/section listing 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?

Long but tightly structured and front-loaded: identity, use/don't-use, then a numbered two-step procedure. Every clause carries information (scope, sourcing of slugs, limit, language constraint) with no filler or restatement 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 no output schema, the description compensates by describing the return shape of a search (title, UI section, article summary, matched snippet) versus a full read. Combined with the usage routing and slug-sourcing rules, an agent has everything needed to call both modes correctly.

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

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

Schema description coverage is 100%, so the schema documents all four parameters, but the description still adds cross-call semantics the schema cannot: that slugs should come from a previous search's 'slug', a recipe's docs[].slug, or a docs.axl.tech URL, and that query+slugs are the two halves of a workflow rather than independent filters.

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 (search/read) and resource (AXL product documentation), and explicitly distinguishes itself from the API-side siblings by naming capability_map, list_recipes and get_operation_schema. An agent can tell immediately this is the product-docs tool, not the API tool.

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

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

Gives explicit when-to-use ('PRODUCT questions the API surface cannot answer: what a feature is, which flow it belongs to, business rules, UI naming') and when-not-to-use, routing API questions to named alternatives. The TWO STEPS block dictates the exact call sequence.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds real behavior beyond that: results are ranked by relevance, and zero-result responses report which query words failed to match. It stops short of describing pagination or the result object shape, but the behavioral disclosure is well above 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?

Three sentences, front-loaded with the core action and match rules before the routing caveat. Every sentence carries information, though the final sentence's trade-off explanation is slightly long relative to the rest. Nothing is boilerplate.

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

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

With no output schema, the description carries return-value burden and does so partially: it discloses relevance ranking and the diagnostic content of empty results. Annotations cover the safety profile. It could say more about the fields present in each returned operation, but for a two-parameter search tool the coverage is solid.

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 earns the extra point by explaining query semantics the schema does not: matching is order-insensitive, applies to five specific fields, and is API vocabulary rather than business vocabulary. The 'limit' parameter is left to the schema, which is acceptable given full 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?

States a specific verb ('Search') and resource ('operations across all API modules'), then goes further by naming exactly which fields are matched (operationId, path, module, summary, request-body property names). It explicitly distinguishes itself from capability_map, so an agent can route between 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?

Gives an explicit when-not-and-use-alternative: if the request is phrased in user vocabulary, capability_map routes it faster. It also states the two positive conditions for coming here (no area fits, or you already know the API's word). This is the rare definition that fully resolves the routing decision.

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