Emero

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

With no annotations, the description carries the full burden and does well: it discloses the long-poll duration, the user-visible side effect of displaying the result, the two-part return (shown result + copy for the agent), progress reporting versus typical time, and that the percentage is coarse rather than an ETA. It does not cover what is returned or how to react when a job fails or is cancelled, which is the main 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?

Front-loaded with purpose and the 'no second call needed' payoff, and every sentence adds an operational fact rather than filler. It is dense and clause-heavy with caps emphasis, which slightly hurts scannability, but nothing is wasted.

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

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

For a 2-param polling tool with no annotations and no output schema, the description supplies the essential return shape (one image or a video poster frame) and full polling policy. The one missing piece is failure/cancellation behavior, which an agent would likely encounter while polling a render job.

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%; job_id has no schema description, but the description compensates by explaining it is 'the id it returned' from generate/combine_videos, which gives the agent its provenance. project_id is already fully documented in the schema, so no duplication 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?

States a specific verb+resource ('fetch the result of a generate / combine_videos job') and identifies the sibling tools that produce the id. It also distinguishes itself from a plain lookup by noting the result is both shown to the user and returned, so no separate view call is needed.

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 branching guidance: keep polling for short jobs, but for a long render 'STOP and hand off' and call once when the user returns, with an explicit 'don't poll in a loop' prohibition. It also explains the polling window (~30s) and which id to pass, so the agent knows exactly when and how to invoke it.

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 so richly: normalization to a common resolution/fps, concatenation, clamping of ranges, audio replacement vs. mixing, ducking via sidechain compression, per-clip volume, and the fact that output is free. It explains the effects of each mode rather than merely naming them.

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

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

Front-loads purpose and usage, then organizes detail under TRIM and AUDIO headings. It is dense and long, but for a 15-parameter tool with low schema coverage almost every sentence adds needed semantics; a small amount of tightening is possible but not much.

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 no output schema and low schema coverage, the description fills every gap an agent needs: id formats, ordering, trimming, per-clip audio, overlay mixing, ducking, and the no-cost output. Nothing essential for correct invocation appears missing.

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

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

Schema description coverage is only 13%, so the description must compensate, and it does: it explains the video_ids string vs. trim-object shape, seconds units for start/end/duration, max_clip_seconds behavior, audio_id/music_id sources, audio_mode semantics, clip/audio/music volume ranges, fade units, and ducking. The remaining project_id/project_name params already carry thorough schema descriptions.

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

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

States a specific verb and resource ('Join existing video clips into ONE continuous video') and explicitly excludes the sibling generate path ('NOT to generate new footage'). The scope and ordering constraint are clear enough to distinguish it from every sibling.

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 routing: call search_creations or get_settings when ids or order are unknown, and load_skill('combining-videos') when the skill isn't loaded. Also clarifies the generate alternative is wrong for this task, so when/when-not is fully covered.

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

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

Annotations only flag it as a non-idempotent write with open-world effects; the description adds the real behavioral load: billing at cost to the user's balance, the confirm:false/true two-phase commit that spends nothing until confirmed, and the side effect that brain_note is persisted to the project's Second Brain on confirm. It also encodes a hard constraint the annotations cannot express — the model is never switched for price or balance.

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 capability and cost statement is front-loaded, then the workflow, then the invariants — a sensible ordering for a 25-parameter orchestration tool. It is long and the arrow-chain middle paragraph is dense, but for this parameter count almost every sentence carries a rule an agent would otherwise get wrong.

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, non-idempotent generation tool with no output schema, it covers triggering, sequencing, cost gating, input binding and post-call verification. It stops short of describing failure handling, refunds on failed generations, or latency/polling expectations beyond naming check_generation.

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

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

Schema coverage is 100%, so the schema already documents every field; the description goes beyond it by adding cross-parameter rules that no single field carries, notably that references and frames never mix and that video_mode is mandatory whenever kind=video. It restates some schema content (ids never URLs, brain_note format), which keeps it from 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?

The first sentence names a specific verb (make) and enumerates the exact outputs (image, video clip, instrumental track, voiceover, upscale) plus the billing model. It explicitly separates itself from combine_videos for joining clips, so an agent can route correctly without opening any schema.

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

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

