no-api-media

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

With no annotations, the description carries the full burden and does real work: it discloses that a visible browser window is opened on the 'private no-api-media' profile, that credentials are never seen or stored server-side, and that closure is the user's responsibility. It does not say whether sessions persist after the window closes or what happens if it is left open.

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 with zero filler, and the security guarantee — the most trust-critical fact — is front-loaded immediately after the action. Each sentence 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?

For a one-optional-parameter tool with no annotations and no output schema, the description covers the essentials: the mechanism, the security posture, and the required user follow-up. It is slightly short on the post-sign-in state (whether logins are stored for later tools to use, or how to confirm success).

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 single optional 'services' parameter already carries an inline description with allowed values and a default. The description never mentions 'services', so it adds no meaning beyond the schema; 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?

Concrete verb and resource: opens a normal Chrome window on a named profile so the user can sign in by hand. An agent knows exactly what action occurs. It does not differentiate itself from the sibling accounts_status, which an agent might reasonably confuse for checking login state.

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

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

Gives explicit operational instruction: tell the user to sign in, then close the window — so the agent knows the call starts a human-in-the-loop step rather than completing auth itself. It does not mention accounts_status as the way to verify the result afterward, so routing between the two siblings is left to inference.

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

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

With no annotations, the description must carry behavioral disclosure. It does enumerate exactly what gets inspected, implying a read-only probe, but never says whether it makes live network/auth calls, whether it can be slow or rate-limited, or whether it mutates anything — and there is no output schema to fall back on.

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?

One dense, front-loaded sentence listing all checked surfaces with no filler. Slightly list-heavy phrasing but every clause names a distinct account source.

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 should convey what comes back — per-account status, pass/fail booleans, or remediation hints pointing to accounts_login. It lists the inspected targets but leaves the return shape undefined.

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

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

The tool takes zero parameters and the description correctly presents the check as parameter-free with a fixed enumeration of targets. Baseline 4 applies; nothing extra is needed.

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 ('Checks') plus concrete resources: Codex and Higgsfield CLI sign-in, ChatGPT web sign-in, Google account/plan tier on Flow, and JSON-defined sites. It's clearly a status/readiness probe rather than the login action performed by the sibling accounts_login, though it doesn't name that sibling 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?

No statement of when to call it versus accounts_login, nor any prerequisite or exclusion (e.g. 'run before generation to verify auth'). Readiness gating is only weakly implied by the title 'Check which accounts are ready'.

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

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

With no annotations, the description carries the burden and does substantial work: it discloses local-only processing with no upload or API, the one-time model download on first run, and the exact dependency install command. It omits what happens when the target file already exists and whether the input file is ever modified, which matters for a writing 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?

Front-loaded with the outcome, then the presets, then the environment caveat; nearly every clause earns its place. The install command is useful but sits slightly awkwardly at the tail.

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

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

There is no output schema, so the description must say what comes back, and it only implies a file is written rather than stating whether a path is returned. Combined with the silent `overwrite` parameter, an agent knows the intent but not the failure and return contract.

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 25%, so the description must compensate and does so well for `quality`, mapping each enum value to a model, speed cost, and use case. However, `overwrite` is undocumented in both schema and description, leaving the agent to guess whether false means error or skip, which is the riskiest parameter 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: cuts out the subject and saves a transparent PNG, entirely on this machine. The operation is distinct from every sibling listed (media_optimize, media_cleanup, image_generate all do something else), so an agent can select it 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 quality presets are explained with the conditions that select them (fast = default, best = slower with a ~1 GB model on first use, portrait = people, anime), which is real selection guidance. It stops short of stating when to prefer this tool over a sibling like media_optimize, and gives no exclusion for non-photographic inputs.

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

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

With no annotations, the description carries the full burden. It usefully discloses that data is 'stored on this machine only', but for a mutating tool it does not say whether set overwrites an existing profile, what remove destroys, or what list returns. The local-persistence note is real added value, but mutation semantics are missing.

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

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

