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

With no annotations present, the description carries the full burden, and it reveals key behavioral details: it is a read-only status check, accepts optional Basic auth credentials, and returns a structured dict with verified, email, api_key_count, credits_remaining, uploads_remaining. It does not mention potential errors or rate limits, but for this tool the core behavior is well disclosed.

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

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

The description is compact and front-loaded: purpose sentence, usage context, concise Args, and Returns. There is no filler or repetition of schema 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 two-parameter status-check tool with an output schema, the description covers when to invoke it, how to authenticate in both modes, parameters, and return fields. Nothing essential 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 0%, so the description must compensate; it does by defining email and password as Basic auth credentials obtained from create_account, and by stating that omitting both falls back to the configured API key. This adds meaning well beyond the bare schema field names.

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 ('Check') and a concrete resource (account verification status, credit balance, API key count). It clearly differentiates this from sibling tools like get_balance or create_account by covering a distinct account-status read.

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 to use after create_account to poll verification-link clicks, and explains the two auth modes (Basic auth with email/password vs omitting both for API key). It does not list when-not-to-use cases or alternatives, but the provided context is sufficient for typical selection.

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 no annotations provided, the description carries full behavioral weight and succeeds: it discloses that the tool returns a `checkout_url` the user must open, that credits are provisioned automatically via webhook, and that failures return `email_not_verified`, `auth`, or `failed` errors. This gives the agent accurate expectations about side effects and outcomes beyond any schema information.

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

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

The description is well-structured and front-loaded: it opens with the core purpose, then covers the URL flow, the alternative routing, arguments, and return/error behavior. Every section contributes necessary decision-making information without 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 checkout tool with an output schema and no annotations, the description covers the full call cycle: inputs, user action required, automatic credit provisioning, and failure modes. The agent has enough context to decide whether to use this tool and what to expect when invoking it.

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

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

Schema description coverage is 0%, so parameter explanations in the description are essential. All three parameters are addressed: `product_id` is sourced from `get_products`, and `email`/`password` are tied to Basic auth during onboarding. However, the description doesn't fully clarify when `email` and `password` are needed or what specific auth failures they prevent, so it is helpful but not exhaustive.

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

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

The description states a specific verb and resource: 'Create a Stripe checkout session for purchasing a product.' It also distinguishes itself from the sibling `generate` tool by explaining that on-chain payment should use `generate` instead, which makes the tool's role 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 explicitly tells the agent when to skip this tool: 'If the agent has a USDC wallet, skip this entirely — just call `generate`.' It also instructs that `product_id` comes from `get_products`, giving a clear dependency between sibling tools. This is strong when-to-use vs alternative guidance.

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

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

With no annotations present, the description carries the full behavioral disclosure burden and succeeds: it details the local-server persistence path (~/.config/maginary/api_key, chmod 600, survives restarts), the hosted-server non-persistence behavior (persisted: false, per-request Authorization: Bearer header), and the confirmation response shape. This is rich, actionable behavioral context.

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

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

The description is front-loaded with the core purpose and ordering in the first two sentences, and the local/hosted distinction is logically grouped. It is slightly verbose with the Args/Returns block, but every sentence delivers necessary operational information, so 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?

Given the environment-dependent complexity (local vs hosted persistence), the description is complete: it covers ordering, input provenance, file paths, permissions, restart behavior, per-request auth headers, and the persisted:false response flag. An output schema exists to document the return value, so return-detail omission is acceptable.

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

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

Schema coverage is 0% — the schema only labels api_key as a required string. The description compensates fully by specifying the exact provenance: 'The full API key string returned by manage_api_key.' An agent knows precisely what value to pass and where to obtain it, which is the critical semantic the schema fails to 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 opens with a specific verb+resource pair ('Activate an API key') and clearly distinguishes itself from the sibling manage_api_key by framing this tool as the activation step that follows key creation. The sequencing reference ('Call this after manage_api_key(action='create') returns a raw_key') makes the tool's role 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?

Explicit when-to-use guidance is provided: call this after manage_api_key(action='create') returns a raw_key. It also names the prerequisite sibling tool and explains environment-specific setup requirements. However, it does not state when-not to use it or enumerate alternative tools besides the implicit manage_api_key reference.

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?

