maginary-mcp

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

The description discloses authentication behavior ('Pass email + password ... for Basic auth, or omit both to use the configured API key') and the polling context, which adds value beyond the readOnlyHint/idempotentHint annotations. It does not contradict the annotations and explains what the tool checks without claiming side effects.

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 single-sentence purpose, followed by a compact usage scenario, args, and returns. Every sentence contributes: use case, auth mode, and expected output.

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 poll tool with two optional params and an output schema, the description covers purpose, when to call it, auth alternatives, and return fields. There is no missing operational detail an agent needs to invoke it safely and 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%, so the baseline is 3; the description adds useful coupling by saying the credentials come from create_account and that omitting both uses the API key. This gives the agent more operational guidance than the schema's standalone field descriptions.

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

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

The opening sentence names a specific verb and resource—'Check account verification status, credit balance, and API key count'—and the Returns line reinforces what is queried. This clearly differentiates it from siblings like get_balance by covering verification and API key count in addition to balance.

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 explicitly instructs when to use the tool: 'Use this after create_account to poll whether the user has clicked the verification link.' It does not mention when not to use it or name sibling alternatives such as get_balance, so it stops short of a full exclusion list.

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 goes well beyond the annotations by explaining the checkout flow: the URL must be opened in a browser, payment is handled via webhook, credits are provisioned automatically, and the URL fragment must not be modified. It also discloses failure modes such as email_not_verified, auth, and failed. This is rich behavioral context for a mutation 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?

The description is well-structured, front-loaded with the purpose, and uses formatting to highlight the critical URL-handling instruction. The Args block is somewhat redundant with the schema, but the overall length is justified by the important behavioral details and failure examples.

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 an agent to select and invoke the tool correctly. It covers purpose, usage conditions, alternative routing, exact handling of the returned URL, post-payment behavior, and failure responses. The presence of an output schema further reduces the burden on the description.

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

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

The input schema already provides 100% description coverage for all three parameters. The description's Args section essentially repeats the schema text, adding no new semantic meaning. It does reinforce that product_id comes from get_products, but that is already in 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 clearly states a specific verb and resource: 'Create a Stripe checkout session for purchasing a product.' This distinguishes checkout from sibling tools like generate, create_account, or get_products. The title and description align well.

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

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

The description gives explicit routing guidance: if the agent has a USDC wallet, skip checkout and call generate instead. It also points to get_products for the product_id, clarifying the intended data source. This is strong when-to-use and when-not-to-use guidance.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds critical details beyond those: exact file path, chmod 600, persistence across restarts, hosted response 'persisted: false', and the requirement to send an Authorization: Bearer header. This is rich operational context the annotations do not convey.

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

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

The description is front-loaded with the core purpose and uses clear paragraphs for environment-specific behavior. It is somewhat long, but every sentence provides operational necessity—no filler. Slight verbosity around the hosted section keeps it from 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?

For a single-parameter tool with full schema coverage, annotations, and an output schema, this description is complete. It covers the exact trigger (after create), environment differences, persistence behavior, and how to handle the non-persistent case, leaving no gaps for correct invocation.

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

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

Schema coverage is 100% and the schema already documents api_key as 'Full API key string from manage_api_key.' The description repeats that nearly verbatim, adding no new meaning. Baseline 3 is appropriate because the schema carries the 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 ('Activate an API key') and clearly distinguishes from its sibling manage_api_key by positioning this as the step after creation. An agent can immediately tell this tool is for enabling/persisting a key, not for creating or managing it.

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 call this after manage_api_key(action='create') returns a raw_key, and provides environment-specific guidance: local persistence vs. hosted per-request authentication. This leaves no ambiguity about when to use the tool and what to do with the result.

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

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

Beyond the annotations, the description discloses important behaviors: the password is auto-generated and must be shown once, verification is required before generating images, and failures include already_exists, rate_limited, and failed. This meaningfully informs the agent about side effects and error handling without contradicting the annotation hints.

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, and every part earns its place: creation, one-time password display, verification, downstream API-key steps, and failure modes. It is detailed without being redundant.

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

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

For a tool with a verification side effect and downstream steps, the description covers the full lifecycle: what happens immediately, what the user must do, what the agent should do next, and what errors to expect. The output schema exists, and the description still adds useful return semantics, so 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?