It provides an explicit ordered workflow with named sibling calls (load_skill → get_emero_brain → generate → check_generation), and states the when-nots: one generation per request, clips get joined with combine_videos, references and frames never mix. Alternatives and exclusions are both spelled out.

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 well: it discloses that the brain is shared across chats, devices and teammates, that an empty result means no brain exists yet, and that anchor ids are meant to be passed as reference_image_ids. It does not address permissions, error behavior, or size/response characteristics for very large brains, which keeps it short of 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?

Front-loaded with the read action and its contents, then the when-to-call, then the disambiguation cues. The long em-dash inventory of brain contents is dense but each element maps to a distinct part of the return value; it could be trimmed slightly but 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?

There is no output schema, so the description must describe the return shape — and it does, enumerating look-lock, rules, locked subjects with anchor ids, and per-project plus brand-wide decisions with ids. Combined with the call-timing guidance and the empty-state note, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and both parameters carry detailed guidance (minting the p- id, reusing it, renaming via project_name), so the schema already does the heavy lifting. The description adds nothing about project_id semantics beyond referring to "this project's" decisions and "the brand's other projects," so 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?

Specific verb and resource ("Read this brand's emero brain in full") followed by an explicit inventory of what the brain contains: look-lock sheet, style/model leanings, defaults, graded rules, locked subjects with anchor ids, and decisions. It separates itself from siblings by naming get_settings ("short version"), save_to_emero_brain (growth), and load_skill (shape).

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 trigger — "Call it before the first generation for a brand" — plus the rationale (anchors and look-lock reused for consistency). It also routes the agent to alternatives for adjacent needs: get_settings for the short version, save_to_emero_brain for writing, load_skill for the data shape.

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

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

Annotations already declare readOnlyHint and openWorldHint, so 'Read-only' and 'Changes nothing' are largely restatements. The description does add real value beyond them: the data is the live at-cost rate card with zero markup, and it discloses the shape of each model entry (price tiers by quality/resolution/duration/sound plus unit basis).

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?

Densely packed but front-loaded – the read-only guarantee and the resource come first, then filters, then return shape, then the usage trigger. Every sentence contributes; the only mild redundancy is 'Changes nothing' echoing 'Read-only'.

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 must convey the return shape, and it does: per-model price tiers with unit basis. Nothing is said about result size or pagination for the unfiltered full list, which is the one gap for a zero-required-parameter 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%, so the description carries the burden and does so: it enumerates the allowed kind values (image/video/music/speech/edit) and tells the agent that model expects an exact id. What it omits is whether model accepts partial matches or is case-sensitive.

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 every emero model's per-generation cost in USD – with the scope (live at-cost rate card, zero markup) made explicit. No sibling tool does anything similar, so no disambiguation is required.

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

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

Gives a clear trigger: 'Use it when the user asks what something costs or wants the full price list.' It also explains that filters are optional and how to narrow results. It stops short of naming an alternative or a when-not condition, but none of the listed siblings compete with it.

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 discloses that this is a read operation ('Read'), what data is returned, and that compact:true is a 'cheap' check that skips the catalog and brain. It does not mention permissions, rate limits, or error behavior, but for a read-only tool it provides solid behavioral context.

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

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

The description is front-loaded with what the tool reads and follows with usage guidance. It is a bit dense but every sentence contributes useful information; it could be slightly more scannable, but it is appropriately sized.

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 that there is no output schema and only two parameters, the description is complete enough: it enumerates the main return values and explains the compact mode. It does not describe the response format or error cases, but those are minor gaps for a read 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 description coverage is 50%: project_id is fully documented in the schema, but compact has no schema description. The description compensates by explaining that compact:true skips the catalog and brain for a cheap balance/spend/current-model check, adding meaning beyond the schema.

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

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

The description states a specific verb ('Read') and resource ('current generation settings') and enumerates the returned data (model, aspect ratio, quality, duration, resolution, sound, voice, speed, cost, balance, spend, brain view). It clearly distinguishes itself from set_settings (write) and from more specialized siblings like get_pricelist or get_emero_brain by being a combined read.

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

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

It gives explicit usage: 'Call it before each image or video' and 'show the user the model and cost first.' It also explains when to use the compact flag. It does not mention when to avoid this tool in favor of alternatives, but the primary context is clear.

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

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

