Audora

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

With annotations already declaring non-destructive, non-read-only behavior, the description adds real value: it discloses that the result is a draft until scheduled, that media must already exist in the Library (Audora does not generate it here), and implicitly that nothing is published yet. It does not describe the return payload or error behavior, but the draft semantics are the key disclosure.

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 compact sentences that front-load the action and scope, then qualify with the moment distinction and draft status. No wasted clauses, though the reference to 'Promo's +' is an opaque internal pointer that costs a little clarity.

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 12-parameter mutation with full schema coverage and no output schema, the description covers scope, draft behavior, and media provenance adequately. It could say more about what the call returns or what happens on validation failure, but nothing essential for calling it correctly is missing.

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

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

Schema description coverage is 100% and the parameter docs are unusually rich (date window, angle semantics, hashtag limits, dry_run, idempotency). The description mirrors a few of these (words/caption, angle, media from Library) but adds little beyond the schema, 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?

The description names a specific verb and resource ('Add a post to a campaign') plus the scoping dimensions (one lane and day) and the content it carries (words, angle, media). It also distinguishes itself from a related concept ('not part of a moment'), though it never explicitly contrasts with the sibling update_post.

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 is a post on its own, not part of a moment, and a draft until it is scheduled' implies the context of use and that scheduling is a separate step. However, it never names an alternative tool (update_post, keep_post, skip_post) or states when not to use it, so the guidance is implicit.

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 mark it as a non-destructive write, and the description reinforces this by stating 'The release status does not change.' It adds context the annotations cannot: that the answer may be a rights/ownership statement Audora relies on, and that Audora is told it came through the assistant. It doesn't address the idempotency_key behavior beyond 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?