The schema already documents the email parameter at 100% coverage, so the baseline is 3. The description adds operational meaning by explaining that the email is used to create the account and by giving guidance on the already_exists failure, such as asking the user for their password or a different email. This goes beyond the schema but does not add format 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?

The description opens with a specific verb and resource: 'Create a new Maginary account for the given email address.' It is clear and actionable, though it does not explicitly contrast itself with the sibling create_wallet_account, leaving the agent to infer the distinction from the 'Maginary account' wording.

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

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

The description gives a clear usage flow: create the account, show the password once, wait for verification, then use manage_api_key and configure_api_key. It does not explicitly state when not to use this tool or name alternatives, but the downstream instructions make the intended context concrete.

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 readOnlyHint false and destructiveHint true, so the description must clarify the mutating nature. It does so by describing the creation/access flow and that a fresh API key is returned even for existing accounts. It also details the authentication message format and timestamp freshness constraint (5 minutes), adding meaningful behavioral context. It does not contradict the annotations, and the added details about the signing process and error codes (validation, signature_failed, rate_limited) enhance transparency.

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

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

The description is well-structured with a clear intro paragraph, then Args and Returns sections. While it is fairly long, every sentence adds necessary information (message format, timestamp constraint, key usage, error handling). It is front-loaded with the core purpose and usage context, then details. No filler or redundancy; it earns its length.

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

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

Given the complexity of a wallet-signature authentication flow, the description is remarkably complete. It covers the exact message to sign, parameter constraints, return values including api_key and key_prefix, error codes, and post-call usage (Bearer token, configure_api_key, _meta). The output schema is not provided, so the description's Returns section is the sole source for return format, and it is thorough. Nothing essential for an agent to call the tool correctly is missing.

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

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

Schema description coverage is 100% with each parameter briefly described, but the description adds critical semantics beyond the schema: it specifies the exact message to sign, the timestamp must be within the last 5 minutes, and the signature is EIP-191 personal_sign. This is essential for correct invocation and goes beyond the schema's one-line descriptions. The description also explains the relationship between timestamp and the signed message, which the schema alone does not 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 clearly states the purpose: 'Create (or access) a Maginary account using a wallet signature.' It specifies the resource (account) and the method (wallet signature), and distinguishes itself from the sibling 'create_account' by noting the email-less workflow. The phrase 'Create (or access)' clarifies that it handles both new and existing accounts, which is precise and unambiguous.

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

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

The description explicitly provides usage context: 'Use this when you have a wallet but no email.' This signals the alternative (create_account for email users) and gives a clear decision rule. It also explains how to use the returned api_key via multiple channels, which guides the agent on subsequent actions. This is comprehensive and leaves no ambiguity about when to invoke this tool.

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 present (non-read-only, non-idempotent, open-world), but the description adds substantial context beyond them: the call creates a child generation record that must be polled, and failures follow the same ``isError`` contract as ``generate`` with ``auth``, ``payment_required`` (x402 challenge) and ``failed`` cases. That is exactly the kind of downstream-behavior disclosure annotations cannot express.

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 purpose followed by Args/Returns blocks; the 14-item action-type list earns its place because the schema defines no enum for action_type. It is longer than strictly necessary, with a few restatements of schema-documented behavior, but nothing is 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?