No annotations are present, so the description carries full responsibility for behavioral disclosure. It reveals that the password is auto-generated and displayed only once, that verification is required before account activation, and that failures return isError results with specific error meanings such as already_exists, rate_limited, and failed.

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

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

The description is well-structured and front-loaded: action, immediate output warning, verification prerequisite, follow-up API steps, then error handling. Every sentence contributes necessary operational information 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 fully covers the account creation flow, including the one-time password display, verification requirement, subsequent API key steps, and detailed failure modes. This is sufficient for an agent to invoke the tool correctly and know what to expect at each step.

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, email, is described as 'The user's email address,' which does not add significant meaning beyond the input schema's title. Since schema description coverage is 0%, this minimal description is acceptable but does not enrich the parameter with format, validation, or behavioral constraints.

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: create a new Maginary account for an email address. It clearly differentiates itself from sibling tools like check_account_status, manage_api_key, and configure_api_key by defining its role as the account-creation entry point.

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

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

Provides explicit workflow guidance: show the returned password once, require email verification before image generation, then use manage_api_key(action='create') followed by configure_api_key. It also tells the agent how to handle the 'already_exists' failure by asking the user for their password or a different email.

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 no annotations, the description fully carries the behavioral burden and does so thoroughly: it discloses async completion (uuid to poll), no-exception error style (isError result, nothing raised), auth/payment failure modes, webhook signing, and the x402 settlement flow. No behavioral surprises are hidden.

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 content is front-loaded and labeled clearly (Args/Returns/errors/x402), but the description is extremely long, largely due to an exhaustive 35-flag enumeration that partly duplicates the get_parameter/search_parameters tools. It earns its detail for safety, but is not appropriately sized and could be tightened by delegating the full list.

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 mutable, two-parameter generation tool with no annotations, the description provides a complete operating manual: return fields, all error branches, billing and payment handling, x402 integration, flag constraints, and callback behavior. 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 0%, and the description compensates completely: prompt format, flag placement, examples, common flags, and the lookup rule for unknown flags are all covered; callback_url gets a definition, HTTPS requirement, and webhook documentation link. Every parameter acquires meaning beyond its bare schema type.

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

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

The description opens with a specific action and resource ('Kick off a generation via POST /api/gens/') and makes clear this creates a generation rather than inspecting one. The return contract (uuid for polling) further distinguishes it from sibling tools like get_generation and wait_for_generation.

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 strong usage context: prompts carry flags, flags go at the end, unknown flags must be looked up via get_parameter/search_parameters first, and callback_url is optional for webhook notifications. It stops short of explicitly naming when-not-to-use alternatives, such as 'use get_generation or wait_for_generation instead of calling generate again to check status,' so it doesn't reach 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?

With no annotations, the description carries the behavioral burden. It identifies the operation as a read-only balance check, specifies that credentials use Basic auth, and names the exact return fields, giving the agent a clear picture of expected behavior.

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

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

The description is brief and well organized with Args and Returns sections. Every sentence contributes necessary information, and there is no repetition of the input 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 simple read-only balance tool, the description is largely complete: purpose, auth context, and return keys are all covered. The only notable gap is the lack of guidance around optional credentials and behavior when authentication is absent.

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

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

Schema coverage is 0%, so the description must add meaning. It does explain that both email and password are for Basic auth, but it does not address why they are optional, what happens if omitted, or how to obtain/format them.

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 states a specific verb 'Check' and a precise resource: remaining credits and uploads for the authenticated account. This clearly distinguishes it from siblings such as check_account_status, generate, or get_generation.

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

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

The description explains what the tool does but provides no guidance on when to use it versus alternatives, nor any exclusions. With siblings like check_account_status, an explicit usage note would help disambiguate.

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 no annotations provided, the description fully carries the behavioral disclosure burden. It excellently does so by explaining terminal vs. non-terminal states, the structure of image_urls and processing_result.slots, and the critical edge case that a server-side failure returns a successful tool call with processing_state: 'failed'. It also documents an optional hosted API key meta parameter.

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

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

The description is well-structured with clear sections (Fetch, Args, Returns, NOTE, Hosted) and every sentence adds value. It front-loads the core purpose and endpoint, then provides necessary behavioral caveats without 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?