Action is front-loaded, and each sentence carries a distinct instruction (source tool, who answers, no guessing, attribution, post-call effect). Marginally long but no filler 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 a non-destructive write with no output schema, the description covers the workflow, the critical constraint, and the downstream consequence ('Audora reads the answer and moves the release on'). Return-value details are unnecessary here.

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 80%, so the schema documents most parameters. The description adds meaning to the answer parameter (in the artist's own words, may be a rights statement) but doesn't elaborate on dry_run, artist, or idempotency_key beyond what the schema already provides.

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

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

States a specific verb (Send) and resource (the artist's answer to a question Audora asked about their release), and cross-references the sibling get_release_questions so the agent can tell where the question came from. The distinction from other write tools is clear.

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 supplies a workflow: consult get_release_questions, ask the artist, then relay. The strong 'Never answer for them and never guess' constraint tells the agent what not to do when handling the answer. It lacks explicit exclusion conditions, but the routing is clear.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is largely covered. The description adds genuinely useful non-structured context by disclosing the side effect: 'Everyone invited or coming is told.' It leaves reversibility and retry semantics unstated even though the schema exposes an idempotency_key for exactly that concern.

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 core action is front-loaded before the side effect and the connection constraint. Every sentence carries distinct information.

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

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

With no output schema, the description does the work of telling the agent what happens as a result (invitees are notified) and which connection type is valid. For a destructive-feeling mutation it still omits reversibility, failure modes (e.g., cancelling an already-cancelled event), and what the response returns, but it is substantially complete for a tool this simple.

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 67%: `artist` and `idempotency_key` are well documented in the schema, but `event_id` (the sole required parameter) has no description anywhere. The description adds no parameter-level meaning beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb and resource ('Cancel one of the artist's events') and scopes it to a single event, which clearly separates it from list_events and save_event. It does not explicitly name or contrast with a sibling, so it falls just short of the routing clarity a 5 requires.

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?

'Artist connections only' gives a partial condition for use, but it is the only guidance offered and it sits in tension with the schema, where the `artist` parameter is documented as 'required for every artist tool on a label connection' — implying label connections may also call this. No alternatives, prerequisites, or when-not conditions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds the return content (record count plus per-record outcome), but says nothing about pagination, terminal states, or error reporting, so it adds modest value beyond the structured fields.

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

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

A single compact sentence with the resource front-loaded and zero filler. Efficient, though the casual title phrasing carries no additional routing information.

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

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

For a read-only status tool with no output schema, the description covers the headline return (count and per-record outcome). It omits what outcome values look like and whether long imports paginate, leaving minor gaps against annotations that already handle the safety profile.

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 50% schema coverage, the artist parameter is documented in the schema while job_id has none. The phrase 'or the one named' partially compensates by implying job_id selects a specific import, but no format or sourcing guidance is given.

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 resource (catalog import) and what it reports (how many records are in, and each record's outcome), so an agent grasps the intent. It does not explicitly distinguish itself from siblings like preview_catalog_import or import_catalog, keeping it below 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?

There is no explicit guidance on when to call this versus import_catalog or preview_catalog_import, nor any stated prerequisites. The parenthetical '(or the one named)' hints you can target a specific job, but the agent must infer the workflow context entirely.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuinely new context the annotations cannot: it evaluates the stores' intake rules against the uploaded master and cover, and it discloses the two-tier result shape (blocking items vs. things "worth a second look that does not block it"). Useful, though nothing on latency, caching, or how stale a prior check may be.

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 the core purpose before the format details and the call-timing advice. The parenthetical format list is dense but earns its place as concrete acceptance criteria. Slightly heavy for a read-only check but no real 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 read-only inspection tool with full annotation coverage, the description is complete: it states the applicable scope, what is inspected, the two categories of findings, and when to invoke it. No output schema exists, but the description already characterizes the response content, so there is no gap an agent must guess at.

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 artist, album_id and track_id, including the label-vs-artist connection rule and the mutual exclusivity of album_id/track_id. The description only restates "one track or one album" and adds no extra semantics, so the baseline 3 is correct.

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 concrete verb+resource: it audits one track or one album for what Audora still needs before submission, separating blockers from non-blocking observations. The scope is crisp and the return content is described. It does not, however, set itself apart from a plausibly overlapping sibling such as get_requirements, so it falls short of the 5 benchmark.

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?

"Call this after writing, and again before telling the artist something is ready" gives two concrete trigger points, which is clear contextual guidance. It stops short of naming alternatives or stating when NOT to call it (e.g., versus get_requirements or report_gap), so it is a 4, not a 5.

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

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

Annotations already establish this is a non-read-only, non-destructive, non-idempotent operation, and the description adds a genuinely useful behavioral trait not encoded anywhere else: the to-do 'comes back by itself when what it is about changes.' However it says nothing about the auth/roster requirement beyond the schema, or about the retry behavior of idempotency_key.

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 front-loaded sentences with no wasted filler; the core action leads and the caveat follows. The 'exactly as closing it in Audora does' clause is slightly flowery but earns its place by signalling the UI parallel.

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 tool with no output schema, the description covers the effect and its reversibility, which is the important part. It is still incomplete because it does not resolve the close_todo vs set_todo_done distinction or mention the label-connection requirement that the schema only incidentally covers.

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

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

Schema description coverage is 100% and the schema fully documents all three parameters (key, artist scoping, idempotency_key). The description adds no parameter-level detail, so the baseline 3 applies.

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

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

The verb+resource are clear (close a to-do) and the phrase 'the artist does not want to see' hints at dismissal rather than completion, but 'close' is a domain metaphor and the description never distinguishes this from the sibling set_todo_done, which an agent will inevitably confuse it with.

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-not: 'A track's or album's missing details are not closed: they are fixed,' steering the agent toward the correct handling. It stops short of naming the alternative tool and does not clarify the close-vs-mark-done boundary against set_todo_done.

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

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

Annotations already establish this is a non-read, non-destructive, non-open-world write that is not idempotent (with the idempotency_key param covering retries). The description adds the useful 'catalog can be split across pages' hint, implying repeated calls, but does not describe what actually gets recorded or the effect on the artist's catalog.

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

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

Four short, front-loaded sentences with no filler; the core action leads. The stylized fragment ('"That's me":') and clipped phrasing make it slightly cryptic, 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?

No output schema exists, so return values need not be described, and all three params are documented. The description covers the workflow, input constraint, and the ask-the-human rule, leaving only the downstream effect unstated.

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

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

Schema coverage is 100% and the schema descriptions already explain artist, deezer_ids, and idempotency_key. The description adds a genuine constraint beyond the schema: deezer_ids must be ones find_my_music offered, not arbitrary ids.

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 (record the candidates the artist said are theirs) and its resource scope, and explicitly distinguishes it from the sibling find_my_music by requiring 'only ids find_my_music offered.' An agent can tell this is the confirmation step that follows candidate discovery.

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 clear workflow context (use ids find_my_music offered; the catalog may be split across pages) and a firm rule: 'Ask the artist. Never confirm on a guess.' It stops short of enumerating when-not-to-use scenarios or naming other alternatives, but the intent is unambiguous.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds only the post-creation workflow hint and says nothing about auth requirements (e.g. the label artist requirement) or what the create actually persists.

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 terse sentences with zero waste, front-loading the action and then the next step. Nothing is padded.

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

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

With rich schema coverage, annotations covering safety, and the schema routing to get_requirements for field names, the description supplies the essential purpose and sequencing. It omits any note about what an album needs or how it relates to other entities, but nothing critical for calling 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 description coverage is 100%, so every parameter (artist, fields, dry_run, idempotency_key) is already documented in the schema, including non-obvious ones. The description adds no parameter detail, so the baseline 3 applies.

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

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

States a specific verb+resource ('Create an album or EP'), which clearly separates it from create_track, update_album, and list_albums. It does not explicitly name a sibling to contrast with, but the entity-level distinction is obvious.

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

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

The only guidance is the follow-up step ('Put tracks on it afterward with set_album_tracks'), which is a workflow hint rather than a when-to-use rule. There is no explicit condition for choosing create_album over alternatives or when not to use 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?

Annotations declare the safety profile (not read-only, not destructive, not idempotent). The description adds genuine context beyond them: media is a separate upload step, and idempotency_key is the mechanism to avoid duplicate tracks on retry, which usefully explains the idempotentHint=false setting rather than contradicting it.

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

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

Three short sentences, each earning its place: what it creates, what it deliberately omits, and the retry-safety mechanism. The scope boundary is front-loaded before the optional advice.

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 tool with no output schema, the description covers the key behavioral facts and the schema covers all parameters. The main omission is the prerequisite workflow — that field names come from get_requirements — which is only surfaced inside the nested schema, not in the description.

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

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

Schema coverage is 100%, so artist, fields, dry_run, and idempotency_key are all documented in the schema, including the get_requirements linkage for field names. The description adds no syntax or format detail beyond 'pass idempotency_key if you might retry', so the baseline 3 applies.

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

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

States a specific verb+resource ('Create a track') and immediately bounds the scope by excluding audio and cover art, which distinguishes it from sibling tools like update_track, set_track_artists, and request_upload. An agent can tell what this tool does and does not own 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?

Gives a clear conditional trigger for idempotency_key ('if you might retry') and implies the media-upload path belongs elsewhere. It stops short of naming alternatives explicitly (e.g. 'for audio/art use request_upload', 'to modify an existing track use update_track'), so no exclusion guidance is present.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and non-destructive, so the safety profile needs no restating. The description adds genuinely useful context beyond that: it discloses what is returned (a page URL plus a sentence describing the destination) and that no work is performed through this connection. It doesn't discuss auth requirements or the label-vs-artist connection nuance, keeping it from a 5.

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

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

The key behavior ('call this to get the exact page') is front-loaded in sentence two, and the bottom line appears immediately. There is mild redundancy between 'cover art' in the opening list and 'a cover' in the usage sentence, but no filler 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 a four-parameter tool with no output schema, the description covers what the tool does, when to invoke it, and what it yields — enough for an agent to call it correctly. The covered ground plus the structured schema entries for artist/album_id/track_id leaves no critical 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 coverage is 75%, so the schema documents artist, album_id and track_id, but leaves the required 'what' enum undescribed. The description compensates by enumerating the design categories in natural language, mapping them to the enum values and helping the agent pick the right one. It adds no format or edge-case detail beyond that mapping.

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 action (call this to get the exact page to send the artist to) and resource (Audora's design tools for logo, cover art, colors/typefaces, photos, promo). It clearly distinguishes itself by clarifying that the actual design happens inside Audora, not through this connection. It stops short of naming or positioning against any sibling tool, which would earn 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?

Explicit trigger is given: 'Use it whenever the artist wants a logo, artwork, a cover, visuals, photos or promo video made.' This is a clear when-to-use statement. There is no explicit when-not or named alternative, and no sibling tool overlaps, so a 4 is appropriate rather than a 5.

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

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

The description discloses a lot beyond the annotations: the file's contents (not its name) are inspected, invalid files are refused AND removed, and passing here is not equivalent to being releasable. However, 'the file is removed' describes a destructive outcome while destructiveHint=false, creating a tension an agent cannot resolve from the structured fields alone.

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, no filler, and the core action and the failure behavior are front-loaded before the forward reference to check_readiness.

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 mutating tool with no output schema, the description covers failure modes, side effects (removal), and the post-condition boundary versus check_readiness. It leaves unstated the success side effect (what the file is attached to) and the origin of upload_id, minor gaps given the annotation 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 67% (name and artist are documented; upload_id is not). The description does add a genuine disambiguation — 'the file itself, not its name' — clarifying that upload_id refers to file content rather than the optional name parameter, but it never says where upload_id comes from (presumably request_upload). Baseline 3 given partial schema coverage plus one useful clarification.

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

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

Specific verb+resource: it validates an uploaded file against the upload spec and attaches it only on success. It also actively distinguishes itself from the sibling check_readiness ('Passing here is not the same as being releasable'), so an agent can route correctly 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?

Gives clear when-not conditions (non-MP3 master, non-square or sub-3000px cover → refused) and names the alternative tool (check_readiness) for the releasability question. It does not explicitly name request_upload as the required predecessor or state the ordering, which keeps it short of a 5.

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

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

Annotations already cover the safe-read profile (readOnly, idempotent, non-destructive), so the description's real contribution is behavioral: it discloses that it queries external services (Deezer and Apple Music, with Spotify/Apple link input) and that output may be a single confirmed match or a candidate set. That candidate-vs-confirmed distinction is genuinely useful context not present in the 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?

It is short (two sentences) and leads with the purpose, but the first sentence is grammatically tangled and the colon list is hard to parse, costing clarity per word. No filler, yet the structure works against quick comprehension.

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

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

For a read-only, two-optional-parameter tool with no output schema, the description conveys the operation, the external sources, and the nature of the result (confirmed vs candidates). It stops short of describing what the agent should do with candidates or how it relates to the confirm step, but it is largely sufficient.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by clarifying that 'link' accepts Deezer, Spotify or Apple links and can point at either an artist or a specific record, and that supplying it replaces the name-based search. This adds source-format and mode-switching meaning the schema text ('a link to the artist's music') does not.

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 (resolving which Deezer/Apple Music artist matches this artist and pulling their released records) with a clear resource. It is distinguishable from siblings like confirm_my_music and list_releases, though the phrasing ('bring their released records in: the confirmed one, or candidates to show the artist') is roundabout and requires a second 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 implies usage by explaining that the confirmed match or candidates are produced and that a link searches from a link instead of a name, which hints at the find-then-confirm flow with confirm_my_music. However, it never explicitly says when to use this tool versus confirm_my_music, nor states any prerequisite or exclusion.

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?

Adds substantial behavior beyond the annotations: 1–2 minute duration, a per-artist daily cap shared with Soundcheck, first-lookup-free pricing, credit cost plus the artist's spend permission, and the fact that every returned fact carries its source pages. It also states it never mutates the profile, consistent with readOnlyHint=false (which reflects credit/state mutation, not profile writes) and destructiveHint=false.

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, then usage, cost, and status handling in a logical order, and every sentence carries distinct information. It is long and clause-heavy for a single paragraph, with minor editorial padding ('so the artist keeps what is theirs in Audora'), but nothing is truly redundant.

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

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

No output schema exists, yet the description covers the return contract ('every fact comes with the pages it was read on'), the async nature (1–2 minutes, status action), the pricing/permission flow, and the correct post-call handoff. An agent has everything needed to invoke both actions correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds workflow meaning the schema cannot: the dry_run → confirm_cost_credits sequencing, the default of 'status', and that status reads the newest run unless run_id names one. The link and not_me semantics live mostly in the schema, so it does not fully re-explain every 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?

States a specific verb and resource — running Audora's own artist lookup and reading its result — and distinguishes itself from siblings by naming update_profile (filling the page) and propose_profile (post-lookup handoff). It also carves out the 'do your own web search instead' case. The dual start/status nature makes the opening sentence slightly dense, but an agent can tell what this does.

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 ('only when you cannot search the web yourself'), the alternative ('look the artist up with your own search... fill their page with update_profile'), and the required follow-up after completion ('call propose_profile'). It also spells out the conditional cost workflow: dry_run to read the price, tell the artist, then start with confirm_cost_credits.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral value by disclosing a computed, live field: schedule_check reflects 'exactly what Audora's Schedule would decide about it now' rather than stored data, plus it surfaces 'what it still needs'.

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 front-loaded sentence that leads with the resource and then enumerates the returned fields, with no filler. It is dense with product jargon ('lane', 'Promo's calendar', 'Audora's Schedule'), which costs a little readability but not length.

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

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

With no output schema, the description correctly carries the burden of describing the return shape (posts by day and lane, words, hashtags, media, status, schedule_check) and it does so thoroughly for a two-parameter read tool. Auth/connection semantics are left to the schema descriptions, which is acceptable.

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%, with campaign_id and the label-only artist parameter both fully documented in the schema itself. The description adds no syntax, format, or conditional guidance beyond that, which is the expected baseline when the schema does the work.

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

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

The description states a specific resource and scope: one campaign rendered as a calendar of every post by day and lane with its content and status. That is enough to distinguish it from list_campaigns, though the 'Promo's calendar' / 'Audora's Schedule' framing is branded jargon rather than a plain verb+resource statement.

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 explicit when-to-use, when-not, or named alternative. The only routing hint ('From list_campaigns') lives in the schema, not the description, so the agent must infer that this is the detail fetch following the list tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety and repeatability are covered. The description adds only the pre-flight-check framing, with no detail on freshness, rate limits, or how allowances are computed. No contradiction, but little value beyond the structured metadata.

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

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

Two tight sentences with no filler, and the substantive content (returned fields) leads. The opening noun fragment 'The plan, whether distribution is included...' reads slightly awkwardly as a standalone, which keeps it from a 5, 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?

With no output schema, the description correctly carries the burden of listing the returned values, and it does so concretely. What an agent needs before uploading is present; only edge details (empty credits, expired plan behavior) are missing.

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

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

Schema description coverage is 100% and the single 'artist' parameter is fully documented in the schema, including the label-vs-artist connection rule. The description adds nothing about it, so the baseline 3 for schema-covered parameters applies.

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

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

The description names the resource (the account's plan) and enumerates exactly what it surfaces: plan tier, distribution inclusion, credits remaining, and track/album/storage allowances. That is specific enough to distinguish it from siblings like get_stats or check_readiness, though it lacks an explicit verb and never states that it is a read-only fetch.

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

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

It gives a clear triggering condition: 'Check before uploading or preparing a submission.' That is actionable context for an agent deciding whether to call it. It stops short of naming alternatives or stating when the call is unnecessary, so it is not a full 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The phrase 'as Audora holds it' adds a small but real signal that this is a canonical read rather than a staged/derived view, which helps distinguish it from propose_profile. It stops short of describing return content or any auth or scope constraints.

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 front-loaded sentence with no filler or redundancy. It is arguably over-compressed, but nothing in it 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?

The tool is simple: one optional, fully documented parameter, read-only annotations, no output schema. The description is adequate for that surface but does not state what the profile contains or how a missing profile is handled, leaving minor gaps for an agent deciding whether this call answers its question.

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 'artist' parameter is documented thoroughly in the schema (conditional on label connection, required for artist tools, source of the ID). The description adds no meaning beyond that, so the baseline 3 applies.

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

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

The description names the resource (the artist profile) and asserts it is the authoritative version Audora holds, which is a useful qualifier. But it supplies no verb and offers no differentiation from close siblings like propose_profile, update_profile, or whoami, so an agent cannot fully disambiguate from the text alone.

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 no when-to-use guidance whatsoever. The only routing information (label vs. artist connection, when to pass 'artist') lives entirely in the schema's parameter description, so the description itself contributes nothing toward selecting this tool over propose_profile or update_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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuine business context beyond structured fields: unanswered questions block a release, and the call returns the entire conversation, not just the question text.

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 front-loaded sentences that carry the resource, the blocking rule, and the filter rule with little waste. The middle sentence about unanswered questions blocking release earns its place as motivating context.

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

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

For a read-only, two-optional-param tool with no output schema, the description adequately conveys what is returned (questions plus the whole conversation) and both filter modes. A slightly clearer statement of the default behavior would close the remaining gap.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema (including the same 'omit for open questions' rule). The description adds only the note that a release_id call includes closed conversations, which is marginal over 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?

States a specific verb (retrieve) and resource (reviewer questions about the artist's releases) and clarifies that the full conversation is returned, making it clearly distinct from the write-oriented answer_release_question. However, it never explicitly names the sibling it contrasts with, so an agent must infer the read-vs-answer split.

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 the practical filter rule ('Omit release_id for every open question') and explains why the data matters (an unanswered question blocks release), which implies when to reach for it. But there is no explicit when-to-use comparison against alternatives like answer_release_question or list_release_todos.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description still adds genuinely useful behavioral context that annotations cannot carry: limits vary per field, some violations are refused while others are merely flagged, and the blocking rules are external and mutable. It does not describe output shape or pagination, but for a small spec lookup that is minor.

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

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

Four tight sentences, front-loaded with what is returned and then the imperative to call it first. Every sentence contributes, including the caveat about differing and mutable limits. No filler or redundancy, though the list-like first sentence is 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?

No output schema exists, so the description must stand in for it, and it does so by describing the kinds of data returned (field limits, closed lists, file formats and sizes). Combined with a fully documented two-parameter schema, an agent has enough to invoke and interpret this correctly. A brief note on scoping behavior when entity/release_type are combined would make it 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?

Schema description coverage is 100% and both enum parameters carry clear explanations ("Omit for everything", "An album needs more than a single"). The description itself says nothing about entity or release_type, 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?

The description names a specific resource and enumerates the exact content returned: per-field limits in characters or words, closed value lists, accepted file formats and sizes. It is far more specific than a restatement of the name. It does not, however, differentiate itself from the nearby sibling get_limits, which an agent could plausibly confuse with this tool.

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

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

"Call this BEFORE filling anything in" gives explicit, actionable timing guidance that tells the agent where this fits in the workflow relative to the create/update tools. It stops short of naming alternatives or stating when this tool is not the right choice (e.g. versus get_limits or check_readiness).

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 readOnly/idempotent annotations already covering the safety profile, the description usefully adds a conditional behavior: extra web-wide numbers appear only when the artist has connected their own Songstats account. It also instructs how to report missing values ('not reported yet', never zero), which materially affects output interpretation.

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 opening sentence is a long run-on list of data categories that is hard to parse and partly redundant with later sentences. Usage triggers and the 'not reported yet' rule are valuable, but the enumeration is bloated for what an agent needs to select and invoke the tool.

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

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

There is no output schema, so the description carries the burden of explaining returns and does so thoroughly, covering both track-level and catalog-level data plus the connected-account conditional. Complete enough to call correctly, with only minor ambiguity from the dense enumeration.

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

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

Schema description coverage is 100%, so the artist/album_id/track_id semantics are already fully documented in the schema, including the label-connection requirement and the leave-out-both meaning. The description adds no parameter-level detail beyond the schema 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?

The description clearly establishes that this tool returns performance metrics (streams, saves, growth, sources, audience demographics, socials) per track or for the whole catalog. It is specific about the resource and scope, though it never explicitly names a sibling it is distinct from, relying on the agent to infer the boundary against get_track or promo_results.

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 concrete triggers: answer 'how is my release doing', write a pitch or bio from real numbers, or suggest where to focus next, plus handling guidance for missing figures. It lacks explicit when-not or named alternatives, but the context is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds real context about what is fetched (billed artists plus song credits), but says nothing about error behavior, missing-track handling, or output shape.

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 front-loaded sentence with no filler or restatement of the name; every word conveys scope or payload.

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 low-complexity, fully annotated, fully documented single-record read with no output schema, the description is nearly sufficient — it tells the agent the returned payload. Only a pointer to list_tracks as the id source or a note on absent tracks is missing.

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

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

Schema description coverage is 100% and both parameters (track_id and the label-connection artist field) are well documented in the schema itself, including the label-vs-artist-connection rule. The description adds no parameter meaning beyond that, 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?

States the resource (one track) and enumerates the payload it returns — billed artists and song credits — which distinguishes it from a bare track lookup. However, it never names or contrasts with siblings like list_tracks, update_track, or set_track_artists, so sibling differentiation is missing.

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 when-to-use or when-not-to-use guidance. Given siblings such as list_tracks, set_track_artists, and set_track_credits, an agent gets no explicit signal that this is the read path for a single track versus the write paths for its credits.

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

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

The annotations already declare the mutation-safe profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description still adds real behavioral detail: covers are only imported when rights are artist-confirmed, otherwise records import without covers. It does not address the async nature hinted by 'Start' or the idempotency_key/idempotentHint tension.

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, purpose front-loaded in the first clause. The second sentence is dense but every clause earns its place by explaining the conditional cover behavior. 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?

For a mutation tool with no output schema, the description covers the cover/righths conditional well but omits the async handoff implied by 'Start' and the existence of catalog_import_status. An agent is not told whether this returns a job, a count, or needs polling, leaving a meaningful workflow 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 coverage is 75%, so artist and idempotency_key are already documented. The description reinforces rights_confirmed with an ethical nuance ('their own words, recorded as their consent') not in the schema, but adds nothing for items or the include flag. Baseline 3 fits given the schema does most of the work.

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

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

The verb+resource is clear: 'Start bringing the chosen records into the catalog.' An agent understands this is the actual import action. However, it never names or contrasts the closely related siblings preview_catalog_import and catalog_import_status, so sibling differentiation is left to inference.

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 no when-to-use guidance or routing against alternatives. It does not say to run preview_catalog_import first or to poll catalog_import_status, despite those siblings clearly existing. The rights_confirmed clause is a behavioral condition, not usage guidance.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent mutation. The description adds real behavioral context: the tool changes state back to draft, and a draft is a no-op. It does not mention auth/permission requirements (e.g., label vs artist connection) or whether the change is reversible.

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 zero wasted words; the primary action is front-loaded. The closing sentence 'A draft is already kept' is terse to the point of being slightly cryptic, which costs a little clarity.

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

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

A simple state-transition tool with full schema coverage and annotations, and no output schema to explain. What is missing is the return behavior (does it return the post/draft?) and the failure conditions when the post is not in an eligible state, which would materially help an agent call it confidently.

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

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

Schema description coverage is 100%, so the schema already documents artist, post_id, and idempotency_key in detail. The description adds a faint constraint (the post must be skipped/failed) but no format or identifier guidance beyond what the schema provides. Baseline 3 applies.

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

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

States a specific verb+resource transformation: take a skipped post or one that failed to send and bring it back as a draft. The trailing clause 'A draft is already kept' clarifies scope by excluding drafts, and the reversal nature distinguishes it from update_post or add_post. It does not, however, name the sibling it reverses (skip_post) explicitly.

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

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

The description implies when to use it by naming the two eligible post states (skipped, or did-not-go-out), which is useful context. But it never names the counterpart tool (skip_post) or states exclusions such as posts that are already scheduled or already a draft beyond the implicit hint.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and non-openWorld, so the safety profile is covered. The description adds the ordering behavior ('newest first'), which is genuinely useful and not in the annotations, but says nothing about pagination, result caps, or coverage limits on large catalogs.

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 short sentence with the scope and the ordering constraint front-loaded and zero filler. Nothing could be removed without losing information.

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

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

For a simple read-only list tool with rich annotations and a fully documented parameter, this is close to adequate. However, there is no output schema, so the description is the only place to signal what an album record contains and whether the list is paginated — neither is mentioned.

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 'artist' parameter is fully documented in the schema, including the label-vs-artist connection rule. The description adds no parameter meaning at all, so the baseline 3 applies.

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

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

The sentence names the resource (albums) and the scope (this account) and adds an ordering guarantee ('newest first'), so an agent knows this is a catalog listing rather than a mutation. It does not explicitly distinguish itself from sibling list tools like list_releases or list_tracks, and the list verb is only 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?

There is no when-to-use guidance and no naming of alternatives such as list_releases, list_tracks, or get_track, even though those siblings plausibly overlap in the catalog domain. The agent must infer that 'album' means don't use the track or release tools.

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

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

Annotations already cover readOnly, idempotent, non-destructive, and closed-world, so the safety profile is settled. The description adds real behavioral context beyond that: the campaign kind taxonomy (release vs between_releases), the fact that it also includes upcoming releases with no campaign and campaigns currently being planned. No return format or pagination details, but the domain behavior is well 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-loads what the tool returns, which is good, but the second sentence is a dense run-on packing domain taxonomy and lifecycle rules that could be tighter. Every clause carries information, but the phrasing is rambling rather than crisp.

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 carries the burden of explaining returns, and it does so concretely (window, status states, per-post counts, plus uncampaigned releases and in-progress campaigns). The only gap is the artist scoping, which the schema handles, so it is largely complete for a list 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 100%, so the artist parameter and its label-vs-artist-connection condition are fully documented in the schema. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific resource ('Every Promo campaign in this account') and enumerates the fields it returns (window, status, post counts), so the scope is clear. It communicates the 'all campaigns' aggregation distinct from a single-campaign read, though it never names get_campaign or another sibling directly.

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 the call is useful by describing what it returns and clarifies the campaign lifecycle ('none starts by itself: start_campaign with between_releases plans the next one'), which points to the start_campaign sibling. But it gives no explicit when-to-use-vs-alternatives guidance against siblings like promo_this_week, promo_results, or get_campaign.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured context: the result includes drafts that are 'saved, not posted, seen by nobody else' and shows who is invited versus who is coming, plus an authorization constraint (artist connections only). That is meaningful disclosure beyond the annotations.

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

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

Two sentences, front-loaded with what is returned and followed by the access constraint. The nested parenthetical about drafts is slightly dense but each clause carries information; 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?

With no output schema, the description does the work of describing the return payload (events, invitees, attendees, drafts) and the connection requirement. For a single-optional-parameter read tool this is close to complete; only pagination or ordering behavior is unaddressed.

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 'artist' parameter is thoroughly documented in the schema itself, including its label-connection requirement. The description adds no parameter-level syntax or format detail, so the baseline of 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 resource (shows, release parties, listening parties) scoped to what the artist has posted, which clearly separates it from the write-side siblings save_event and cancel_event. It never names a sibling explicitly, so it stops short of full differentiation, but the verb+resource is unambiguous.

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

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

The description supplies a real usage constraint — 'Artist connections only: Scene is between artists' — which tells the agent which connection context is valid. However, it gives no guidance on when to prefer this over save_event, cancel_event, or other listing tools, so the when/when-not routing is only implied.

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, idempotentHint, non-destructive and closed-world, so safety needs no restating. The description adds genuinely new behavioral facts beyond those: results are sorted newest first, and each preview link expires after an hour — a time-sensitivity detail an agent could otherwise miss and misuse.

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

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

Two sentences, front-loaded with what the tool returns and how it can be narrowed. The long parenthetical category list is dense but earns its space by decoding the enum; nothing is redundant.

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

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

With no output schema, the description correctly takes on the burden of describing returns (media_asset_id plus a one-hour preview link). The main residual gap is pagination behavior — limit/offset appear in the schema with only numeric bounds and no explaining text.

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 67%, and the description compensates by translating the enum values into user-facing category names (Brand kit, Cover art, Made by Audora, Found online, Stock footage), which is genuinely useful for mapping a user's wording onto the enum. It also clarifies search spans name plus the artist/track/album the item relates to. It says nothing about limit/offset semantics, so it is good but not complete.

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 (list) and resource (the artist's pictures or videos in Audora's Library) with ordering (newest first) and scope (the artist's). The closing note that each item carries a media_asset_id 'what update_post takes' gives a concrete downstream link, which helps distinguish it from sibling list_* tools even though no sibling is named as an 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?

Usage is implied rather than stated: the description signals the tool is the source of media_asset_id values needed by update_post, which is a real routing hint. However, it never says when NOT to use it, never names an alternative for browsing versus searching, and leaves the label-vs-artist-connection distinction entirely to the 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?

Annotations already declare a safe read (readOnlyHint, idempotentHint, non-destructive, closed-world), so the description need not restate safety. It does add real behavioral context by disclosing the complete status_label taxonomy the tool surfaces, which an agent cannot get from the annotations or the schema. It omits pagination, ordering, and result-size behavior, keeping it out of 5 territory.

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 ('Every release in this account') before the status detail, and there is no filler. The long inline status list makes it a single dense sentence, which is slightly harder to scan than a well-structured multi-sentence definition.

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 carries some of the burden and does so by specifying the status vocabulary and the inclusion of release questions. Annotations cover the safety profile and the sole parameter is documented in the schema. Missing pagination/ordering notes are the only notable 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 100% and the single optional artist parameter is fully explained there (label connection, artist_user_id or exact name). The description adds nothing about that parameter, and its 'every release in this account' phrasing is slightly at odds with the filtering the parameter enables. 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?

Clear verb+resource: it lists every release in the account, and it enumerates the full set of status_label values so the agent knows exactly what dimension is returned. It does not explicitly distinguish itself from near-siblings like list_albums or list_tracks, 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?

Usage is only implied: the agent can infer this is the call to enumerate releases, and 'including anything Audora asked about' hints at a relationship to get_release_questions/answer_release_question, but no alternative is named and no when-to-use vs when-not condition is stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, not open-world), so the bar is lower. The description adds useful context beyond them by disclosing the returned content: each todo's due timing, rationale, where it is performed, and completion status.

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

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

Two sentences, front-loaded with the release_id branching and zero filler. The parenthetical item enumerations are long but they earn their place by previewing the returned checklist contents.

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 carries the burden of describing returns, and it does so adequately by listing what each checklist item contains and the two list variants. Minor gaps remain (no mention of todo identifiers that would feed close_todo/set_todo_done), but it is complete enough to call correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the concrete output consequence of omitting release_id (switching to the 'Set up once' list) rather than just restating the field.

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 (list) and resource (release checklist) and splits the behavior into two clearly named modes: the release's 'Around the release' checklist vs. the artist's 'Set up once' list. An agent can distinguish it from sibling list_todos/list_tracks 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?

Explicitly states the condition that selects each mode (pass release_id vs. omit it), which is real usage guidance. It stops short of naming alternatives or exclusions relative to siblings like list_todos or the mutation tools (close_todo, set_todo_done), so it is clear context rather than 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?

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower, and the description clears it by disclosing ordering (most urgent first), the returned fields (what, urgency, location, fixing tool), and the 'key'/'closable' semantics tied to close_todo. The 'closable' contract is genuinely useful context beyond the structured fields.

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

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

Two tight sentences with the core scope front-loaded and the field/closability detail following. Every clause earns its place and 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?

With no output schema, the description sensibly enumerates the return fields and their meaning, and covers ordering and closability. It is close to complete for a single-parameter read tool, missing only a note on whether results can be empty or filtered.

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 only parameter (artist) is fully documented in the schema with connection-type conditions. The description adds nothing about parameters, 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?

States a specific resource (open to-dos across the artist's pages) and scope, and implies the list verb. It differentiates somewhat from list_release_todos by scoping to 'their pages' rather than a release, though it never names 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?

Usage is implied by the content (read the artist's actionable to-dos) and it cross-references close_todo via the 'closable' field, giving a hint of the downstream action. But there is no explicit when-to-use/when-not-to-use guidance or named alternatives, so it stays at minimum-viable.

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, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds the scope ('this account') and sort order ('newest first'), but says nothing about result limits or pagination, which matters for an unbounded list call.

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 short sentence with zero filler; the scope and sort order are front-loaded and no clause 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 simple, no-required-param list tool with a fully described schema and annotations covering the safety profile, the description is nearly complete. The one residual gap is the absence of any hint about result size or pagination behavior.

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

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

Schema description coverage is 100%, so the artist parameter's label-vs-artist-connection semantics are already fully documented in the schema. The description adds no additional meaning for the parameter, which is the expected baseline when the schema does the work.

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

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

States the resource (every track in this account) and the ordering (newest first), which is specific enough to separate it from get_track or list_albums by scope and intent. It does not, however, explicitly differentiate itself from other listing siblings such as list_releases or find_my_music.

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 stated when-to-use or when-not-to-use guidance, and no routing to alternatives like get_track for a single track or find_my_music for search. The only conditional logic lives in the schema's artist field description, not in the tool description.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: pagination size (50 a page), ordering (newest first), the three match outcomes against the catalog, that total is the grand count, and that the response also reports the plan's room for songs and albums.

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 the core content and no filler. It is dense but each clause adds information; the closing note on the plan's room is slightly tacked-on but still relevant.

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 usefully explains the return shape: match statuses, total, pagination and the plan-capacity figures. The main gap is that it never frames the call as a preview preceding import_catalog, but for a read-only tool whose annotations cover safety, it is largely 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?

Schema description coverage is 100%, so the schema already documents page, artist and deezer_album_ids fully. The description only echoes the ordering and page size, adding no syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema carries the load.

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 name preview_catalog_import and the description of records 'matched against the catalog: new, already in the catalog, or in conflict' together convey a dry-run of an import, but the text never states the verb 'preview' or that it is read-only inspection before importing. It reads as a description of return data rather than of the action, and does not distinguish itself from siblings like import_catalog or catalog_import_status.

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 explicit when-to-use or when-not-to-use guidance. The obvious alternative, import_catalog, is not named, and no condition is given for choosing this preview over that import or over catalog_import_status. The label-connection artist requirement is in the schema, not routed here.

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/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-derivable behavior: results are ordered 'best first' and, importantly, 'a missing number is not reported yet, never zero' – a data-semantics rule an agent could otherwise misread as a real zero. Scope is also constrained to the artist's own posts. Pagination/window mechanics are left to 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 primary output is front-loaded in the first sentence, which is good, but it is a dense, comma-piled run-on, and the second 'what_works' sentence is a chain of clauses that is hard to parse. Meaningful content, but not tight or 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?

There is no output schema, so the description has to carry the return-shape burden and largely does: it enumerates the per-post metrics, the window totals, the follower counts, and the what_works breakdown. Combined with 100% schema coverage on inputs, an agent has enough to call and interpret the result, with only ordering/pagination details 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 description coverage is 100%, so days, limit, and artist are fully documented in structured form and this is the baseline case. The description only loosely reinforces the artist scoping ('from their own posts only') without adding range, default, or format detail 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?

States a specific resource (the posts that went out) and the exact payload: reach, likes, comments, shares, saves, views, window totals, per-account followers, plus a per-platform what_works analysis. An agent knows what it returns. It never names or contrasts a sibling such as get_stats or promo_this_week, so the boundary is left to inference 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?

The description gives no when-to-use framing, no prerequisites, and no explicit alternative to choose instead. The only routing hint ('from their own posts only', label vs artist connection) lives in the schema's artist parameter, not in the description. An agent must infer that this is the historical-results counterpart to promo_this_week.

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 carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, closed-world), so the description only needs to add content-level context — and it does describe the returned subject matter (unscheduled items that will be missed, posts needing the artist). It adds no auth/permission or roster-scoping behavior, and the unexplained 'last_week' clause muddies rather than clarifies.

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 sprawling sentence with nested clauses, a mid-sentence colon introducing an unrelated subject, and no front-loaded summary of the return shape. The second half is disproportionate to its informational value and is the least coherent part.

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 read-only annotations, the description correctly assumes the burden of explaining what comes back, and the forward-looking portion does that acceptably. However, the trailing retrospective description is not backed by any parameter or option, so the agent cannot tell whether that data is always returned, conditionally returned, or unreachable.

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 both `days` and `artist` — but the description never mentions either, and instead names a `last_week` control that does not exist in the schema. That dangling reference actively misleads about how the call can be parameterized, dropping it below the baseline 3.

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

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

The first clause does identify a specific resource and scope: upcoming posts across every campaign plus the gaps not yet scheduled. But the second half pivots to a 'last_week:' block describing retrospective analytics, which reads like a leftover mode flag rather than part of this tool's purpose, leaving the agent unsure whether this is a forward-looking schedule view or a results digest.

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 promo_results, get_campaign, list_campaigns, or list_todos, even though several siblings overlap on campaign/post data. The only implicit cue is the 'next days' framing; nothing tells the agent when this tool is the wrong choice.

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 readOnlyHint=false present, the description adds real behavioral context beyond annotations: it clarifies that no profile write occurs, that the artist confirms and keeps the results in Audora, that Home is notified, and that the call returns a link. It does not address repeat/idempotent behavior (annotation says idempotentHint=false), which is a minor 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 primary action is front-loaded in the first sentence, and the remaining sentences carry genuine behavioral guidance (no profile write, don't route through update_profile). The final sentence about Home is slightly expository but still conveys the user-visible effect.

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

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

With no output schema, the description correctly states the return value (the link), describes the side effects, and explains the artist-facing flow. Combined with full schema coverage and annotations, an agent has what it needs to call this correctly, though idempotency remains unaddressed.

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 parameters (artist, run_id) are fully documented in the schema. The description's phrase 'finished find_online lookup' loosely reinforces run_id's meaning but adds no syntax or format detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific action (surface a finished find_online lookup in Audora) and the resource it operates on, and explicitly names the sibling tool find_online as its input source. An agent can distinguish this from update_profile and the other write tools without opening the schema.

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

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

It gives the prerequisite (a finished find_online lookup) and an explicit alternative to avoid: 'you should not copy the findings into update_profile yourself.' That is a concrete when-to-use plus a named when-not-to-use, 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false. The description adds what annotations cannot: the ask lands in a human-read support inbox, surfaces in the artist's Settings › Support, changes nothing in their catalog, and is the only path to a human. That is high-value behavioral disclosure beyond the structured fields.

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

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

Four short sentences, front-loaded with the trigger, then destination, then the crucial ordering instruction, then the no-side-effects reassurance. Every sentence earns its place; nothing redundant.

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

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

Completes a simple three-param, no-output-schema tool whose annotations already cover safety. All four facts an agent must know to invoke correctly – trigger, destination, ordering, side-effect profile – are present with no important omission.

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 each of the three parameters already has a description ('in their own words', 'the tool you tried or looked for'). The description doesn't add format or constraint details beyond the schema, which is the baseline case for full coverage.

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 (files the ask in Audora's support inbox) and its scope (no tool exists, or a tool refuses unrecoverably). The name 'report_gap' plus this description makes the tool's job unambiguous relative to siblings, none of which touch support inboxes.

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

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

Explicit when-to-use ('whenever the artist asks for something there is no tool for, or a tool refuses in a way you cannot work around') and an explicit when ('before you tell the artist no'). This is exactly the routing judgment an agent needs.

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 give only the safety profile (non-read-only, non-idempotent); the description adds real behavior beyond that: the address is one-time, finalize_upload independently reads and validates size/format/account storage, and the server measures the file on arrival. It does not describe address expiry or failure modes, so it falls short of full disclosure.

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 the follow-up workflow, then the constraint on asking for file size — four dense sentences with no filler. Each clause either routes the agent to the next call or prevents a specific failure.

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

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

For a 7-parameter, no-output-schema tool, the description covers the essential end-to-end flow and the key constraint. Gaps remain on the shape of the returned address object and on album_id/mime_type usage, which are undocumented in both description and schema.

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

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

With 57% schema coverage, the description usefully narrows the requirement set ('You need the file's NAME, nothing else') and reinforces that bytes is optional and must not be solicited. It adds little on artist, album_id, track_id or mime_type, but track-related params are already documented in 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?

States a specific verb and resource — requesting a one-time upload address — and enumerates the four artifact kinds, which matches the 'kind' enum exactly. It also distinguishes itself from finalize_upload by positioning the call as the first half of a two-step PUT-then-finalize flow.

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 clear workflow guidance: get the address, PUT the file to it, then call finalize_upload. It also sets an operating rule ('Never ask the artist how big a file is'). It stops short of explicit when-not-to-use exclusions, but the sequencing makes the trigger condition unambiguous.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description goes well beyond them: drafts are private to the artist and need only kind, posting publishes to Scene/public page, posted events stay posted so later edits must also post, and edits preserve previously chosen values. These are real behavioral traits 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?

Purpose and draft/post distinction are front-loaded, and nearly every sentence carries a distinct rule. The later sentences ('Inviting artists or Audora stays the artist's to do in Audora; an edit keeps what they chose') are dense and slightly awkward to parse, costing a point.

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 nested-object mutation with no output schema and no annotations on data lifecycle, the description covers draft privacy, publish requirements, posted-state immutability and connection scope. The one gap is what the call returns (e.g. an event_id for subsequent edits), which an agent needs to chain calls.

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 80%, so most parameters are already documented, but the description adds cross-parameter logic the schema does not: only 'kind' is required for a draft, while posting demands title, starts_at and a place (city+country and/or online link). It does not explain time_zone or ends_at interplay, which the schema handles.

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 set (save, change, post) over a specific resource (the artist's show, release party or listening party), and the event_id branching clarifies the create-vs-update duality. It is clearly distinguishable from siblings like list_events or cancel_event.

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

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

Explicit when-to-use and when-not: save as a draft by default, only set post: true when the artist actually asked for it to go out, and 'Artist connections only' (with the label path deferred to the artist param). It also rules out adjacent work ('Inviting artists... stays the artist's to do'), removing ambiguity about scope.

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 cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description goes well beyond them: it discloses the return shape (draft_hash, release_rules), that unfinished drafts still save, that too-soon release dates come back in `warnings`, and that submission will refuse the release until changed. Missing auth/connection prerequisites beyond what the schema states, but the mutation-behavior story is unusually well told.

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

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

Four sentences, front-loaded with the core action and the DRAFT qualifier before the return values and edge cases. Slightly prose-heavy ('goes nowhere until the artist says so', the parenthetical field list), but each sentence carries distinct information and nothing is pure 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 correctly carries the burden of describing returns (draft_hash, release_rules, warnings) and the draft/submit lifecycle. For a 4-param tool with a nested `release` object, that is close to sufficient; the only real gap is that it doesn't restate which connection/artist context is required, which the schema covers.

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 75%, so the baseline is 3; the description adds only loose context for the `release` object ('release details', referencing the fields stores require) and does not explain the get_requirements field names, the 'send only what you are setting' semantics, or the draft_hash linkage. It neither compensates substantially for the gap nor misleads.

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 — 'Write the release details for a track or album as a DRAFT' — so the agent immediately knows this persists release metadata rather than submitting it. It is distinguishable from update_track/update_album by the DRAFT framing, but it never explicitly contrasts itself with those siblings (or with check_readiness/get_requirements, whose output it partially overlaps), so differentiation is implied 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?

'A draft costs nothing, can be changed and goes nowhere until the artist says so' implies the workflow context (use this before submission to stage metadata), and it notes the draft saves even when unfinished. However, it never says when to choose this over update_track, update_album, or get_requirements, and gives no exclusion conditions. Usage is inferable but not prescribed.

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

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

Beyond the annotations the description discloses routing and audience: it lands in 'Audora's support inbox' and shows in 'the artist's Settings › Support', it is read by a person, and it should be written as prose ('what you were trying to do, what got in the way and what would have helped'). That is real operational context. There is a mild tension with openWorldHint=false/readOnlyHint=true given the submission is delivered somewhere, but nothing destructive or irreversible is claimed, so this is context-adding rather than contradictory.

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, then the kind taxonomy, then the writing guidance and the sibling routing — a sensible order with almost no filler. It is one dense paragraph of roughly ten sentences, so it is a little longer and less scannable than it could be, but each sentence carries information.

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

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

With no output schema, the description still tells the agent what happens after the call (support inbox, artist's Settings), who reads it, and the permission model. Enough to call the tool 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 100%, so the baseline is 3, but the description genuinely disambiguates the enum values — the schema only says 'What this is about' for kind, while the description differentiates missing_capability, connector_improvement, product_improvement, bug and other with concrete examples. It also reinforces artist_asked semantics already in 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 opening sentence gives a specific verb and resource ('Send Audora feedback it will read') and immediately enumerates the five kinds, so the agent knows exactly what is being created. It also names the sibling it is not: 'For a plain "there is no tool for that", report_gap is enough.'

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

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

Explicit trigger ('Use it when you notice something worth fixing'), an explicit exclusion that routes to the alternative sibling (report_gap), and a stated permission rule ('You do not need the artist's permission, but set artist_asked to true when the artist asked for it'). This is close to a full when/when-not/alternative specification.

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

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

Goes beyond the annotations by disclosing the overwrite behavior and, importantly, that omitted tracks are removed from the album rather than deleted — which usefully clarifies the destructiveHint=false annotation. It stops short of mentioning dry_run's effect or any auth/permission 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 short sentences, front-loaded with the core action, and the non-obvious removal semantics are stated upfront. Every sentence earns its place 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?

For a mutation tool with no output schema and no annotation coverage of side effects, the description supplies the key behavioral facts (full replacement, non-deletion). It omits any mention of dry_run (available in schema) and permission context, leaving minor 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 75% and already documents artist, dry_run, and 'In running order' for track_ids. The description restates the ordering semantics and implies album_id is the target album, but adds little the schema does not already carry, so 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+resource ('Put these tracks on this album') plus the defining scope ('in this order'), which matches the title's 'running order'. No sibling tool overlaps this operation, so no disambiguation is needed, and an agent can tell exactly what it does from the first sentence.

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

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

The phrase 'Replaces whatever was on it' implies the usage condition (use it to fully rewrite the album's order rather than append), but it never explicitly states when to use this vs. alternatives like update_album or when not to use it. No prerequisites or exclusions are given.

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

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

Annotations already cover the safety profile (read-only false, non-destructive, non-idempotent). The description adds genuine beyond-schema behavior: the eligibility window and the 'released elsewhere' refusal condition, which an agent cannot infer from annotations. Auth/return behavior is left to 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?

Two sentences, zero waste, with the effect front-loaded and the refusal constraint following. Every clause 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 write toggle with no output schema, the definition covers purpose, eligibility, and refusal conditions. It omits any mention of side effects (e.g. notifications to other artists) or confirmation of state change, but nothing blocks correct invocation.

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

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

Schema coverage is 75%, with artist, release_id, and idempotency_key documented but the required 'on' boolean left undescribed. The description compensates by defining what 'on' means (appearing on the first-listen list), adding real 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?

States a specific verb ('switch ... on or off') and resource ('the list other artists on Audora see on release day'), with a concrete effect ('give it a first listen'). This is distinguishable from siblings like list_releases or promo_this_week without opening a schema.

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

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

Explicitly states when the tool will be refused ('a release out more than four weeks ago or released elsewhere'), which is strong when-not guidance. It does not, however, name an alternative tool or spell out the positive 'use this when' scenario beyond the toggle's effect.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description does add one behavioral fact beyond that — the action is reversible ('or not done again'), i.e. it can be un-ticked — but says nothing about permissions, label-vs-artist connection requirements, or what the response confirms.

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 front-loaded sentence that identifies the action immediately and wastes no words. The trailing 'the tick in Audora' is slightly vague phrasing but does not undermine the concision.

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 two-state mutation with no output schema, the definition is minimally adequate: the schema carries the parameter and connection details, and the description confirms reversibility. It is missing the distinction from close_todo and any confirmation of state return, which leaves a real gap for an agent choosing among the todo-mutating siblings.

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 75%, so the schema already explains todo_id, artist (label connection rule), and idempotency_key. The description adds no parameter meaning beyond that and does not itself explain the done toggle's semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('mark one checklist item done, or not done again') and clarifies it is a toggle in both directions. However, it never distinguishes itself from the sibling close_todo or explains how ticking relates to closing, so an agent can't route between them from the description alone.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as close_todo or list_release_todos. Usage is only implied by the verb 'mark done'.

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?

Adds rich behavior beyond the annotations: the call is refused and nothing is written unless rights_confirmed is sent, the account artist can never be removed, an empty list clears billing, and dry_run previews without writing. The legal-confirmation recording is a significant disclosure the annotations cannot express.

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

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

Front-loaded with the core action, and nearly every sentence carries a distinct rule (ordering, refusal, clearing, sibling routing). It is dense rather than padded, though the single long paragraph could be broken up for faster scanning.

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 mutation tool with no output schema, the description supplies the prerequisites, refusal conditions, idempotent-clearing behavior, and the alternative tool. 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 coverage is 80%, so the baseline would be 3, but the description adds real meaning: it explains what each role value does to the credit line (primary/with join the main credit, featured/remixer become the feat. part) and the exact semantics of rights_confirmed. Only dry_run and the label-only artist param are not elaborated in prose.

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 (Replace) and resource (the OTHER artists a track is billed to), and illustrates the exact output line on every store. It explicitly distinguishes itself from set_track_credits, the sibling that handles songwriter/performer/producer credits.

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

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

Explicit when-to-use, when-not (do not send the account's own artist, which is always billed first), ordering requirement, and named alternative (set_track_credits). It also routes the rights_confirmed workflow with a precise confirmation rule, so the agent knows both the preconditions and the fallback.

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

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

The description is rich on behavior: it discloses that the list replaces ALL existing credits, that missing performer instruments produce saved-but-warned state, and that optional credit kinds never count toward the three required. But that replace-everything semantics conflicts with destructiveHint=false (and idempotentHint=false for what is a set-to-value operation), so the structured hints mislead an agent that skips the prose.

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 the mutation semantics, then the validation constraint, then the anti-hallucination rule. Nothing is repeated from the schema and every sentence changes how the agent would call the tool.

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

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

For a mutation tool with no output schema, the description covers the essentials an agent needs: replacement semantics, hard validation rules, warning behavior, and the domain constraint that credits are real people. It could go one step further by clarifying ordering/idempotency or how it relates to set_track_artists.

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

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

Schema coverage is already 75% and the properties are heavily documented, so the schema carries most of the load. The description still adds real meaning beyond it: the one-of-each-role rule, the pointer to get_requirements for performer_roles/optional_credits vocabularies, and the consequence of omitting an instrument (warning, not rejection).

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: 'Replace a track's song credits with this list.' The replace semantics are unambiguous. It does not, however, distinguish itself from the adjacent sibling set_track_artists (or update_track), so an agent must infer that 'credits' (songwriter/performer/producer) is a different concept from 'artists'.

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 condition — the three required roles must exist 'before its release can be submitted' — plus an operational rule ('ask the artist, and never invent a name'). It lacks any exclusion or named alternative, so the boundary with set_track_artists and update_track remains implicit.

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

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

Goes well beyond the annotations (which only say readOnly=false, destructive=false, idempotent=false): it discloses that the post stays attached to the campaign, that the change is reversible via keep_post, that scheduled posts are dequeued with the posting credit returned, and that the schedule permission is required. That is exactly the kind of state/auth context annotations cannot carry.

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

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

Three short sentences, each earning its place: effect, reversibility plus sibling, then the scheduled-post and permission caveat. Front-loaded with the primary effect.

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

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

No output schema exists, but the description covers the mutation's semantics, reversibility, credit handling, and required permission. Together with annotations and the fully documented schema, an agent has everything needed to invoke 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 post_id, artist, and idempotency_key are already fully documented in the schema; the description adds no parameter-level syntax or format detail. Baseline 3 applies since the schema does the heavy lifting.

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

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

Specific verb+resource ('Skip a post so it does not go out') with the precise effect stated, and it explicitly distinguishes itself from the sibling keep_post, which undoes it. An agent can tell skip_post from update_post/keep_post 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 names the alternative (keep_post brings it back) and the condition that makes skipping consequential (a post already scheduled is pulled from the queue). It stops short of stating explicit when-not-to-use cases, e.g. whether this applies to drafts vs scheduled posts only.

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 say it is a non-destructive, non-idempotent write; the description adds substantial context beyond that: credits are charged when it starts and returned if the plan fails, the artist's spend permission is required, campaigns that duplicate a live campaign in language/lead market/accounts are refused, and posts are fit around existing scheduled posts (one video and one picture a day per account). It never states what the successful (non-dry-run) response contains, which keeps it off 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?

The purpose is front-loaded, but the body is a dense stream of parenthetical asides that pack several unrelated rules per sentence ('...the dry run's quote.plan says it), charged when it starts and returned if the plan fails; starting it needs the artist's spend permission'). Rules about between-releases months appear in the first sentence and are restated later, and the dry-run-first instruction — the most actionable line — is buried at the very end.

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 24-parameter mutation tool with no output schema, the description covers most of what an agent needs: cost model, refunds, permission gating, duplicate refusal, scheduling interplay, credit pricing per moment, and dry-run quote semantics. The remaining gap is the shape of the live response (campaign id, resulting schedule), which is never 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 coverage is 100%, so the baseline is 3; the description adds meaning on top by explaining that the answer fields (the_story, key_lyrics, key_moments, what_works, sonic_references, note) are the Start panel's, are optional, are filled from what Audora knows when omitted, and 'turn on posts that use them.' It also points at dry-run quote fields (quote.plan, quote.duplicate_of, quote.markets, quote.post_language) that explain defaults.

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

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

The opening sentence names a specific verb and resource ('Start a campaign') and immediately splits the two modes (an upcoming release, or a month between releases). It also carves out the exclusion case ('a release already out gets no campaign of its own'), so an agent can distinguish this from siblings like update_post, make_posts and list_campaigns.

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 spells out the operating sequence explicitly: 'Use dry_run first to see the posts, the price and those answers, tell the artist, then start with confirm_cost_credits.' It also names when to reach for alternatives — 'Nothing is made: fill each post from the artist's Library with update_post, or have Audora make one with make_posts' — and when to use replace_plan_id.

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

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

Annotations already establish the safety profile (readOnly=false, destructive=false, idempotent=false) plus the schema's dry_run field documents preview behavior. On top of that the description discloses a real behavioral gate — the call is refused after release submission. It stops short of saying whether unlisted fields are preserved or cleared, which is the key mutation risk here.

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

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

Two short sentences with zero filler, purpose first and the refusal condition second. Nothing to trim and nothing 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 mutation tool with no output schema and a free-form nested 'fields' object, the definition covers the critical refusal precondition and the schema covers the dry_run workflow. It does not, however, clarify what happens to existing values not named in fields, which is the main thing an agent needs before an overwrite.

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 75% and the schema itself explains artist, the fields map, and dry_run richly; only album_id is undocumented. The description adds nothing about parameters, so per the coverage rule the baseline of 3 applies — the schema carries the weight rather than the prose.

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 ('Amend an album's details'), which cleanly separates it from create_album and update_track. However, it never contrasts itself with near-siblings like set_album_tracks or save_release_draft, so the agent must infer the boundary between amending metadata and other album mutation 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?

The sentence 'Refused once its release has been submitted' gives a genuine precondition telling the agent when the call will fail, which is more than most definitions offer. But it never names an alternative for that blocked case (e.g., a draft or release-edit tool) or states prerequisites for locating an album_id, leaving the routing decision half-specified.

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 cover the boolean safety profile; the description goes much further by disclosing the permission gate for scheduled posts, the hard boundary for posts already pushed to Facebook/YouTube or published, the partial-update contract, and the return payload (the post plus schedule_check). Nothing here contradicts readOnlyHint=false or destructiveHint=false.

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, each with a distinct job: what can change, how to send it, and what comes back plus the constraints. Front-loaded with the mutable field list. Slightly dense in the first sentence but 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?

No output schema exists, so the description must describe the return value, and it does ('the post with schedule_check: what Schedule would decide now'). Combined with permission requirements and the cases where the call is rejected, an agent has everything needed to invoke this correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters, including the enum values for angle and the Library constraint on media_asset_id. The description's field list largely restates what the schema covers; 'Send only what changes' is the one genuine semantic addition. 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?

Names a specific verb (Change) and resource (a post), then enumerates exactly which fields are mutable (words, hashtags, link, day, time, picture/video, angle). An agent can immediately distinguish this from add_post, keep_post, and skip_post 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?

Gives explicit partial-update guidance ('Send only what changes') and clear when-not conditions: a post already handed to its platform's own schedule or already published cannot be changed here, and a scheduled post needs the schedule permission. It does not name a sibling alternative for the excluded cases, so it falls just short of the top band.

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 declare the mutation profile (readOnly false, destructive false). The description adds real behavior beyond that: partial updates, a hard prerequisite on get_requirements, and the failure mode where over-long values are refused with the offending length. It doesn't state success/return behavior, but that is a modest 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?

Three tight sentences, front-loaded with scope, then the update rule, then the prerequisite and validation behavior. The field list is dense but every clause carries actionable information.

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

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

For a mutation tool with full schema coverage and annotations present, the description covers scope, partial-write semantics, prerequisite, and validation failure. Nothing critical is missing, though it could note that writes replace existing artist-authored text (which dry_run hints at in the schema).

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

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

Schema coverage is 100%, so all three parameters (artist, fields, dry_run) are already documented in the schema, including the label-connection rule for artist and the dry-run warning. The description's field enumeration and partial-update note add little beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Set) and resource (artist details) and enumerates the writable fields, so an agent can tell it apart from get_profile and propose_profile. It stops short of explicitly naming the sibling it replaces, but the mutation scope is unambiguous.

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

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

"Send only the fields you are changing" gives clear partial-update guidance and "Call get_requirements first for the exact limits" establishes a prerequisite. There is no explicit when-not or alternative routing (e.g. propose_profile), which keeps it out of 5 territory.

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 non-read-only, non-destructive, non-idempotent, non-open-world. The description adds genuinely new behavior: a hard refusal after release submission, the frozen-copy rationale, and the fact that underlying catalog changes cost credits and are the artist's decision.

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, purpose front-loaded, zero filler. The second sentence is dense and slightly tangled ('changing the catalog underneath it is the artist's own decision, because it costs credits'), but still earns its place by conveying the refusal rule.

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

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

No output schema, but annotations cover the safety profile and the description covers the critical mutation constraint (frozen after submission) plus credit implications. A mutation tool with this much behavioral context is adequately specified, though the alternative once frozen is unstated.

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 schema itself richly documents artist, fields (pointing at get_requirements), and dry_run. The description adds no parameter-level detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Amend a track's metadata') that clearly separates it from update_album, update_post, and update_profile. It does not, however, explicitly contrast itself with sibling update tools or create_track.

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 a concrete precondition and exclusion: the call is refused once the release has been submitted because a frozen copy exists. It does not name an alternative path (e.g. what to do once frozen), leaving that 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 this readOnly, idempotent, and closed-world, so the safety profile is covered. The description goes beyond them by disclosing the return content (account identity, allowed actions, review location, next_steps) and the connection-type behavior — a meaningful addition not present in structured fields.

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

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

Three sentences, well front-loaded — return semantics first, then the 'call this first' directive, then the parameter condition. The opening sentence packs several clauses but each carries distinct information, so the length is earned.

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 only one optional parameter, the description carries the full burden of explaining return values, and it does so explicitly (account, permissions, review location, next_steps). Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%: the `artist` parameter is already fully documented with its label-only condition and fallback to list_roster. The description restates the label-connection case, adding context but no syntax or format detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a precise verb and resource — it returns the account the connection acts in — and enumerates exactly what comes back (permissions, review location, next_steps). The artist-vs-label distinction makes it clearly distinguishable from catalog siblings like get_profile or list_roster.

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

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

It gives explicit when-to-use guidance: 'Call this first, and again whenever you are unsure whose catalog you are working in.' It also names the conditional path (pass `artist` on a label connection) and points to list_roster as the source of that value, routing the agent without ambiguity.

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