Posters and flyers with the headline and details printed on the design, in portrait, square or landscape format.
Scored across 5 tools
Most tools target a distinct action (prepare, generate, poll, update, render), but generate_media and update_media_project both 'overwrite saved project settings' before generation, creating boundary overlap. The object vocabulary is also muddy—'poster/flyer', 'media project', and 'media job' are used loosely, and render_media_widget references a prepare_media_project tool that isn't in the set.
All five names follow a clean verb_noun snake_case pattern (generate_media, get_media_job, prepare_poster_flyer, render_media_widget, update_media_project). The only wobble is the noun vocabulary, which alternates between poster_flyer and various media_* entities, but the structural pattern is consistent.
Five tools is a tight, well-scoped set for a generation flow (prepare, update, generate, poll, render). Nothing feels padded, though the set leans slightly thin given that one tool references a missing companion.
The core flow (prepare → update → generate → poll → render) is present, but render_media_widget depends on a project_id from prepare_media_project, which does not exist—only the poster/flyer-specific prepare does. There is also no list/delete or generic media-prepare operation, leaving a notable gap that could cause dead ends.
Start the generation for a prepared project in the user's Abracadabrax account. Call this only after the user explicitly asked to generate, never on your own initiative: it spends the user's credits and sends the generation inputs to the configured model provider. Optional settings overwrite the saved project. Repeating with unchanged settings reuses a running or completed job, but a failed job can start a new paid attempt. Returns the job id and status; poll get_media_job for the output. It needs the user's Abracadabrax account: the client asks the user to sign in when it is missing. Use this only for text-to-image or text-to-video prompts. Do not use it for uploaded, attached or reference images, image editing, background removal, upscaling, virtual try-on, image-to-video or other media-to-media workflows.
| Name | Required | Description | Default |
|---|---|---|---|
| tab | No | ||
| ratio | No | Aspect ratio such as 1:1, 16:9, 9:16, 4:3, 3:4. | |
| prompt | No | ||
| duration | No | Video length in seconds; must be one of the model's supported durations. | |
| model_id | No | Abracadabrax model id, e.g. nano-banana-2, gpt-image-2, flux-2-pro, kling-3-pro, veo-3-1, sora-2. | |
| model_name | No | ||
| project_id | Yes |
| Name | Required | Description |
|---|---|---|
| job | No | |
| state | Yes | |
| balance | No | |
| message | Yes | |
| project | Yes | |
| dashboard_url | Yes | |
| credits_required | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses credit spend, that inputs are sent to the configured model provider, that optional settings overwrite the saved project, that repeats reuse running/completed jobs while a failed job starts a new paid attempt, and that sign-in is required for the Abracadabrax account. These are exactly the cost, auth, and side-effect facts an agent needs and cannot get from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense block, but front-loaded with the critical constraint (never generate on your own initiative) before routing, cost, and return-value details. Each sentence carries distinct information; it is long because the behavioral surface is large rather than padded, though the negative-workflow list could be tightened.
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 decision surface for a 7-parameter, open-world-false mutation: cost, auth, idempotency-like reuse behavior, job-id return and polling path, and explicit exclusion of adjacent workflows. With an output schema present, no further return-value detail is required.
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 only 43%, and the description compensates partially by explaining that the optional settings overwrite the saved project (which frames tab, ratio, duration, model_id as overrides). However, it adds no per-parameter meaning for ratio, duration, or model selection beyond what the schema fragments already say, leaving the coverage gap only partly closed.
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+resource ("Start the generation for a prepared project") and clearly frames it as the execution step that follows prepare_media_project. The text also delineates what it is not (media-to-media workflows), so an agent can separate it from get_media_job and update_media_project without inspecting schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-call (only after the user explicitly asked to generate, never on own initiative), the follow-up step (poll get_media_job), and negative routing (not for uploaded/reference images, editing, background removal, upscaling, try-on, image-to-video). Both alternatives and exclusions are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the status and saved output URLs of an existing image or video job owned by the linked account. A queued or running job older than ten minutes can be marked failed and its credits refunded once. This changes job and credit records; it never starts a generation.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
| Name | Required | Description |
|---|---|---|
| job | No | |
| state | Yes | |
| message | Yes | |
| dashboard_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly discloses a side effect: 'This changes job and credit records' with a one-time failure marking and credit refund for jobs stuck past ten minutes. The annotations declare readOnlyHint=true, which directly contradicts a tool that writes to job and credit records (destructiveHint=true on a read-only tool is likewise incoherent). Per the rubric this is a mutation disclosed against a readOnly annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the primary outcome (status + output URLs), followed by exactly the two behavioral facts an agent needs: the ten-minute failure/refund rule and the mutation disclaimer. No 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?
An output schema exists, so return values are covered, and the annotations plus description together cover the safety profile. The remaining gap is the unresolvable readOnly/destructive tension and no statement of what happens when the job_id is unknown or already terminal.
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 single job_id parameter has 0% schema description coverage, so the description must carry the burden. It adds a meaningful ownership constraint (the job must belong to the linked account) but gives no format, source, or validity guidance for the identifier.
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 (return the status and saved output URLs of an existing image/video job) plus the scope constraint (owned by the linked account). The closing clause 'it never starts a generation' actively distinguishes it from the sibling generate_media 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?
Context for use is clear — retrieve the state of an already-created job — and the description supplies an exclusion ('never starts a generation') that separates it from generate_media. However, it never names generate_media or explain the expected call pattern (e.g., poll after submitting a job).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prepare a poster or flyer design with Abracadabrax: the headline and the details (date, place, offer) printed on the design, a visual theme and a portrait, square or landscape format. Returns the settings and the credits required; nothing is generated and no credits are spent. No sign-in is needed to prepare. Text only: do not use it for uploaded, attached or reference images or videos (editing, background removal, upscaling, image-to-video); for those, point the user to the Abracadabrax workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | event-poster (default), flyer, sale-flyer, concert-poster, movie-poster or announcement. | |
| theme | No | Visual theme, style and colors, e.g. retro 70s, neon night, elegant gold and black. | |
| format | No | portrait 2:3 (default), square 1:1 or landscape 3:2. | |
| details | No | Secondary text such as date, time, place, price or offer. Keep it short. | |
| headline | Yes | Main title printed on the design. | |
| model_id | No | Optional image model id: nano-banana-pro (default, sharp text), gpt-image-2, nano-banana-2. |
| Name | Required | Description |
|---|---|---|
| job | No | |
| state | Yes | |
| balance | No | |
| message | Yes | |
| project | Yes | |
| dashboard_url | Yes | |
| credits_required | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations present, the description still adds real behavioral context beyond them: nothing is generated, no credits are spent, and no sign-in is required to prepare. The annotation set (readOnlyHint=false, idempotentHint=false) does not convey the cost/auth profile, so this text is load-bearing. It stops short of describing what the returned 'settings and credits required' actually contain or what the agent should do next.
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 purpose, then cost/auth behavior, then the exclusion and routing rule — a sensible order with no filler sentences. The final exclusion sentence is long and packs several modalities, but every clause carries distinct routing 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?
Coverage of auth, cost, non-generation and exclusions is strong, and an output schema exists so return values need not be spelled out. The gap is workflow: the description never says the preparation is a precursor to an actual render or which sibling to call next, which matters given siblings like generate_media.
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 a baseline of 3 applies, but the description adds meaning by framing headline and details as text 'printed on the design' (with examples like date, place, offer) and by tying theme/format to the visual output. The text-only restriction also implicitly constrains how these parameters may be used, which the schema alone 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?
The description states a specific verb and resource ('Prepare a poster or flyer design with Abracadabrax') and enumerates the concrete inputs that define the output (headline, details, theme, format). It also explicitly carves out what the tool is not for, so an agent can separate it from image-generation siblings 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?
It gives explicit when-to-use (text-only poster/flyer with headline plus details) and when-not-to-use (uploaded, attached or reference images/videos: editing, background removal, upscaling, image-to-video), and names the correct destination for those cases ('point the user to the Abracadabrax workspace'). This is exactly the routing guidance an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show a saved Abracadabrax image or video project and its existing job. A queued or running job older than ten minutes can be marked failed and its credits refunded once. This changes job and credit records; it never starts a generation. Requires a project_id returned by prepare_media_project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes |
| Name | Required | Description |
|---|---|---|
| job | No | |
| state | Yes | |
| balance | No | |
| message | Yes | |
| project | Yes | |
| dashboard_url | Yes | |
| credits_required | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true, idempotentHint=true, readOnlyHint=false), the description discloses exactly what is mutated (job and credit records), the narrow condition under which the destructive action triggers (queued/running job older than ten minutes), and that the refund happens only once. This is precisely the extra 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?
Four short sentences, front-loaded with the primary action, followed by the conditional mutation, the non-behavior, and the prerequisite. No filler or repetition; every sentence adds a distinct fact.
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?
An output schema exists, so return values need not be explained. Given the tool's mutation semantics, the description covers what is required to call it safely and correctly: input source, mutation scope, the conditional destructive path, and the guarantee that no generation is started.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with one required parameter, so the description must compensate. It does by specifying the project_id's provenance ('returned by prepare_media_project'), which is meaningful information absent from the bare 'type: string' schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete verb+resource: showing a saved Abracadabrax image or video project together with its existing job, plus the side effect of failing a stale job and refunding credits. It is clear, but it does not distinguish itself from sibling tools like get_media_job or update_media_project, which could plausibly cover similar ground.
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 supplies a real precondition (project_id must come from prepare_media_project) and an exclusion (it never starts a generation, implicitly routing generation to generate_media). It stops short of explicitly naming get_media_job or update_media_project as alternatives, so the selection logic is not fully closed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Overwrite the saved widget settings (prompt, model, aspect ratio, duration) to a prepared project before generating. Changing generation settings detaches the prior job from this project without deleting that job or its media. Intended for the widget UI; no credits are spent. Use this only for text-to-image or text-to-video prompts. Do not use it for uploaded, attached or reference images, image editing, background removal, upscaling, virtual try-on, image-to-video or other media-to-media workflows.
| Name | Required | Description | Default |
|---|---|---|---|
| tab | No | ||
| ratio | No | Aspect ratio such as 1:1, 16:9, 9:16, 4:3, 3:4. | |
| prompt | No | ||
| duration | No | Video length in seconds; must be one of the model's supported durations. | |
| model_id | No | Abracadabrax model id, e.g. nano-banana-2, gpt-image-2, flux-2-pro, kling-3-pro, veo-3-1, sora-2. | |
| model_name | No | ||
| project_id | Yes |
| Name | Required | Description |
|---|---|---|
| job | No | |
| state | Yes | |
| balance | No | |
| message | Yes | |
| project | Yes | |
| dashboard_url | Yes | |
| credits_required | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and idempotentHint=true, and the description adds exactly the right context beyond them: the prior job is detached from the project rather than deleted, its media survives, and no credits are spent on the update. It also states the overwrite semantics, consistent with the idempotent hint instead of contradicting 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?
Opens with the core action and effect, then the scope constraints. No sentence is redundant; even the long exclusion list is load-bearing because it prevents the agent from routing editing/media-to-media work here.
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 7-parameter mutation tool with an output schema and full annotation coverage, the description supplies the necessary usage envelope, destruction semantics and cost note. The residual gap is parameter-level detail (tab, model_name, project_id), which is minor given the structured fields available.
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 only 43%, so the description must compensate; it names prompt, model, aspect ratio and duration but adds no syntax or constraints beyond the schema (duration's model-specific allowed values, ratio format, and the tab/model_id vs model_name distinction are untouched). Partial compensation for the coverage gap, so a baseline 3.
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 ('Overwrite the saved widget settings') plus which fields are affected, and positions the tool in the workflow ('to a prepared project before generating'), which cleanly separates it from prepare_media_project and generate_media. An agent can identify what this does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the supported case (text-to-image / text-to-video prompts) and enumerates a long list of excluded workflows (uploaded/attached/reference images, editing, background removal, upscaling, try-on, image-to-video, media-to-media). This is textbook when/when-not guidance with nothing left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
generate_mediaget_media_jobprepare_poster_flyerrender_media_widgetupdate_media_project
Add one secure layer between your agents and this server.