The tool is simple (one parameter, no nesting), and while an output schema exists, the description still enriches understanding of return semantics and failure modes. It covers parameter origin, expected result shape, critical state-checking guidance, and auth metadata—everything an agent needs to invoke this tool correctly in context.

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

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

Schema description coverage is 0%, so the description must compensate. It does by explaining that uuid is 'The UUID returned by generate', giving the agent the provenance and expected value of the only parameter. It also mentions the optional _meta key for hosted sessions, adding useful context beyond the bare schema type.

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

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

The description starts with a specific verb and resource: 'Fetch a generation by UUID' and even includes the exact API endpoint. This clearly distinguishes it from siblings like 'generate' (which creates) and 'wait_for_generation' (which waits), and the UUID-based scope makes its role unambiguous.

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

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

The description provides clear context by explaining that the uuid comes from the 'generate' call, which tells the agent when to use this tool. It also advises checking processing_state rather than assuming success. However, it does not explicitly name alternatives or state when not to use this tool vs. siblings like wait_for_generation.

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 no annotations provided, the description carries the burden of behavioral disclosure. It discloses the return type ('parameter dict') and the error behavior (not-found is an 'isError' result, to be surfaced rather than fabricated), which is useful and goes beyond the schema. It doesn't mention auth, rate limits, or explicitly state read-only behavior, but for a simple getter the key behaviors are covered.

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

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

The description is compact and well-structured with an opening purpose sentence followed by Args and Returns sections. Every sentence adds needed information, with no filler or repetition.

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

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

For a single-parameter lookup with a single required argument and an output schema present, the description covers input semantics, return value, and not-found handling. It could optionally note when to prefer list_parameters or search_parameters, but this is a minor gap rather than a missing essential detail.

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

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

Schema description coverage is 0%, so the description must fully explain the parameter, and it does. It explains that 'name' accepts canonical names or aliases, with or without leading '--', is case-insensitive, and provides concrete examples. This is stronger than typical schema text.

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

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

The description clearly states the action ('Return the full record') and the resource ('a single parameter'), and it narrows the scope by mentioning canonical names and aliases. It implicitly differentiates from list_parameters and search_parameters as a direct single-record lookup, though it doesn't explicitly name those alternatives.

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

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

There is no explicit guidance about when to use this tool versus list_parameters or search_parameters. The phrase 'single parameter' weakly implies direct lookup by name, but no conditions, exclusions, or alternative tool mentions are provided.

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

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

With no annotations provided, the description carries the full burden and handles it well. It discloses that no authentication is needed, describes the exact return shape including the wrapped dict versus bare backend array, and explains the FastMCP validation motivation. This is exemplary behavioral context.

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

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

The description is concise and well-structured, front-loading the core purpose and pricing context before the return format. The return-format note is technical but earns its place because the wrapping behavior is non-obvious and important for callers.

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 zero parameters and an output schema, the description is complete: it explains purpose, authentication, purchase-context usage, recommended product, and the exact return contract. Nothing needed for correct invocation is missing.

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

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

The tool has zero parameters, so there is no parameter semantics burden for the description to carry. The description appropriately focuses on output and usage rather than parameter details.

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

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

The description clearly states the verb and resource: 'List available Maginary products/plans with pricing.' It also distinguishes its purpose from the sibling tools by framing it as the way to present purchase options, which no sibling tool covers.

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

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

The description explicitly says when to use the tool ('Use this to present purchase options to the user') and notes that no authentication is required. It does not name exclusions or alternatives, but given the sibling set, the intended use is clear and 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?

No annotations are provided, so the description carries the behavioral disclosure burden. It covers filtering behavior, the effect of include_reserved, the response structure, and the important live vs. bundled-snapshot source distinction. It does not mention auth requirements or rate limits, but these are not implied by the tool's read-only listing nature.

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

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

The description is well-structured with Args and Returns sections, front-loads the purpose, and avoids filler. It is slightly repetitive around the 'unimplemented' status concept across status and include_reserved, but remains efficient.

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

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

For a listing tool with no required parameters and an output schema available, the description covers the key call patterns, filter semantics, and return keys. It does not discuss pagination or entry-level details of the parameters array, but the output schema likely covers those, and the description provides enough to invoke the tool correctly.

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

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

