Mage.Space

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

Annotations already declare destructiveHint, idempotentHint=false, and readOnlyHint=false, so the safety profile is known. The description adds real value beyond them: Gems consumed are not refunded (a cost consequence) and cancelling a cancelled request is a no-op (concrete idempotency semantics). It stops short of saying what the response contains or whether the request transitions through an intermediate state.

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

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

Three short sentences, front-loaded with the action, each carrying a distinct constraint or consequence. 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?

For a one-parameter mutation with no output schema, it covers the cost side effect and the edge cases that matter. A brief note on what the call returns (e.g. updated request status) would close the remaining gap.

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

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

Single parameter with 100% schema coverage and its own description tying it to generate's return value, so the schema does the heavy lifting. The tool description adds nothing about request_id format or validation, which is acceptable at this coverage level.

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 (stop/cancel) and resource (a queued or running request), and ties the resource back to its origin tool, generate. The scope qualifier 'queued or running' distinguishes it cleanly from get_request, list_history, and generate.

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 gives the use condition (request is queued or running) and the exclusion (a finished request cannot be cancelled), plus the no-op case for an already-cancelled request. An agent can decide whether to call this without inferring anything from siblings.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent, open-world), so the description doesn't need to restate them. It adds real value beyond that: the image is "stored permanently", the voice clip is "trimmed to 10 seconds", the returned handle "cannot be changed later", and the result is private until published in the app. Missing are failure behaviors (bad image URL, name/handle collision) and whether a duplicate name is allowed.

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

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

Two sentences, front-loaded with the core action, followed by the return-value/mention tip and the publishing exclusion. Every clause earns its place and nothing is padded.

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

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

With no output schema, the description correctly compensates by explaining that the tool returns a `handle` and how to use it downstream. For a 5-parameter mutation tool with full annotation and schema coverage, the main remaining gap is error and uniqueness behavior. Otherwise it is complete enough to invoke correctly.

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

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

Schema coverage is 100%, so parameter documentation is already handled by the schema. The description restates the accepted image forms (https URL or data URL of JPEG/PNG) and the voice trimming, but actually omits the "upload URL" option the schema lists, and adds no format detail the schema lacks. Baseline 3 is correct here.

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 ("Save a private character from a name and an image") and immediately scopes it against the sibling actions: private creation here, publishing "in the Mage app", deletion elsewhere. An agent can tell this apart from delete_character or list_characters without opening a schema.

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

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

It gives a usable boundary: this creates a *private* character, and publishing is explicitly out of scope ("Publishing a character happens in the Mage app"). It also tells the agent the post-condition needed to proceed ("mention it in a generate prompt as @handle"), implying the create-then-generate flow. It stops short of naming sibling tools like list_characters or delete_character as alternatives.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the description mainly needs to add context. It contributes that the reference is private, permanently stored, that audio is trimmed to 15 seconds, and that the returned handle is the durable contract — useful, but most of these details are restated from the schema, and nothing is said about failures, name collisions, or what happens on re-creation of an existing handle.

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

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

Two sentences, front-loaded with the primary action and its payload formats; the return-value and usage note comes second where it belongs. It is dense with parenthetical format details but no sentence is wasted.

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

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

For a 6-parameter creation tool with full schema coverage and annotations present, the description covers purpose, input formats, the audio trimming behavior, and the returned handle's role in downstream prompts. With no output schema, it correctly states the return value; remaining gaps around permissions and error behavior are minor.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the kind-to-field pairing (four image kinds take image, audio takes audio) and the accepted formats, which largely duplicates what the schema already documents rather than adding new syntax or 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 first sentence gives a specific verb (Save) and resource (a private reference) and enumerates the concrete kinds, so an agent immediately understands what is created. It does not differentiate itself from siblings such as create_upload (which apparently handles the reserved image1/image2 uploads) or create_character, leaving a small ambiguity at the boundary.

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 closing clause 'mention it in a generate prompt as @handle' implicitly explains why one would call this rather than anything else, tying it to the generate flow. However, there is no explicit when-not guidance, no mention of list_references/delete_reference as the lifecycle alternatives, and no statement about when to prefer create_upload.

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

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