For a multi-action, stateful tool with an output schema and annotations, the description supplies the missing connective tissue: ordering relative to generate/wait_for_generation, where to source action names, required-vs-optional parameter rules, and the failure contract. An agent has everything needed to invoke it correctly on the first try.

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 already 100%, so a 3 is the floor, and the description goes further by stating per-slot requirements (parent_image_index required except for ``reroll``) and the ``--mask <shapes>`` / flag syntax for ``img2img_inpaint``, which the schema's brief one-liner omits. Some overlap remains with the schema's own prompt and action_type text, keeping this out of 5 territory.

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 ('Run a follow-up action on a completed generation's image') and positions it precisely in the pipeline after generate → wait_for_generation, which cleanly separates it from both siblings. An agent can tell this is the post-generation image-editing tool 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?

Gives a clear precondition chain (only after ``generate`` → ``wait_for_generation``) and tells the agent where valid inputs come from (``processing_result.available_actions``), plus which actions are global vs per-slot. It does not state an explicit when-not-to-use or name a competing sibling as an exclusion, so it falls short of a 5.

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

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

Beyond annotations (readOnlyHint=false, openWorldHint=true, etc.), the description discloses the POST endpoint, the credit cost of extra flags, the fact that errors are returned as isError instead of raised, and detailed error codes (auth, payment_required, demo_not_found, failed). It also explains x402 payment handling and non-idempotency, exceeding annotation coverage.

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

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

The description is long but structured with clear sections and front-loaded with the main instruction. However, the exhaustive flag list at the end could be condensed by referencing get_parameter, making it slightly verbose though justified by the tool's complexity.

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

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

Given the tool's complexity and rich output schema, the description covers return fields (uuid, action_type, etc.), error handling, payment flow, and integration with sibling tools. Nothing an agent needs to call 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?

While the schema already describes both parameters at 100% coverage, the description adds extensive semantics: how to format the prompt with flags at the end, img2img examples, style reference distinction, and callback_url usage. It even provides concrete prompt examples, greatly enriching meaning beyond the schema.

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

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

The description clearly states the action ('Kick off a generation via POST /api/gens/') and the title confirms 'Generate image or video'. It distinguishes itself from siblings by explicitly instructing when to use upload_image, execute_action, and get_parameter, making the tool's purpose unambiguous.

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

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

It provides explicit when-to-use guidance: tells the agent to ask the user about quality/aspect ratio before generating, to use upload_image first for unhosted images, to use execute_action for img2vid, and to use get_parameter for unknown flags. It also explains when not to add flags, with concrete examples.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description's 'Check' aligns with read-only behavior and adds the return structure (dict with credits_remaining and uploads_remaining), which is useful context. However, it does not disclose any additional traits like rate limits or authentication prerequisites beyond the parameters. With annotations in place, this is adequate but minimal.

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: a clear first sentence stating the purpose, followed by Args and Returns sections. It is front-loaded with the main action and does not contain verbose or redundant phrasing. The repetition of schema parameter descriptions is minor and typical, but it does not detract from overall efficiency.

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-checking tool, the description is complete: it states what it does, the required inputs, and the output structure. It does not cover error conditions or alternative usage, but these are not critical for a basic operation. The return values are specified, and the tool's simplicity makes this sufficient for an agent 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?

The description's Args section repeats the parameter descriptions exactly as they appear in the input schema ('Account email (for Basic auth).'). Since schema coverage is 100%, the baseline is 3. The description adds no additional meaning or context about the parameters beyond what the schema already provides.

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 a specific action ('Check remaining credits and uploads') on a specific resource ('for the authenticated account'). This distinguishes it from siblings like check_account_status, which would cover broader account status. The verb and resource are explicit and unambiguous.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives such as check_account_status. It only describes the function, so usage is left to inference. There is no mention of exclusions or context that would help an agent decide between get_balance and other account-related tools.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description reveals a critical failure-mode behavior: a server-side failed generation is still a successful tool call returning processing_state 'failed'. It also documents terminal return structure and available_actions, adding substantial interpretive context the annotations do not 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?

The description is front-loaded with the purpose and uses clear labeled sections (Args, Returns, NOTE, Follow-up actions). It is longer than minimal but each section contributes meaningful operational guidance; only the hosted _meta note feels slightly tangential.

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

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

For a one-parameter fetch tool with an output schema, the description covers how to interpret terminal vs failed states, what fields to inspect, and how to proceed with available actions. Nothing an agent needs to call it correctly or interpret its result 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%, and the schema already explains uuid as 'Generation UUID from generate or execute_action.' The description only restates that the UUID is returned by generate, adding little beyond what the schema provides.

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 opens with 'Fetch a generation by UUID (GET /api/gens/{uuid}/)', giving a specific verb, resource, and endpoint. This clearly distinguishes it from siblings like generate, wait_for_generation, and execute_action, which handle creation, waiting, and post-processing actions respectively.

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 states the UUID comes from generate and explicitly directs follow-up actions to execute_action with the uuid, action_type, and parent_image_index. It doesn't explicitly contrast with wait_for_generation, but the context of fetching and checking state is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: it specifies the return type ('parameter dict') and error handling ('Not-found is an isError result — surface it rather than fabricating a param'). This goes beyond the annotations and helps the agent avoid incorrect 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?

Concise and well-structured with an Args/Returns format. The main purpose is front-loaded, and every sentence adds value. No fluff or redundancy.

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

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

For a simple single-parameter get with an output schema present, the description covers everything an agent needs: the name format, case-insensitivity, return type, and error behavior. No important operational details are 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%, so the baseline is 3. The description adds meaningful extra semantics: it clarifies the name can be canonical or alias, that leading '--' is optional, and that matching is case-insensitive. This enriches understanding beyond the schema's terse example.

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 ('Return') and resource ('full record for a single parameter'), and explicitly notes it accepts canonical name or alias. This distinguishes it from siblings like list_parameters and search_parameters by focusing on a single known 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?

Implies usage for a single parameter but does not explicitly name alternatives or conditions for choosing this tool over list_parameters or search_parameters. The context signals show these siblings, and the description could have added 'use search_parameters when you don't know the exact name' for clearer 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?

Annotations already mark this as read-only, idempotent, and non-destructive Mendable. The description adds valuable behavioral detail: no authentication requiredks, and it explains the output wrapping workaround (backend sends a bare array that FastMCP would reject as a top-level list). This goes well beyond the annotations and is consistent with them.

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

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

The description is front-loaded with the essential purpose and usage, then gives a compact, well-organized return format summary and a useful backend-wrapping note. Every sentence adds value; nothing is redundant.

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

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

Given the tool has no parameters and annotations already declare its read-only, idempotent nature, the description covers everything an agent needs: what it returns, when to use it, and a noteworthy output-format quirk. The presence of an output schema also reduces the burden, but the description exceeds it.

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

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

The tool has zero parametersaren't needed, so the description does not need to add parameter meanings. Per the rubric, 0 params receives a baseline of 4, and the description appropriately focuses on output and usage instead of nonexistent parameters.

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 available Maginary products/plans with pricing.' This clearly distinguishes the tool from siblings like checkout, get_balance, and create_account, and the use case is immediately obvious.

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

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

The description gives explicit context for when to call it: 'Use this to present purchase options to the user.' It also notes that no authentication is required and highlights a recommended product. It stops short of naming alternatives or exclusions, but the usage context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context: it explains the meaning of include_reserved (dropping unimplemented parameters) and describes the response keys (count, source, categories/statuses, parameters). This goes beyond annotations and helps the agent understand the tool's output and filter semantics.

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-loading the core purpose in the first sentence. It is concise yet comprehensive, with no redundant information. Each sentence adds value, making it easy for an agent to parse quickly.

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

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

The tool has an output schema, and the description explicitly outlines the return dict structure, covering count, source, categories/statuses, and parameters. All three parameters are optional and documented, and the description provides usage guidance. An agent has everything needed to invoke the tool correctly without missing critical details.

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 enriches parameter meaning by providing concrete examples for category (e.g., composition, video) and explaining that include_reserved defaults to False and drops unimplemented parameters. It also suggests using no filters to get the full taxonomy, which adds usage context beyond the schema's basic descriptions.

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

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

The description clearly states the verb 'List' and the resource 'Maginary prompt-DSL parameters', making the tool's purpose explicit. It also details the filtering options and return structure, distinguishing it from siblings like search_parameters and get_parameter without ambiguity.

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

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

The description provides clear usage guidance, notably 'Call with no filters once — the response's categories / statuses maps are the full taxonomy.' This tells the agent when to use the tool and what to expect. However, it does not explicitly contrast with sibling tools like search_parameters, so it lacks explicit exclusions or alternative selection criteria.

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

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

The description goes well beyond the annotations (destructiveHint=true) by disclosing the 10-key limit, the one-time display of raw_key, the requirement to use configure_api_key for activation, and the auth-mode switching behavior. This gives the agent concrete operational expectations without contradicting the structured 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?

The description is well-organized with clear sections for overview, auth, args, and returns. Each sentence contributes useful information, and the action-specific return behavior is structured for quick parsing. There is no filler or redundant restatement of the title.

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 multi-action tool with 5 parameters and no enums, the description covers all necessary operational details: what each action does, required vs. optional parameters, auth modes, account limit, and the expected return payloads. It also references the related activation tool, making the workflow complete for an agent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful detail beyond the schema: it clarifies that key_prefix must be 8 characters, that name is required for create, that key_prefix is required for revoke, and it explains the return format for each action. This is more than the schema alone provides.

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 (create/list/revoke) with a specific resource (Maginary API keys) and a key constraint (up to 10 per account). It clearly distinguishes itself from the sibling configure_api_key by mentioning that activation is a separate step, so an agent can select this tool appropriately.

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

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

It provides explicit auth guidance (email+password for onboarding vs. configured API key for normal operation) and notes that after creating a key, configure_api_key should be used to activate it. It does not explicitly enumerate all alternatives or when not to use the tool, but the action field and sibling references make the intended usage clear.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior, so the description adds value by disclosing search semantics (case-insensitive substring), the inclusion of unimplemented parameters via include_reserved, and the return distinction between live and bundled-snapshot sources. These details go beyond what the annotations 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?

The description is compact, front-loaded with the core purpose, and uses a clear Args/Returns structure. Every sentence contributes meaningful information without repetition 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?

The tool is simple, has an output schema, and all parameters are documented. The description fully covers search behavior, parameter roles, and return structure, including the live vs. bundled-snapshot source field and ordering guarantee. Nothing needed to invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description mostly mirrors the schema, though it adds useful nuance such as 'single-category restriction' and clarifies that include_reserved covers 'unimplemented' parameters. This is adequate but does not substantially exceed the schema's existing documentation.

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 a specific verb ('Text-search') and a specific resource (parameter names, aliases, descriptions, values, examples), which distinguishes it from sibling tools like list_parameters or get_parameter. It also explains the search semantics in the first sentence, making the tool's role immediately obvious.

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 establishes clear context: it is for substring-based text search across parameter metadata. It does not explicitly name sibling tools or state when not to use them, but the 'Text-search' framing and the parameter-focused scope are sufficient to guide selection in most cases.

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=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the local-only constraint, the deduplication behavior (exists field), and the fact that credits are deducted. It doesn't explicitly state that the operation is a write/upload, but the description's 'Upload' verb and the credits_deducted return field make that clear. The description adds context beyond annotations without contradicting them.

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

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

The description is well-structured and front-loaded: the core purpose is in the first sentence, followed by the critical usage constraint, then a usage example, then parameter details. Every sentence earns its place, and the Args/Returns section is a clean, scannable format. No wasted words.

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 an upload tool. It covers the purpose, the local-only constraint, the alternative for remote connections, how to use the result, parameter semantics, and the return value structure. The output schema exists, so return values are documented. The sibling tools are all different operations (generate, checkout, account management), so no confusion is possible. Nothing an agent needs to call this 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 the schema already documents both parameters (file_path and filename). The description adds a small amount of value by explaining that filename is inferred from file_path if omitted, which is also in the schema. It doesn't add format details or examples beyond what the schema provides, so a 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?

The description states a specific verb ('Upload'), a resource ('a local image'), and the outcome ('get a CDN URL for img2img or --sref'). It clearly distinguishes this tool from siblings like generate or get_generation by focusing on the upload step. The title and description align, and the purpose is immediately understandable.

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

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

The description explicitly states when to use this tool: only on local (stdio) connections, and provides the alternative for hosted/remote connections (place an existing image URL directly in the prompt). It also gives a concrete usage example showing how to use the returned URL in a generate prompt. This is clear, actionable guidance that prevents misuse.

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?

Well beyond the readOnly/idempotent/openWorld annotations, the description discloses the backoff polling strategy, the 45s default tied to the 60s MCP per-call limit, and a precise error taxonomy ('timeout', 'auth', 'failed') with the crucial distinction that server-side 'failed' generations are still successful tool calls with empty image_urls. This is exactly the behavioral context annotations cannot carry.

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 behavior, then structured Args/Returns/follow-up sections. It is verbose and the timeout semantics are restated in both the arg paragraph and the Returns block, but nearly every sentence carries operational 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 polling tool with an output schema, a single required param, and no nesting, this covers everything an agent needs: termination states, timeout semantics, error branches, and how to chain into execute_action using available_actions slot indices. Nothing material 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%, so the baseline is 3, but the description adds real semantics: timeout_s defaults to 45 to stay under the 60s client limit, a timeout is non-fatal since the generation keeps running, and which uuids are valid (those returned by generate). uuid adds no meaning beyond the schema, but timeout_s is meaningfully enriched.

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 names a specific verb (poll) and resource (get_generation), plus the termination condition (done/failed). It clearly distinguishes itself from the one-shot sibling get_generation and from generate, so an agent can pick it 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?

It gives a concrete when-to-use context (waiting on a generate uuid), explains what a timeout result means ('call again'), and warns when to raise timeout_s (video, permissive clients). It routes follow-up work to execute_action, but never explicitly states the alternative (e.g. 'use get_generation for a single non-blocking check'), which keeps it just short of a 5.

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