Schema coverage is 0%, so the description must fully explain the parameters. It does: category gives concrete examples and points to the taxonomy response, status lists allowed values, and include_reserved clarifies the default behavior with 'unimplemented' parameters. All three parameters receive meaningful, usable 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?

The description states a specific verb and resource: 'List Maginary prompt-DSL parameters.' It clearly conveys the tool's core function, though it does not explicitly differentiate itself from sibling tools like search_parameters or get_parameter.

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

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

The description gives clear usage context for each filter and explicitly advises calling with no filters once to get the full taxonomy. It does not, however, state when to prefer this tool over alternatives such as search_parameters.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses the 10-key limit, the two auth modes, per-action behavior, and the show-once nature of raw_key. This goes well beyond what the schema alone communicates.

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

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

The description is well-structured with a summary line followed by Auth, Args, and Returns sections. It is long only because it covers three actions and two auth modes, and every line 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 no annotations and zero schema coverage, the description explains auth, conditionally required parameters, and return shapes for each action. The pointer to configure_api_key completes the workflow context. Nothing necessary for correct invocation is missing.

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

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

Schema description coverage is 0%, so the description must compensate completely. It does: action is defined as create/list/revoke, name as required for create, key_prefix as required for revoke, and email/password as tied to Basic auth. Every parameter receives operational meaning.

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

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

States three explicit verbs (create, list, revoke) targeting a single resource, Maginary API keys, and adds the 10-per-account limit. This clearly distinguishes it from sibling configure_api_key, which the description names as the activation step.

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

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

Provides explicit auth-mode guidance: Basic auth with email/password for onboarding, or the configured API key for normal operation. It also names configure_api_key as the follow-up after create, but it does not explicitly exclude related siblings such as create_account.

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 no annotations provided, the description carries the full burden and does well: it discloses that search is case-insensitive substring matching, that include_reserved pulls in 'unimplemented' parameters, and that results are ordered as they appear in the catalog. It also reveals the live vs. bundled-snapshot source distinction. It could go further by explaining what 'unimplemented' means or how source is chosen, but coverage is strong.

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 tightly structured with Args and Returns sections, front-loads the core purpose in one sentence, and contains no filler. Every line adds useful information for calling the tool correctly.

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 three parameters and an output schema, the description is complete: it explains the search scope, all parameter behaviors, and the return shape including count, source, and ordering. No critical calling information appears to be missing.

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

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

Schema description coverage is 0%, so the description must fully compensate. It does: 'query' is defined as substring match, case-insensitive; 'category' as an optional single-category restriction; 'include_reserved' as whether to include unimplemented parameters. Every parameter receives meaningful semantic context 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 states a specific action ('Text-search over parameter names, aliases, descriptions, values, examples') with a clear resource and scope. This distinguishes it from sibling tools like list_parameters and get_parameter, which imply enumeration and direct lookup rather than substring search.

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

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

The description explains the mechanics of the search (substring match, case-insensitivity, category restriction, include_reserved flag) but does not explicitly say when to choose search_parameters over list_parameters or get_parameter. Usage is implied rather than directly contrasted with alternatives.

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

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

With no annotations, the description fully discloses behavior: polling backoff, timeout semantics (isError with error='timeout', generation keeps running and can be re-fetched), auth/failed errors, and the surprising case where server-side failures are successful calls with processing_state='failed' and empty image_urls.

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 section earns its place: one-line purpose, compact Args, and a Returns block that clarifies success and error variants. No filler or repetition.

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

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

For a tool with nuanced async behavior and no annotations, it covers purpose, input provenance, timeout behavior, terminal states, server-side failure semantics, and client-side error codes. The presence of an output schema further reduces the need to describe return structure.

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

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

Schema coverage is 0%, but the description compensates completely: uuid is defined as the value returned by generate, and timeout_s is explained with default, client-limit context, call-again meaning, and guidance for raising it. This far exceeds the bare schema.

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

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

The first sentence states a specific action—polling get_generation on backoff until done/failed—which clearly identifies the tool as a blocking wrapper over an asynchronous generation. This differentiates it from siblings like get_generation (single status fetch) and generate (starting the operation).

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

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

It explains the uuid comes from generate, implying use after generation is started, and gives explicit guidance about timeout_s relative to client call limits and when to raise it. It does not explicitly state 'use get_generation instead for a one-off status check,' so it lacks an explicit exclusion.

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