With annotations already covering safety (readOnlyHint=false, destructiveHint=false), the description adds crucial operational semantics beyond them: a signed-URL handshake, exact PUT requirements with headers, URL/file expiry, one-file-per-upload immutability, CDN caching for up to 4 hours, and the rule never to reuse an earlier upload_url. These are non-obvious behaviors an agent could easily get wrong.

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

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

Front-loads purpose and size threshold, then the operational workflow, then consumption targets. Although long, every sentence carries distinct operational value—expiry, immutability, header requirements—and the curl example is a compact concrete instruction rather than 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?

No output schema is provided, and the description explains the relevant returned fields (upload_url, headers, upload_url_expires_at, url, url_expires_at) and how they behave. Combined with the PUT workflow and consumer tools, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the content_type enumeration and meaning are fully documented by the schema. The description adds only indirect context via the curl example showing a matching Content-Type header. That is marginal beyond the schema, so the baseline 3 applies.

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

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

Starts with a specific verb and resource: 'Get a signed URL to upload a local file'. Immediately qualifies scope (too large for a data URL, over ~3 MB, up to 100 MB) and the file kinds supported. An agent can tell this apart from generate, create_character, and create_reference, which consume the result rather than create uploads.

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 states the precondition ('Only for a file on a machine where you can run commands: this server cannot read files attached to the chat') and the size-based reason to choose this over a data URL. It names the downstream tools that consume the returned URL (generate, create_character, create_reference, estimate_cost), giving clear routing 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 destructive=true and idempotent=true, so the safety profile is covered. The description adds real behavioral context beyond annotations: the character's handle stops working in prompts immediately, telling the agent the effect is instant and user-visible. It stops short of stating irreversibility or whether the character can be recreated.

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

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

Two short sentences, front-loaded with the action and target, followed by the consequence. Every clause carries information; 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?

With one required param, no output schema, and annotations covering safety and idempotency, the description supplies what an agent needs: what is deleted, where the id comes from, and the immediate effect. Lacking only a note on whether deletion is reversible.

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

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