No annotations exist, so the description must carry the full load and largely does: it discloses the return identifier format (`job:<uuid>#0`), the ≤8 image cardinality when passed to `generate`, the requirement that `url` be public https and that `file` needs a publicly reachable `download_url`, and the hard constraint never to base64 a file into the reply. The only untouched operator concerns are auth and rate limits, which are minor for this 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 capability and the returned id before the bullet list, and every bullet adds a real constraint. Minor deduction: the fragment "No UI" is cryptic on its own, and the base64 warning sits awkwardly mid-paragraph rather than with the other `file` guidance.

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 4-parameter nested-object tool with no output schema and no annotations, the description covers what an agent needs to call it correctly: inputs accepted, preconditions, the return value's shape, and exactly which sibling fields consume it. Nothing material is missing.

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

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

Coverage is split cleanly: the description supplies the semantics for `url` (public https image URL) and `file` (requires a reachable `download_url`, local paths fail), while the schema's own descriptions cover `project_id` and `project_name` in depth. Together every parameter is explained with more than type information.

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?

Opens with a specific verb+resource ("Store an image INTO emero's library") and immediately states the downstream purpose — anchoring a generation with a subject/product/character/scene. It explicitly differentiates from siblings by naming `inspect` for look-only and `request_upload` for local paths.

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 when-not-to-use rules: "To just LOOK at an image ... use `inspect`, not this," and "a local or sandbox path will fail — use request_upload instead." It also frames the selection criterion ("Only ingest_url the images you've decided to keep and reuse"), so the agent can decide without opening any schema.

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 a lot: it discloses that images are downscaled ~1024px, capped at 8, delivered at most once per project, that videos come as labeled contact sheets, and that include_details surfaces prompt/model/settings/inputs across any project of the brand. Gaps remain around error behavior and what happens if caps are exceeded.

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, then bullets map cleanly to parameters, ending with the sequencing constraint. Dense but nearly every clause carries operational information; a couple of phrasings ('AT MOST ONCE per project') are terse enough to risk misreading.

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 tool with no output schema and thin schema documentation, the description explains what comes back (visible image copies, motion contact sheets, generation metadata) and how to behave. Missing only edge-case behavior such as exceeding the 8-image / 20-id caps or failure modes.

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 20% (only project_id is documented), yet the description fully compensates: it defines artifact_ids as emero ids OR external https image URLs, gives defaults and semantics for images (downscaled copy, up to 8, once per project), include_details (exact prompt, model, settings, roles, project), and force (only after compaction). This is meaning well beyond the bare boolean/array 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?

States a specific verb and resource ('Look at assets yourself') plus a crucial scope distinction ('never shown to the user') that separates it from a user-facing view tool. It doesn't name the sibling `view` explicitly, so the agent must infer the contrast, which keeps it 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?

Gives explicit conditions and sequencing: 'Call it in its own step — after check_generation's result has arrived, not alongside it', 'pass force:true ONLY after your context was compacted', and two concrete purposes (review MOTION, rebuild a past prompt / debug repeated fixes). The when-not condition on `force` is exactly the kind of exclusion that prevents misuse.

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

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

With no annotations, the description carries the burden and does state read-only, the 12-item cap, the returned fields (status, embedded thumbnails, links), and that refreshes are live/lightweight. It does not cover failure modes or how skipping works beyond what the schema says, keeping it just short of 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 short sentences, front-loaded with the caller constraint that determines whether an agent should use it at all, followed by return contents and the alternative. Nothing is padding.

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

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

There is no output schema, yet the description says exactly what comes back (status, thumbnails, links, 12 newest) so an agent need not guess. Combined with fully documented parameters, nothing required to call or interpret it is missing.

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

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

Schema coverage is 100%: both 'have' and 'project_id' are fully documented in the schema, including the skipping behavior and project-id minting rules. The description only hints at refresh behavior ('live-refresh its tiles'), so the schema does the heavy lifting and a baseline 3 is appropriate.

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

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

States a specific verb and resource plus precise scope: the 12 newest creations in this chat's project, with status, thumbnails and links. It also declares the caller boundary (widget-only, the assistant never calls it), which distinguishes it cleanly from siblings.

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 who calls it (the inline creation widget) and who does not (the assistant), and names the alternative for the other job: use search_creations to find past work by description across every project. When-to-use and when-not-to-use are both covered.

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 discloses important traits: skills are cached per version, re-loading is required when a prior skill's steps disappear, and the name is a free string so new skills can appear without reconnecting. It stops short of describing the return format or confirming read-only behavior, but the essential operational 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?