Three dense sentences, front-loaded with the purpose and rationale ('so the right logo is never guessed'), followed by workflow links and the action set. Little waste, though the rationale clause could be trimmed without loss.

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 an 11-parameter tool with no annotations and no output schema, the description leaves key behavior unexplained: what a list result contains, whether set is an upsert, and what remove clears. The workflow and persistence notes help, but an agent still has to infer mutation semantics.

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 36%, so the description must compensate. It does explain publisher ('a person posting as themselves, or a company'), the dark-vs-light logo distinction, and that palette and fonts are optional, but leaves name, colors format, used_for, body_font/heading_font, and google_fonts_url to the schema. Partial compensation only.

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 the resource (a per-brand profile holding publisher type, dark/light logo files, optional palette and fonts) and the supported operations (list, set, remove). It also names the siblings it feeds (design_brief, compose), so an agent can place it in the workflow. The verb is soft ('keeps a profile') rather than an explicit 'register/read brand profiles', which keeps it just short of a 5.

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

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

It says design_brief takes brand_id and fills these in, and compose places the logo, which implies this tool should be populated before those run. However, there is no explicit instruction on when to call it (before composing? on first run?) or how to choose between list, set, and remove.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the cross-session safety behavior (other sessions' tabs are untouched, the browser closes itself once they finish) and the fallback idle safety net. It does not state whether the call is idempotent or what a repeat call returns, which is the only remaining gap.

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 prerequisite is front-loaded in the first sentence and every sentence carries information. The closing clause ('reopening costs a few seconds, but closing mid-work makes the next step start over') restates the earlier don't-call-mid-work point at slightly more length than needed.

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 zero-param, output-schema-less lifecycle tool, the description covers timing, side effects, cross-session side effects, and the failure mode of misuse. An agent has everything needed to call it correctly and nothing required is missing.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It correctly avoids inventing parameter detail.

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 ('closes this session's browser') along with the exact precondition for calling it. The scope caveat (shared-browser tabs from other sessions are never closed) further sharpens what the tool does, and no sibling tool overlaps with this lifecycle role.

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

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

Gives an explicit when ('only at the very end', with three concrete completion conditions), an explicit when-not ('don't call it between rounds of edits'), and the cost rationale for the exclusion. Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and does real work: it discloses that a PNG is written to disk, that a browser tab is opened on the server, and the deterministic layout/contrast rules (4.5:1 scrim, single colour, no glow, feathered logo tile). It does not disclose what happens when the output already exists without overwrite, or what errors can occur.

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 is front-loaded in the first clause, followed by dense behavioural detail, then outputs and side effects. The middle sentence is long and comma-chained but every clause carries real information; nothing is 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 an 11-parameter write tool with no annotations and no output schema, the description explains the output (a saved PNG), the downstream step (deliver), and the browser-tab side effect, which covers most of what an agent needs. Gaps around overwrite behaviour, failure modes, and a few parameters keep it short of complete.

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?

At 55% schema coverage the description meaningfully supplements several params: text_corner defaults to the measured calmest corner, logo_corner defaults to the calmest bottom corner, and heading_font falls back to the brand's display font then Space Grotesk. However overwrite, output_path, body_font and platform cropping are left to the schema alone, so it only partially compensates.

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 chain: renders a headline plus a registered brand's logo over a generated image, and saves a PNG. That is clearly distinct from image_generate (creates art) and deliver (publishes the finished file), both of which are named or implied.

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 the position in the workflow by telling the agent to 'run deliver on it for the platform' and by taking a generated art path as input, and it notes the browser tab side effect. But it never states when not to use it, nor how it relates to composition_check or design_audit, which are obvious adjacent 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?

With no annotations, the description carries the load and does disclose the key trait: analysis produces a measurement plus a crop, and a file is only written when output_path is passed ('Pass output_path to save the cropped version'). Undisclosed behaviours remain — what overwrite=false does when the target exists, and whether the input file is ever touched — so it is not complete coverage of a tool that can write to disk.

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, no filler: what it detects and returns first, then the optional write, then the workflow triggers. Every clause carries information an agent would otherwise have to infer.

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 steps in to describe the return value (band proportion plus a crop), which is exactly the right compensation. Given a five-parameter tool with no annotations, the missing overwrite failure behaviour is the one substantive hole.

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 60%, and the description only touches output_path, which the schema already documents ('If set and a band is found, the cropped image is saved here'). planned_edges ('Edges you left calm on purpose') and target_aspect shape preservation go unmentioned in prose, and overwrite is undocumented in both places. Adequate, but no added parameter meaning.

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

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

Specific verb and object: 'Measures an image for the empty band generated art often leaves at an edge' and 'returns how much of the frame it takes, plus a crop that removes it'. That is far more discriminating than sibling names like design_audit or media_probe, which are not named but are also clearly not about edge-band detection. No explicit sibling routing, so it stops short of a 5.

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

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

'Run it on a draft before compositing and on the final file before shipping' gives two concrete moments to call it, which is real context rather than implication. No when-not-to guidance and no statement of what to do if the tool is a poor fit (e.g. an image with an intentional border), so no exclusion clause.

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

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

With no annotations, the description carries the full behavioral burden and does disclose two non-obvious traits: no text is drawn onto the image, and the result is a position-to-file mapping rather than baked-in labels. It omits overwrite behavior, error conditions, and how output_path conflicts are handled, so the mutation side is under-disclosed.

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

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

Two sentences, both earning their place, with the core action front-loaded and the return-format caveat second. No filler or restated 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?

With no output schema and no annotations, the description appropriately covers the return value (position-to-file listing in reading order) and the 12-image ceiling. Remaining gaps are minor: side effects of the required output_path and overwrite are left implicit.

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

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

Schema coverage is 75%, so most parameters are already documented ('roughly square grid' default for columns, example output path). The description's 'up to 12' merely restates maxItems:12 and it says nothing about columns or overwrite, adding little beyond the schema. Baseline 3 fits.

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 — putting up to 12 draft images onto a single grid — and names the concrete upstream source (image_generate directions) that produces the inputs. An agent can tell this apart from compose/deliver/media_optimize 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?

Clearly says when this tool applies: judging several drafts against each other rather than one at a time. It does not name an alternative to use instead when comparison isn't the goal, so it stops short of full 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?

With no annotations, the description carries the load well: it discloses cropping behavior ('cropped to fill'), the quality strategy (lowest JPEG quality that passes SSIM), metadata stripping, enforcement of per-platform size limits, and a post-hoc empty-band validation. Gaps remain around overwrite behavior when the target exists and what the tool actually returns, but the mutation semantics are mostly spelled out.

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 pipeline are front-loaded in the first clause, before the reference-style platform table, which is the right ordering. The platform enumeration makes the single sentence very long and comma-heavy, but each entry carries distinct resolution/intent/size information 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?

For a four-parameter tool with no annotations and no output schema, the description covers the processing contract, per-platform target semantics, and size ceilings — enough for an agent to call it correctly on the first try. Only overwrite semantics and return-value expectations are unaddressed, which are minor against the overall coverage.

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

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

Schema coverage is only 25% (only output_path is documented), so the description must compensate — and it does heavily for the most important parameter, giving every platform enum value a resolution, use case, and in some cases a byte limit (2 MB YouTube, 1 MB GitHub). input_path and overwrite are not explained anywhere, and overwrite's default-false implication is left implicit, so it is not fully compensating.

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 concrete verb and outcome: turn a finished image into the exact file a platform expects, and enumerates the processing steps (crop-to-fill, JPEG/SSIM, metadata strip, size cap, empty-band check). The platform list with dimensions and intent makes the scope unmistakable and lets an agent tell it apart from neighbors like social_sizes or media_optimize even without naming them.

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?

'One step from a finished image to the file a platform wants' establishes when to reach for it, and several enum entries carry real disambiguation guidance (linkedin-link is a 'link preview card, not a feed post'; instagram-story needs text kept out of the top 14%/bottom 20%). It stops short of naming sibling alternatives (compose, media_optimize, social_sizes) or stating preconditions such as source image requirements.

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

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

With no annotations, the description carries the burden well: it discloses side effects (revise marks rejected, ship marks shortlisted), server learning behavior, and that measurements can cap scores. Gaps remain around auth, error cases, and durability of the shortlist/reject state, but the key behaviors are disclosed.

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

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

Front-loaded with the core action and return values, then the side-effect guidance. The back half is dense but each sentence carries distinct information; only the learning-loop explanation drifts toward verbosity.

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 a 5-param nested tool with no output schema and no annotations, the description covers the workflow (look, score, submit), returns, and side effects. Missing only return-shape details for revises beyond 'weakest points and exact fix' and behavior for planned_edges.

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?

At 60% schema coverage, the description adds real meaning: it explains the file lifecycle consequence, why asset_type and style matter, and provides the eight criterion keys expected in scores. It doesn't explain planned_edges or why scores is free-form/additionalProperties, which is a notable omission but not fatal.

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: score a generated image 0-5 on eight named criteria and get a ship/revise verdict. The named criteria and return values distinguish it clearly from siblings like composition_check or design_feedback.

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 call after LOOKING at the image, and that calling with no scores returns the criteria. It also states what to pass and why (asset_type for learning, file for lifecycle marking, style so defaults can be suggested), which is strong when/when-not guidance.

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

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

With no annotations, the description carries the transparency burden and does disclose non-obvious behavior: quality defaults to premium, omitting overlayText changes the composition request, and very wide targetAspect values change the composition guidance. It does not state whether the call is read-only/side-effect free or whether guidance depends on a prior brand_profiles lookup, leaving a small gap.

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 most decision-critical instruction (call before generation) is front-loaded, and every sentence adds information with no filler. Slightly dense in the second half where context-population rules and the exactText caveat stack up, but nothing is expendable.

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 complex tool with deep nested objects, no annotations, and no output schema, the description covers what is returned and how to prime it well. It leaves unstated how `brand_id` and the inline `brand` object interact and what happens if project_profile is unavailable, which matters for a tool whose output quality hinges on that context.

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

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

Schema description coverage is only 33%, so more compensation was needed. The description adds real meaning for `context` (fill from project_profile and the conversation, exactText for every word) but says nothing about `asset_type` — the primary required enum with 13 values — or how `brand_id` relates to the nested `brand` object.

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 action and output: it returns designer-grade guidance (concept directions with ready prompts, critique checklist, iteration process) rather than the asset itself. It explicitly distinguishes itself from image_generate and video_generate by positioning as the pre-step, so an agent can route correctly 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 an explicit ordering rule — 'Call this BEFORE image_generate or video_generate' — naming the alternative tools and the condition that triggers this one. It also tells the agent how to populate `context` from project_profile and the conversation, and calls out the exactText requirement for word-bearing asset types.

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

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

With no annotations present the description carries the full burden, and it does: persistence is disclosed ('kept in a local journal on this machine'), the downstream effect is spelled out ('every later design_brief applies it'), and the propagation mechanism is separated by type (image corrections become prompt instructions, text/logo corrections become compositing_rules). The brand-leakage warning ('so it never leaks into another brand's work') is exactly the kind of cross-call side effect an agent cannot infer 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?

The trigger is front-loaded in the first sentence, followed by persistence, propagation, scoping, actions and the file flag — a sensible order with no filler. It is dense to the point of being a single run-on block, which costs a little scanability but wastes no sentences.

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 an 8-parameter, annotation-free, no-output-schema tool this covers the essentials: when to call, what is stored, how it is later applied, how to scope it, and how to inspect or delete entries. It falls short only on asset_type and the applies_to override, and on what a 'list' entry actually looks like — the latter matters because 'time' must come from that listing to forget an entry.

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 75%, but the description still adds meaning beyond it: brand scoping is explained with a concrete example and the note that it matches brand.name in design_brief, and 'Pass file to mark that draft rejected' clarifies the add-mode effect of that parameter. However, applies_to and asset_type — two parameters that shape how the correction is applied — are never mentioned in the description, leaving the agent to rely on schema text alone for them.

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

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

It states a specific action (record/correct) and resource (user feedback/journal entries) and ties it to a concrete trigger: 'When the user says something about a result was wrong ... call this right away with what was wrong and what they want instead.' The distinction from design_brief is made explicit through the propagation rule, so an agent can tell the two apart 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 an explicit when-to-use trigger (a correction about colour, crop, empty band, text, wrong logo), a when-to-scope rule ('Set brand when the correction is about one brand'), and per-action guidance (list shows stored entries, forget removes one by time, file marks a rejected draft). Nothing about the mode selection is left to inference.

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

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

With no annotations, the description carries the burden and does real work: it discloses the default output location (<project>/.ai-media/<provider>/), the credit-cost implication of higgsfield and the max_credits cap, provider reliability ranking, and that failed fallback attempts are reported. Still missing permission/account prerequisites (the accounts_login / accounts_status siblings hint there are auth steps) and overwrite 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?

Front-loaded with the core action and effect, then operational details. Dense with parentheticals but nearly every clause carries decision-relevant information; the one instructional aside ('Look at the result yourself') is short and useful.

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 an 11-parameter, no-annotation, no-output-schema tool, the description covers the hard parts: provider selection, cost gating, default save location, and retry semantics. Gaps remain on auth prerequisites, overwrite semantics, and the shape of the returned result beyond 'attempts and failures are reported'.

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 64%, and the description compensates where the schema is silent: the provider parameter has no schema description, but the text enumerates codex, chatgpt, flow, gemini, higgsfield and JSON-defined sites with traits and cost notes, and it explains the output_path default location. It does not add meaning for aspect, model, overwrite, or count beyond what the schema already says.

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 (generate one image) plus the side effect (saves the full-quality file inside the project), which cleanly separates it from video_generate and video_edit among the siblings. It even flags that Flow and Higgsfield can return several images despite the singular name.

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 operating guidance: quote before spending credits on higgsfield, call providers_list for JSON-defined sites, use fallback_providers with ordered retries, and inspect the result before using it. It stops short of explicit when-not-to-use routing (e.g. versus video_generate or asking the user for a provider preference), so it is clear context rather than full alternatives coverage.

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

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

With no annotations, the description carries the behavioral burden and does well: 'compares' and 'reports' imply a read-only check, and it explains what low similarity means in practice. It does not explicitly state side effects, permissions, or expected output shape, leaving minor gaps.

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

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

The description is compact and front-loaded: it starts with the intended use case, then explains the check, then interprets low similarity and remediation. Every sentence adds relevant information without repetition.

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

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

For a simple one-parameter check with no output schema, the description explains purpose, method, result interpretation, and remediation well. It remains slightly incomplete because the lone input parameter and exact return shape are not described.

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

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

Schema description coverage is 0% for the single input_path parameter, so the schema provides almost no semantic help. The description only indirectly indicates the input is a looping video and gives no path format, file constraints, or accepted video details.

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

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

The description states a specific verb and resource: it compares a video's first and last frame and reports looping seamlessness. It also differentiates the check from media_optimize by explaining that this is the loop-seam use of a similar similarity check.

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 scopes use to background-video or product-video assets meant to loop, and it says what to do when similarity is low: regenerate with motion that returns to the starting point. It does not explicitly name exclusions or alternative sibling tools, so it is strong but not complete.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses deletion scope, safety boundaries (only .ai-media, final assets untouched), conditional deletion of used drafts, dry-run default, and automatic cleanup. It does not explicitly state irreversibility or permissions, leaving some destructive-action context implicit.

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 purpose and retention rules, then safety boundaries, then dry_run behavior, then automatic cleanup. Every sentence adds useful information without waste.

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 mutation/cleanup tool with no annotations and no output schema, the description covers scope, safety, defaults, deletion mode, and automatic behavior well. It could be more complete by stating irreversibility or what a non-dry-run call returns, but the core operational context 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 coverage is 75%, and the description adds meaningful semantics for dry_run and the three age thresholds in prose. It explains what the thresholds represent (rejected, used, untouched drafts) and default behavior. It does not directly map parameter names to each threshold, but the meaning is clear.

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: removes old drafts from <project>/.ai-media. It also defines the three cleanup categories, making the purpose much clearer than the title alone. It does not explicitly differentiate itself from any sibling tool, so it falls short of the top score under the rubric.

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 default behavior (dry_run true lists candidates) and how to actually delete (dry_run false). It also notes automatic cleanup once per session unless auto_cleanup is off, which is important usage context. It does not name explicit alternatives or when-not-to-use conditions, so 4 rather than 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?

Without annotations the description carries the full burden and does most of it well: it discloses the default metadata stripping (EXIF, XMP, C2PA, text chunks), notes the result lists what was removed, offers keep_metadata as an escape hatch, and states the invisible-watermark and original-file guarantees. Gaps remain on the overwrite semantics, keep_audio, and error 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?

Front-loaded with the primary outcome and format behavior, then the quality mechanism, then the metadata warning. The 'Behaviour notice' paragraph is long but earns its place given no annotations exist; a slightly tighter phrasing of the metadata sentence would improve it.

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?

Good coverage of the destructive-surprise axis (metadata stripping, original preservation) and a partial return-value hint ('the result lists what was removed') in the absence of an output schema. But for a 7-parameter mutation tool it leaves overwrite, max_width, and keep_audio wholly unexplained, which is a real completeness gap for calling it correctly.

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

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

Schema coverage is only 43%, so the description must compensate. It does add real meaning for format/output_path fallback logic and keep_metadata (including the config dependency that the schema only hints at), but max_width, overwrite, and keep_audio are documented nowhere — those three are fully silent.

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 (optimize/shrink) applied to a specific resource (image or video), and enumerates the concrete transformations: WebP/JPEG/PNG for images, H.264 with faststart for video, size reduced via SSIM-targeted quality. This clearly separates it from media_cleanup, media_probe, and video_edit in the sibling list.

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

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

Provides one concrete usage context ('places like LinkedIn post uploads that don't take WebP'), which is genuinely useful for routing. However, there is no explicit when-not guidance and no named sibling alternative (e.g. 'use media_probe first to inspect' or 'use media_cleanup to remove files'), so the agent must infer the rest of the decision boundary.

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

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

No annotations exist, so the description carries the full burden and does not say whether the call is read-only, what happens on unsupported codecs or corrupt files, whether remote URLs are accepted, or how large files are handled. It does usefully pre-declare the returned fields, which is some behavioral value beyond the name.

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?

One tight sentence with the most useful information (the returned fields) front-loaded and no filler. It is efficient but omits the action verb, which slightly reduces usability per word.

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 annotations and no output schema, the description does compensate by enumerating the returned metadata fields. However, it leaves the required parameter undocumented and says nothing about error conditions or path conventions, which are the main remaining gaps for a one-parameter inspection tool.

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

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

Schema coverage is 0% and the single parameter input_path is never mentioned, so the agent gets no statement of whether it must be a project-relative path, absolute path, or asset ID. The phrase 'inside the project' weakly implies path scoping but does not document the parameter.

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

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

The description names the resource (an image or video in the project) and the exact outputs (duration, size, frame rate, codecs), so an agent can infer this is a read-only metadata probe. It does not explicitly contrast with siblings such as media_cleanup, media_optimize or background_remove, and it is phrased as a noun list rather than a verb, so it stops short of a top score.

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

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

There is no statement of when to call this versus media_optimize, media_cleanup or video_edit, and no prerequisites or exclusions are given. The only implicit cue is 'inside the project', which narrows scope but does not guide selection.

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

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

With no annotations, the description carries the full burden, and it does disclose the output shape (hex codes, coverage shares, ordered --palette-1..N names, ready CSS block) and clarifies that ordering is by pixel coverage, not semantics. It says nothing about failure modes — invalid path, unsupported or missing image, very low-diversity images — which matters for a filesystem-reading 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?

Three sentences, front-loaded with what it returns, followed by the naming convention and interpretive caveat. The closing 'decide yourself' sentence earns its place by preventing misuse, though it 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?

For a 2-param, no-annotation, no-output-schema tool, the description conveys the return structure well enough that an output schema is less necessary. But the undocumented `count` parameter and the absence of any error/format expectations leave real gaps an agent would hit on first call.

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

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

Schema description coverage is 0% and the description never mentions the `count` parameter, which controls how many colours are returned (1-12, default 6) and directly shapes the output. `input_path` is only obliquely implied by 'a real image'; the agent must infer it is a path to a local file rather than a URL or asset id.

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: reads dominant colours from an image and returns hex codes with coverage shares plus a :root CSS block. The 'colour histogram, not a brand decision' framing clearly separates it from generative siblings like image_generate or brand_profiles.

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 names the input context ('a generated hero, banner or any photo') and tells the agent to interpret the output itself rather than treat it as a brand decision, which implies usage. However, it never states when to prefer this over alternatives (e.g. brand_profiles for existing brand colours) or what conditions make it inapplicable.

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

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

With no annotations, the description carries the burden and does declare read-only semantics, that reference images must be opened by the agent rather than embedded in the result, and that it is a prerequisite step. It does not say anything about latency, cost, or the shape of the returned profile, which keeps it below 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?

Three sentences, front-loaded with what is scanned, followed by the workflow step and the override rule. The inventory of signals is dense but each item is load-bearing for interpreting the result, and nothing is restated from structured fields.

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 zero-parameter, read-only tool with no output schema, the description covers the important ground: what is scanned, sequencing, and the user-override rule. The one remaining gap is the shape of the returned profile that gets handed to design_brief, which the agent must discover at call time.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; it correctly spends no words on inputs. Baseline 4 applies for a parameterless tool.

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 ('Read-only scan of the project') and enumerates exactly what it inspects: 3D/animation libraries, tone of wording, brand colours, fonts, theme, and reference images. It is clearly separable from design_brief, which it explicitly feeds, and from design_audit/design_feedback.

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

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

Gives an explicit ordering ('Call it first... then pass the result to design_brief') and names the downstream consumer, so the agent knows its place in the workflow. It also states a precedence rule — a user-stated level like 'premium' or 'minimal' overrides the inferred profile.

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

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

With no annotations, the description carries the full burden. It discloses the data sources (built-in plus JSON specs from ~/.no-api-media/providers), which is useful behavioral context, but it does not describe what is returned, whether it is always safe/read-only, or how missing/custom specs are handled.

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 with no wasted words. The key source information is front-loaded, though the second sentence is somewhat vague about what 'what each can make' entails.

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 zero-parameter list tool with no output schema, the description should probably explain the return shape—for example, provider names and capabilities. It hints at capabilities ('what each can make') but does not fully describe the returned structure, leaving an agent to infer the output.

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

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

The tool has zero parameters, so the baseline is 4. There are no parameter semantics to explain, and the description correctly does not pretend otherwise.

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 resource being listed (built-in providers plus JSON specs from a specific path) and that each entry shows what it can make. The tool is understandable as a provider inventory, but the description does not explicitly differentiate it from siblings such as accounts_status or usage_report.

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

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

There is no guidance on when to call this tool versus alternatives like accounts_status or accounts_login. The implied use case is discovering available providers, but no conditions, exclusions, or routing hints are provided.

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

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

With no annotations, the description carries the full behavioural burden. It usefully discloses the output location ('Files go to the output folder named after each preset') and warns that some banner sizes crop differently per device, but it says nothing about what happens when an output file already exists (the schema's overwrite default implies a possible failure or skip), whether the operation is idempotent, or what filesystem access is required.

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 verb and the output list, then the fit guidance, then the crop caveat. Dense but every clause carries usable information. The preset enumeration is long but directly maps to the enum values, so it earns its space; the device-crop advice is the only sentence bordering on advisory 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 6-parameter, no-output-schema, no-annotation tool, the description covers purpose, fit choice, preset scope, and output destination adequately. The gaps are behavioural rather than definitional: how overwrite=false is handled, whether pad_color only applies in pad mode, and what the tool returns (paths? a manifest?) are not conveyed.

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 50%, and the description compensates well for the two most consequential parameters: the three fit modes are explained in richer, more practical terms than the schema ('contain … whole image on a blurred copy of itself, logos and posters'), and the preset families are grouped by platform. It adds no meaning for pad_color, overwrite, or input_path beyond what the schema shows, which keeps it below a 5.

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 and resource: 'From one image, makes the sizes people need', followed by a concrete enumeration of the platforms and formats produced (Open Graph, LinkedIn, X, Instagram, YouTube, favicon/app icons). An agent can immediately tell this is a batch resize/export tool and distinguish it from siblings like image_generate or compose.

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 useful guidance on which fit mode to choose (cover for photos, contain for logos and posters, pad for solid colour) and a centring tip for Facebook/YouTube crops, which implicitly tells the agent when each mode applies. However, it never states when to use this tool rather than a sibling such as compose, image_generate, or media_optimize, and no exclusions or prerequisites 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?

No annotations exist, so the description carries the full burden and does well: it discloses that nothing is uploaded, that it only reads files the server wrote on save, and where those files live. It doesn't state cost, latency, or whether the report is cached, but the trust-relevant behavior is covered.

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

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

Two sentences, zero filler. The data source and the dimensions of the report are front-loaded, and the second sentence immediately answers the security question an agent would have.

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 does the work of explaining what comes back: counts of images and videos broken out by provider, format, and day. A sentence on the return shape (e.g. tabular vs. nested) would make it fully self-contained.

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 single optional since_days parameter is fully documented there. The description adds no syntax or meaning beyond the schema, which is the baseline case.

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?

Uses a specific verb+resource: totals the project's own .ai-media/manifest.jsonl and reports counts by provider, format, and day. That is far more precise than the title 'Local usage summary', though it doesn't explicitly contrast with neighbors like media_probe or media_cleanup.

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 scope ('this project's own manifest') implies when to reach for it, and 'this only reads' signals it's a reporting call. But there is no explicit when-to-use vs. when-not, nor a pointer to the sibling tools that answer related questions.

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

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

With no annotations, the description carries the full burden; it does disclose the local/ffmpeg processing model and the one-op-per-call constraint, which are useful behavioral facts. But it is silent on mutation semantics: overwrite defaults to false, output_path handling, and what happens to the source file are all undisclosed for a tool that writes media files.

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 sentence with the governing rule ('one operation per call') front-loaded, then a scannable parameter→operation mapping, closing with the chaining hint. Every clause carries information, though the run-on comma structure makes it slightly harder to parse than a short bulleted form.

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 25-parameter, no-annotation, no-output-schema tool, this covers enough to invoke correctly: operation selection, per-operation arguments, local execution model, and multi-edit chaining. The remaining hole is output/overwrite behavior, which matters for a file-writing operation but is at least partly discoverable from the schema defaults.

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

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

Schema coverage is 0%, so the description must compensate, and it largely does — nearly every parameter is bound to its operation (trim→start/end, reframe→aspect/fit, gif→start/duration/width/fps, text→text/position/size/color/box, logo→logo_path/position/width_percent, concat→others). Gaps: input_path, output_path, and overwrite are never explained, and 'position top|center|bottom' omits the four corner values available in the enum for logo placement.

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

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

The description starts with a specific verb+scope ('One operation per call, all local with ffmpeg') and then enumerates all 12 supported operations with their key parameters, so an agent knows exactly what this tool does. The title also clarifies it works on images for text/logo overlays, distinguishing it from video_generate (creation) and media_optimize (compression).

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?

'One operation per call' plus 'Chain calls for several edits' gives explicit usage structure, and 'all local with ffmpeg' implies no upload step. It does not, however, name when to prefer this over siblings like media_optimize or video_generate, nor state prerequisites such as whether input_path files must already exist locally.

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

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

With no annotations, the description carries the full burden and does disclose the key behavior: both providers spend credits, the cap is a hard cap, and if the real cost exceeds it nothing is generated. It omits what happens to partially spent credits, whether existing files are clobbered by overwrite, and any auth requirements.

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, each doing distinct work: provider selection, the credit-cap procedure, and the confirm_spend exception. The most consequential rule (call video_quote first) is front-loaded rather than buried.

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 10-parameter spend tool with no annotations and no output schema, the description covers the money-safety story well but leaves the file story — output_path and overwrite — unaddressed. An agent could call it correctly but might silently overwrite an existing video.

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 30% across 10 parameters, and the description compensates for provider, max_credits, and confirm_spend, while the schema itself documents model and duration. Overwrite, output_path, aspect, and quality are explained in neither place, leaving the destructive overwrite and the output destination ambiguous.

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 clear verb and resource — it generates video, and spells out the two provider backends (flow vs. higgsfield) with their model families. It doesn't distinguish itself from the sibling video_edit, but it does route to video_quote as a prerequisite, so an agent can place it in the workflow.

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 sequencing rule: call video_quote first, tell the user the cost, then pass max_credits. It also restricts confirm_spend to cases where the user has already agreed in chat, which is a real when/when-not condition. It stops short of saying when to prefer this over video_edit or image_generate.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses provider mechanics and the important fact that it generates nothing, but omits auth needs, whether opening/setting the Flow project persists state, rate limits, and return format.

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

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

It is two sentences with no filler and front-loads the provider branches. The compact "provider=flow:" shorthand is efficient, though slightly terse, which 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 5-param, no-annotation, no-output-schema tool, it covers the main provider branches and the no-generation guarantee. It still lacks return-value format/units, authentication expectations, and count semantics, leaving meaningful gaps.

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 40%, so the description must compensate. It adds useful semantics for provider, model, aspect, and prompt, especially the higgsfield prompt requirement for an exact quote, but does not explain the count parameter or clarify all aspect 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 states a specific purpose: quote credit cost for a generation, with provider-specific behavior, and explicitly says "Generates nothing," which separates it from generation siblings like video_generate. It does not explicitly contrast with usage_report or providers_list, so it is not a full 5.

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

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

It implies when to use it by provider and cost-quote purpose, but gives no explicit when/when-not guidance or alternatives such as video_generate or usage_report. An agent must infer that this is a pre-generation cost check.

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