Schema coverage is 100%, so baseline is 3. The description adds provenance for the single parameter by naming list_characters as where the `id` comes from, which is meaning the schema does not carry.

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 ('Delete one of the account's characters') and scopes it to the account, which separates it from delete_reference and other siblings. It does not explicitly contrast with any alternative delete/create sibling, but the resource is unambiguous.

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

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

Points the agent to list_characters as the source of the required `id`, which is useful routing, but gives no when-not-to-delete guidance, no prerequisite/permission note, and no note about confirming before irreversible removal.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds a meaningful consequence beyond that: the handle stops working in prompts immediately, which tells the agent the effect is instant and can break prompt configuration. It does not state whether deletion is recoverable, which keeps it from a 5.

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

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

Two short sentences, the action and target front-loaded, followed by the behavioral consequence. Nothing is redundant or padded.

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?

A one-parameter destructive tool with annotations covering destructiveness and idempotency, and no output schema to explain. The description covers purpose, id source, and immediate effect; the only minor gap is recoverability or error behavior for an invalid id.

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% for the single reference_id parameter, so the baseline is 3. The description adds value by naming where the id comes from (list_references), which the schema's terse "The reference `id`." does not say.

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?

Names a specific verb (delete) and resource (reference), scoped to the account, and ties the identifier back to the sibling tool list_references. An agent can distinguish it from delete_character or create_reference without opening a schema.

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

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

The phrase "by its `id` from list_references" implicitly tells the agent to call list_references first to obtain the identifier, which is clear operational context. There are no explicit exclusions or guidance on when not to delete, so it falls short of the top mark.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: nothing is charged or stored, the return payload is the Gems cost plus account balance, and a bad config yields the same refusal generate would give. It also discloses a specific failure mode (a video hosted elsewhere cannot be measured) and why (only generate downloads it).

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?

Purpose, return value, and media caveat are front-loaded in that order, and no sentence is filler. The second sentence is dense and nested (three URL cases, then the exception), which slows reading slightly but every clause carries decision-relevant 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?

There is no output schema, and the description compensates by describing the response shape (Gems charge, account balance, or refusal). Combined with the media-measurement precondition, an agent has everything needed to call this correctly and interpret the result, including for the nested config object.

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

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

Schema coverage is 100%, so both parameters are already documented, including the layered `config` object. The description still adds value by stating that `architecture` and `config` are the same ones generate accepts, which tells the agent it can reuse a config it already validated elsewhere and that estimate and generate will agree.

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?

"Price a generation before starting it" gives a specific verb (price) and resource (a generation), and immediately contrasts with generate by promising the same inputs with no charge. An agent can distinguish this from generate, get_account, and create_upload without opening any 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?

The description states exactly when to call it (before starting a generation, to catch rule-breaking configs for free) and names the alternative that follows (generate) plus the prerequisite path for external video (create_upload first). The "requires_media_measurement" case tells the agent when this tool cannot answer and what to do instead.

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?

Goes well beyond the annotations: discloses cost (Gems), concurrency limits shared with the Mage app with the specific error token `too_many_requests`, batch-in-waves advice, and the fact that an idempotent retry returns the original request without charging again. This is exactly the mutation cost/idempotency context an agent needs and that 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 with the action and payment model, and nearly every clause carries real information. The middle section is a long semicolon-chained block that could be broken into ordered steps for faster scanning, which is the only deduction.

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?

Covers the full call lifecycle for a complex, paid, stateful operation: pricing pre-check, model selection, media input handling, rate-limit behavior, idempotency, and the returned request_id plus the follow-up tool. With no output schema, it still tells the agent what comes back.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds the config layering model onto model defaults, the @handle convention, and https/data URL handling. The idempotency guidance adds one genuinely new consequence (no double charge on retry), though much of the rest restates the schema's own parameter 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?

States a specific verb and resource family ('Start an image, video, or audio generation') plus the payment model ('paid in Gems from the account'). It is immediately distinguishable from siblings like estimate_cost, list_models, and get_request, all of which it names.

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

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

Explicit ordering guidance: check price with estimate_cost first, pick model_id from list_models, upload large local files with create_upload first, and poll with get_request. It also states an exclusion-style rule for idempotency_key reuse (only on retry of a lost response).

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description correctly focuses on semantics beyond safety: the balance is the funding source for every generation started here, the limit is enforced by `generate`, and generations started in the Mage app also count against it. That last detail is non-obvious cross-surface behavior an agent could not infer from schema or annotations.

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

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

Two sentences: the first states what is returned, the second states why and when it matters. No filler, and the payload (the fields) is front-loaded before the rationale.

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

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

There is no output schema, so the description compensates by naming the three returned fields, and it adds the limit/error semantics needed to act on them. Nothing an agent needs to call and interpret this zero-arg read tool 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?

Zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description appropriately spends no words on arguments and instead explains the returned values.

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?

Names a specific resource (the connected Mage account) and enumerates exactly what is returned: username, Gems balance, and in-flight generation count against the limit. This is clearly distinguishable from siblings like get_model or get_request, which target different resources.

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

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

Explicitly says to read this 'before starting a batch' and names the sibling (generate) whose behavior depends on it, with the exact failure mode (`too_many_requests`) that motivates the pre-check. An agent has a concrete trigger for calling this tool and knows which alternative action it gates.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. What the description adds beyond that is substantial: a near-complete inventory of the response payload (schema, options narrowed per model, defaults, URL fields, mention limits, request rules, price, docs, variants), which matters because there is no output schema. It stops short of noting payload size, caching, or error behavior for unknown ids.

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 verb and resource, and every clause maps to a distinct returned field, so almost nothing is padding. The cost is that it is a single ~90-word run-on with heavy nested backticks, making it harder to scan than a short list would be.

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

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

For a one-parameter read tool with no output schema, the description carries the full burden of return-shape disclosure and does so thoroughly — schema, options, defaults, media fields, mentions, request rules, pricing, docs, and variants. An agent can decide whether to call it and know what it will get back without guessing.

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 parameter's own description already explains that it is the model id from list_models, so the description adds little. The text repeatedly says `model_id` while the actual parameter is named `architecture`, which is response-field terminology rather than parameter guidance and could momentarily disorient an agent.

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 clause 'Describe one model' gives a specific verb and resource, and the enumeration of returned fields (input_schema, options, base_config, tier, variants, price) makes the tool's scope unmistakable. It references list_models as carrying the same tier/variant data, which implicitly distinguishes the detail lookup from the summary listing, though it never states that contrast outright.

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?

Usage is only implied: the schema note that the id comes 'from list_models' and the aside 'as in list_models' suggest the list-then-detail workflow, but the description never says when to call this versus list_models or estimate_cost. No exclusions, prerequisites, or alternative routing are given.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile needs no restating. The description adds genuinely useful behavior not in annotations: the blocking wait window, the retry-until-terminal loop, and a 30-day URL retention warning that affects the user's ability to keep results. However, it does not cover error/failure semantics beyond listing 'failed' as a status, so with annotations carrying the safety load this lands at a solid 3 rather than higher.

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 read operation, then practical guidance, with no filler sentences. The restatement of wait_seconds' default and max slightly duplicates the schema, but every other clause (Gems charged, 30-day URL, list_history fallback) 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?

No output schema exists, so the description correctly carries the return-value burden: status values, result contents, charged Gems, and URL lifetime. Combined with the polling loop and the list-based alternative, an agent has everything needed to call and interpret this correctly.

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

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

Schema description coverage is 100% and already documents request_id provenance, wait_seconds range, default 45, and the 0-means-immediate case. The description restates the default and cap ("default 45, at most 120"), which is redundant, though it does add the polling semantic of what to do with the returned status. Baseline 3 is the right level when the schema does the parameter work.

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?

Specific verb + resource ("Read a request started with generate") plus the exact payload it returns: status enum, result, and Gems charged. It also draws the key boundary against siblings by noting that Mage-app generations are not requests and appear in list_history instead.

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 polling instruction ("call it again while the status is queued or in_progress"), plus explicit routing to list_history with concrete status values when following many requests. It also states an exclusion (Mage-app generations), which is exactly the when-not guidance most tools omit.

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, destructiveHint=false, so safety is covered. The description adds genuine behavioral context the annotations lack: result ordering (newest first), the account-scoped result set, and the fact that public characters are resolvable by handle elsewhere but absent here.

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

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

Three short sentences, front-loaded with what is listed and in what order, then how to use the handle, then the scope caveat. No redundant restatement of the title or 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?

There is no output schema, but the description enumerates the returned fields and ordering, and the two input parameters are fully documented in the schema. An agent has everything needed to call it and interpret the response.

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

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

Schema description coverage is 100% and both parameters (limit with default 50 and max 200, cursor referencing next_cursor) are documented there. The description adds nothing about paging or limits, so this is the standard baseline-3 case where the schema does the work.

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

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

States a specific verb and resource ('List the account's saved characters'), the ordering ('newest first'), and the exact fields returned (handle, name, image, voice). It also distinguishes these from other users' public characters, which are addressable by handle but not listed, separating it from sibling create_character/delete_character.

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

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

It gives an explicit next-step instruction ('Put @handle in a generate prompt to include the character') and a scope exclusion ('other users' public characters ... are not listed'), which tells the agent when this tool's output will and won't be complete. It never names a sibling alternative for finding public characters, so it stops short of a full routing rule.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, and the description goes well beyond them: a hard 30-day media expiry, newest-first ordering, the per-item shape (prompt, model, status, result URL, billing), and the gems vs unlimited billing distinction. These are operational constraints the agent cannot get from the structured fields.

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

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

Three tightly packed sentences with the core purpose and time window front-loaded. It is dense with return-field and pricing detail, but nothing is filler; a minor trim of the billing clause would not change meaning.

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

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

No output schema exists, so the description carries the burden of explaining what each record contains, and it does so along with expiry and cross-tool references. The only shortfall is that pagination shape (next_cursor) is left entirely to the schema.

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

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

Schema coverage is 100%, so limit, cursor, status, media_type, and architecture are already documented. The description's mentions of `source` and `request_id` refer to returned fields rather than inputs, and it adds no filter syntax or usage nuance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource plus the exact scope and ordering: 'List the account's generations from the last 30 days, newest first.' It then names the sources (Mage app, API, MCP server, auto-creation) and the sibling that holds a different corpus, so an agent can distinguish it from search_creations immediately.

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 routes the agent: this tool is for the 30-day history, while the user's permanently saved creations live in search_creations. It also names get_request and cancel_request as the consumers of the returned request_id, giving a clear follow-up path.

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

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

Annotations already establish a safe, idempotent read, and the description adds real behavioral context beyond that: default vs. opt-in listing scope and the rule that opt-in models run only on explicit user request. With no output schema, it also describes the return shape (id, media type, tier, price in Gems, summary; variants with model_id, options, image budget, trade-offs), which is valuable. Minor gaps only, such as ordering or result size.

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?

Purpose and defaults are front-loaded, but the body is a dense run-on paragraph with stacked parentheticals like '(`defaults`)' and interleaved field enumerations that make it harder to parse than needed. Little is outright wasteful, but the structure could be far cleaner.

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?

Covers what is listed, what is excluded by default, how to include opt-ins, the default model per media type, and the required follow-up call to get_model. For a two-optional-parameter read tool with no output schema, nothing an agent needs 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 goes further by explaining the consequence of include_opt_in ('the rest are opt-in... run only when the user asks for one by name') rather than just restating the flag. The type filter's semantics are covered by the schema's enum and its constraint, so the description adds little there.

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

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

States a specific verb and resource ('List the models Mage generates with') plus the intent behind it (guiding model choice). It also distinguishes itself from the sibling get_model by explicitly deferring detailed single-model lookup to that tool.

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

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

Gives concrete defaults per media type (mango-v3 for images, cherry-2-pro for video, seed-audio-1.0 for audio) and the condition under which they apply ('Unless the user names a model'). It also explains that opt-in models are only listed with include_opt_in and only run when a user names one, and directs the agent to call get_model before generating.

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

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

The annotations already declare this is read-only, idempotent, closed-world, and non-destructive. The description adds useful behavior beyond that by stating results are newest first and scoped to the account's saved references.

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

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

The description is three focused sentences with the core listing behavior front-loaded. Each sentence contributes useful information: scope, filtering, and cross-tool usage.

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 optional-parameter list tool with rich annotations and full schema coverage, the description is nearly complete. It does not describe the response shape in detail, but the cursor schema covers pagination and no output schema is present.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including the `kind` enum and pagination fields. The description reinforces the `kind` values and gives an example, but adds little beyond the structured schema for `limit` and `cursor`.

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 the account's saved references. It also enumerates the reference kinds and ordering, making clear how this differs from create_reference, delete_reference, and list_characters.

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 clearly explains how to narrow results with the `kind` parameter and gives an example. It also notes how references can be mentioned in generate prompts, though it does not explicitly name alternatives or when not to use 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 already declare read-only, idempotent, non-destructive behavior. The description adds valuable context beyond them: creations are stored permanently, results default to newest-first when no query is given, and each result carries a permanent URL, prompt, and model. No contradiction with annotations.

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

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

Two tightly packed sentences: first states what is searched and the filter modes, then the default ordering and result contents. Front-loaded and zero waste for a seven-parameter tool.

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 seven optional params, full schema coverage, and read-only annotations, the description covers the main search modes, default behavior, and return fields. Pagination details live in the schema; overall the definition is nearly complete, missing only explicit sibling routing.

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 all seven parameters are documented in the schema. The description adds a semantic-search example ('a red car at night') and clarifies that no query yields newest-first, but this is marginal beyond the already-rich schema descriptions.

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

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

States a specific verb (Search) and resource (creations the user saved in Mage, kept permanently), and enumerates the filter modalities (meaning, media type, collection, date). The resource is specific enough to separate it from list_history or list_references, but no sibling is named explicitly.

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

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

The description implies usage: search by meaning with `query`, or filter by media type/collection/date, and it notes the no-query default. However, it never states when to choose this tool over alternatives or any exclusions, so guidance is only implied.

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