The main action and first-use guidance are front-loaded, and most sentences earn their place by explaining caching, re-loading, and index lookup. The long inline list of skill names and the version parenthetical add some bulk that could be tightened, but overall the paragraph is appropriately dense.

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

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

For a one-parameter tool with no output schema and no annotations, the description provides enough context to invoke it correctly: when to load, how caching affects re-use, valid name examples, and how to discover the full set. It could be slightly more complete by describing the shape of the returned guidance, but nothing critical to invocation is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It does so by explaining that 'name' is a free string, listing concrete values (generate, index, make-image, make-video, make-music, make-speech, upscale-video, art-direction, combining-videos, organizing-generations), and pointing to load_skill("index") for the complete list.

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 ('Load') and resource ('emero's guidance for a task') and scopes it to 'before your first use of it.' It also distinguishes itself from sibling 'generate' by instructing that every generation should start with load_skill("generate").

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

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

Explicitly says when to call it (before first use), when to call it again (if prior steps are no longer visible), and which name to use for generation and for listing all skills via load_skill("index"). This leaves little 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?

No annotations exist, so the description carries the full burden, and it does: supersede moves the old entry to History linked to its replacement, delete is a restorable soft-delete, update edits in place, rescope moves scope, every change is logged and user-undoable, and locked entries have an extra guard. These are exactly the safety and side-effect facts an agent needs before mutating state.

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

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

The critical constraint is front-loaded and every clause is substantive. The long run-on sentences with nested parentheticals make it less scannable than a bulleted action list would be, but there is no filler.

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

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

For a 10-parameter mutation tool with nested objects, no annotations, and no output schema, the description still covers action semantics, safety/undo behavior, id provenance, prerequisite skill loading, and the user-consent gate. An agent can call it correctly without guessing.

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

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

With 80% schema coverage the baseline is 3, but the description adds cross-parameter meaning the schema cannot: it maps each action to its required ids/fields ('supersede old_id → new_id', 'delete id, reason', 'update id, fields', 'rescope id, scope'), says where ids come from, and reinforces the user_request_quote requirement. It stops short of restating every field's constraints, which is fine.

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 ('Change existing emero brain entries') and then enumerates five named actions with their precise semantics. It implicitly contrasts with save_to_emero_brain (create) and get_emero_brain (read), and the action list lets an agent distinguish this tool from all 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?

Explicitly says when NOT to use it ('ONLY when the user's latest message asked for it or reversed a decision, never on your own judgment'), names the prerequisite (load_skill first), gives a per-action exception (find_conflicts needs no quote), and a locked-entry override. That is the full when/when-not/alternatives triad.

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

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

Annotations declare idempotentHint=true and openWorldHint=true; the description adds the mechanism (slug-keyed replacement), the visibility consequence (live immediately, public library, share previews, email digest), and the server-side rewrite of {{gen:...}} tokens with real model, cost and prompt. It also discloses the brand/trademark policy and the auto-appended no-affiliation disclaimer, none of which are expressible in annotations.

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

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

Front-loaded with purpose and replacement semantics, then a tight per-field bullet list — efficient given seven required fields and no schema descriptions. It is long, and some bullets stack multiple illustrative examples where one would establish the rule, but essentially every sentence conveys a constraint an agent would otherwise get wrong.

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 nine-parameter, seven-required mutation with zero schema documentation and no output schema, the description covers input format, idempotency, the token/alt/cover relationship, the rename path and the human-approval gate. An agent could execute this correctly without further 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 coverage is 0%, so the description carries the whole burden and does: every one of the nine parameters is defined with format, length caps, examples and edge cases (slug pattern with a sample, seo_title max 60 chars, summary max 100 chars and no terminal period, alts keyed by artifact id, cover must be a body {{gen}} id, replaces takes the old slug). This is substantially more than the bare typed 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?

States a specific verb and resource ('Publish a tested workflow from this chat to the public library at emero.studio/workflows') plus the concrete side effects: it goes live immediately and lands in today's email digest draft. The re-publish semantics ('Calling again with the same slug replaces that post') clearly separate it from unpublish_workflow and from the generation tools.

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 triggers and exclusions: use replaces when renaming to a new slug, 'Never publish a renamed post without it, or the library shows the post twice', and to change a cover 'publish again with the same slug'. It also imposes a pre-call protocol: show the full post and get the user's go-ahead first.

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

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

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses the upload-card interaction, the returned upload:<id>, the need to wait for the user, the lack of polling, and the fact that a second call re-shows the card. It also explains that emero resolves the token to full-resolution 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?

The description is a single tight paragraph that front-loads the purpose and then flows into usage, waiting behavior, downstream token handling, and the no-repeat warning. Every sentence adds operational value with no filler.

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

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

Although there is no output schema, the description states the return value ('upload:<id>') and explains how to use it in generate or view. Despite the absence of annotations, it covers the key interactive and idempotency behavior an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so both project_id and project_name are already fully documented in the schema. The description adds no parameter-specific semantics beyond the schema, which is acceptable at this coverage level but does not exceed the baseline.

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 (show an upload card) and resource (the user's own image or video), and explicitly distinguishes this from ingest_url by limiting it to genuine human uploads. An agent can tell it apart from sibling tools such as generate, view, and ingest_url without opening their 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?

Gives explicit when-to-use guidance ('only for a genuine human upload — e.g. their client couldn't hand a file to ingest_url'), instructs the agent to wait rather than poll, says where to pass the resulting upload:<id>, and warns against calling it again for the same file.

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: it discloses persistence and cross-chat reuse, user editability, that grading never auto-replaces prior entries, and that a save can report possible conflicts requiring a follow-up question. It also adds a strong anti-invention constraint ('Save ONLY what the user actually said or did').

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 core instruction and the trigger are front-loaded, and nearly every clause carries operational content. However, it is one dense, unbroken paragraph with semicolon-chained clauses, making it hard to scan; some of the supersede/conflict guidance overlaps with the 'save only what the user said' constraint.

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 9-parameter mutation tool with no annotations and no output schema, the description is thorough on when to call, which kind, which scope, and conflict handling. Gaps remain on what a successful save returns, how title/summary should be shaped for non-'look' kinds, and any auth or failure behavior beyond the conflict report.

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 22%, but the description compensates heavily: every 'kind' enum value is defined with examples, 'scope' is explained including defaults per kind, and asset_kind/image_job_ids semantics are spelled out as reference-image ids. It also gives shape guidance for summary and detail on the 'look' kind.

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

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

States a specific verb and resource ('Save ONE real decision ... into this brand's emero brain') and enumerates exactly what counts as a saveable decision. The sibling separation is implied rather than named — it alludes to the brain tab where entries 'can review or edit' but never references get_emero_brain or manage_emero_brain by 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 an explicit trigger ('Call it when the user makes a brand decision'), then per-value guidance for each kind, scope selection rules with example phrases, and a conflict rule ('supersede only if the user's message replaces them, else ask'). It also names the escalation path — load_skill("emero-brain") — for the remaining ambiguity.

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 most of it well: it enumerates the returned fields (artifact ids, short description, age, model, project) and the exact shape of prompt_preview (~200 chars, no URLs), which substitutes for the absent output schema. It does not state read-only/non-destructive behavior, result ordering, or any cost/latency characteristics, so a small gap remains.

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 the primary purpose front-loaded, then the return shape, then the escalation path to inspect and the skill prerequisite. No restatement of the title and no filler.

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

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

For a tool with no annotations and no output schema, the description covers purpose, returned fields, and the follow-up tool, which is what an agent needs to act. The missing pieces are the semantics of the modality and limit parameters and confirmation that this is a safe read operation.

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

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

Schema description coverage is 0%, so the description must compensate and only partially does: it explains that 'query' is a natural-language description of the desired generation. The 'modality' filter and the tightly bounded 'limit' (3-8) get no mention at all, leaving two of three parameters undocumented anywhere.

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 ('Find the user's past emero generations') plus a scope qualifier ('across every project of the brand') and the matching mechanism ('natural-language description'). This is clearly distinguishable from list_project_creations and inspect, which it names as the detailed-lookup alternative.

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

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

Explicitly routes the agent: use this for natural-language discovery, then call inspect with include_details:true when the full prompt/settings are needed, illustrated with a concrete example ('make it like that earlier one'). It also states a prerequisite ('Load the organizing-generations skill first if you haven't'), so nothing about when to invoke it 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 so well: it discloses that values are validated and clamped to the chosen model's capabilities, that an unknown model is rejected, that the change persists as the base for future generations, and that the response includes updated settings plus cost. It does not say what happens with an empty call or whether any auth scope is required, which are the remaining 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?

Dense but front-loaded: the confirmation precondition and partial-update rule lead, and each subsequent sentence adds distinct information (validation, persistence, aspect-ratio map, rename scoping, return value). The mid-paragraph aspect-ratio aside slightly interrupts the flow between the settings and rename aspects.

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 14-parameter mutation tool with no annotations and no output schema, the description is unusually complete on behavior, guardrails and return values. The residual gap is parameter-level documentation for the model/quality/duration fields, which neither the schema nor the description supplies.

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 14% across 14 parameters, so the description must compensate, and it only partly does: it explains the aspect-ratio vocabulary (9:16 social/portrait, 16:9 YouTube, 1:1 square) and the rename semantics of project_name. The model names, speech_speed, video_duration, video_resolution, image_quality and video_sound still have no value guidance anywhere, so twelve parameters remain semantically thin.

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

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

Names a specific verb (change settings) plus a second explicit action (rename the project via project_name), which lets an agent separate it from read-side siblings like get_settings. It does not explicitly name get_settings as the read counterpart, so the differentiation is inferred rather than stated.

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 when-to-use rules ('AFTER the user confirms — never pick a model or format for them unprompted'), an exclusion for renaming another project ('tell the user to ask in that project's chat'), and an alternative path (project_name on generate/ingest_url). It also states the partial-update rule ('pass only the keys to change'), leaving little 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?

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds genuinely useful context beyond that: the underlying post survives and can be restored via publish_workflow, which tells an agent this is a reversible visibility change rather than data loss. It omits permission/ownership requirements and any effect on existing links to the published page.

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 filler; the action and scope come first, and the reversibility fact follows as the one piece of context that changes agent behavior.

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

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

For a single-parameter tool with rich annotations and no output schema, the description covers what happens, what is preserved, and how to undo it. Only the response behavior and ownership requirements are left unstated, which is a minor gap.

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

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

Schema description coverage is 0% for the single slug parameter, so the description must compensate. It confirms the identifier is a slug and that it refers to a published workflow, but gives no format, source, or example, leaving the agent to infer where the slug comes from.

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 (take off) and resource (a published workflow on the public library) with the keying identifier (slug). It also implicitly distinguishes itself from deletion by noting the post is kept, and names publish_workflow as the inverse operation, so an agent can place it precisely among siblings.

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

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

The description gives a clear condition for use (removing an item from the public library) and names the counterpart publish_workflow for the reverse action. It stops short of stating prerequisites such as ownership or auth requirements needed to unpublish, or explicit when-not-to-use conditions.

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 it well: it discloses the two critical behaviors — this NEVER returns the asset to the caller and NEVER stores anything — plus the required id formats. What it omits is the side-effect semantics of `force` and `show_user`, i.e. whether the display is suppressed or override-able.

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 core action and id formats come first, then each subsequent sentence is a single-purpose directive (don't inspect via view, don't store via view, don't re-show a fresh generation). Dense but zero filler, and the capitalized NEVER / Do NOT markers make the constraints scannable.

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?

Naming, routing, and the no-return/no-store contract are fully covered, and no output schema exists to explain. However, for a 6-parameter tool with 17% schema coverage, the meaning and effect of `force`, `show_user`, `return_image`, and `include_details` is absent, which an agent cannot infer safely.

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 17%, so the description must compensate. It covers `artifact_ids` thoroughly with concrete id formats ('job:<uuid>#<index>', 'upload:<id>', https URLs), but the four booleans — `force`, `show_user`, `return_image`, `include_details` — are completely undocumented in both schema and description, leaving half the surface unexplained.

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 (show assets inline to the user) and enumerates the accepted id formats. It actively distinguishes itself from three siblings by name — `inspect`, `ingest_url`, and `check_generation` — so the agent can route correctly without opening another 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 explicit when-to-use (show assets inline), when-not-to-use (do NOT call on a generation you just made, since check_generation already showed it), and the exact alternative for each adjacent need: `inspect` to view it yourself, `ingest_url` to persist an external image. 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.