Yaybird

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

Annotations only declare the generic safety profile (not read-only, not idempotent, not destructive, open world). The description goes well beyond that: public-https-only, 100 MB cap, accepted formats, single-use upload URLs that expire in an hour, and aspect inference from images. These are exactly the constraints an agent needs to avoid failed uploads.

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 the core purpose, then walks the three modes in a logical order with no filler sentences. It is a dense single paragraph rather than a structured list, but every sentence carries information the agent needs.

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

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

An output schema exists, so return values need no explanation, and the description still covers the non-obvious case where the response contains upload_url/upload_page_url. For a nine-parameter tool with a nested object, an enum, and a write hazard, everything required to call it correctly is present.

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

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

Schema coverage is 89%, so the schema already documents most parameters and the baseline is 3. The description adds real meaning on top: the url vs file vs neither decision, that file is populated by ChatGPT, and that aspect is auto-derived when omitted — semantics absent from the schema's enum.

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 (adds an image or video to a brand) and immediately distinguishes itself from read-side siblings like get_media and list_media by describing the three input modes. An agent knows exactly what the tool does without opening the schema.

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

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

Explicitly explains when to pass url, when to pass file (ChatGPT-attached), and when to pass neither (get an upload link), plus routes the agent to get_media to poll for readiness. It does not explicitly name a sibling alternative for the same task, but the mode-selection guidance is concrete and actionable.

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 reveals that the rule applies immediately because it only makes checks stricter, and that workspace members will see the addition. This is important behavioral context not captured by annotations (which only indicate non-read-only, non-destructive, non-idempotent).

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

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

The description is a single sentence packed with essential information, no wasted words, and front-loads the core action and constraints.

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

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

Given the rich schema and annotations, the description covers the key behavioral aspects (immediate application, visibility) and constraints (mutual exclusivity). It doesn't mention output, but an output schema exists, so that's fine. It could mention side effects like skip-existing-rules for packs but that's in 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?

The schema has 100% description coverage for all parameters and their nested fields. The description adds some meaning by clarifying that rule and pack are mutually exclusive and that toggles are a type of rule, but otherwise adds little beyond the schema's own descriptions.

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

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

The description clearly names the verb 'adds' and the resource 'rule' to a brand or starter pack, and distinguishes toggle rules from other kinds. The sibling set includes remove_rule and update_rule, but the description doesn't explicitly differentiate from them, leaving some ambiguity.

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

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

It provides a clear rule: 'Pass rule or pack, not both' and notes that toggles are for house style switches. However, it doesn't state when to use add_rule versus update_rule or remove_rule, though these are fairly self-evident.

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, yet the description adds real behavioral context on top: a 'zernio' source queried 'at most once an hour' with a computed_at timestamp, a 'history' fallback limited to 90 days, a min_posts threshold before 'enough' is false, and the crucial caveat that this is advisory and 'does not change the posting times next_slot uses.' That is substantive transparency 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?

It is front-loaded with the core purpose, but a large share of the text enumerates return fields ('slots of {day, hour, minute, local_label, posts, avg_engagement}' and the whole grid cell shape) that an output schema already carries. The run-on density and redundant payload description dilute an otherwise informative opening.

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

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

For a zero-required-parameter read tool with annotations covering the safety profile and an output schema covering the return shape, the description supplies more than enough to call it correctly, including source/caching and advisory semantics. Its only real gap is the undocumented platform parameter.

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

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

Schema description coverage is 50% (brand is documented, platform is an undescribed enum). The description adds no meaning about what brand or platform do, how omission of brand is resolved, or how platform scopes the analysis, so it fails to compensate for the coverage gap.

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 identifies the resource: 'When this brand's posts get the most engagement, by weekday and hour in the workspace's time zone.' That is a specific, unambiguous statement of what the tool returns. It does not, however, explicitly differentiate itself from analytics siblings like get_analytics or open_week.

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 downstream usage: 'a best time can go in scheduled_at, or the person can add it to the posting times in Settings,' and notes a free-form caveat about weak signals when 'Few posts behind a slot.' It stops short of naming an alternative tool for when this is the wrong choice, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description goes further by disclosing partial-destruction semantics (already-live targets stay live and must be removed by hand), irreversibility ('cannot be undone'), and the recovery path (a new post can take its place). This is exactly the extra context an agent needs before a destructive 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?

Three short sentences, front-loaded with the primary effect, then the exception, then the irreversibility warning. Every sentence carries information and nothing is padded.

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

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

An output schema exists, so return values need no explanation. For a single-parameter destructive mutation the description covers effects, partial effects, reversibility, and follow-up, leaving nothing material for the agent to guess.

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?

There is one parameter, post_id, and schema description coverage is 0% – the schema supplies only a string type with no explanation. The description never mentions post_id, what identifier format is expected, or where to get it, so it does not compensate for the coverage gap. The name is inferable, but that is not documented guidance.

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 (cancels) and resource (a post) plus the precise effect: none of the remaining targets will publish. That scope clause separates it from retry_post, update_post, and mark_posted semantically, though no sibling is named explicitly.

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

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

The consequences imply when this tool applies (stop a post that has not yet gone out), but there is no explicit 'use this when / do not use this when' and no comparison against alternatives such as retry_post or update_post. Usage must be inferred from the effect described.

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 and idempotentHint=true, so the safety profile is covered, yet the description adds substantial behavioral detail beyond them: nothing is saved, the exact error shape { platform, field, message, fix }, the rendered_caption output, and constraints such as X's monthly link cap and Google's removal of posts containing phone numbers.

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 and return-shape are front-loaded, which is good, but the second half is a dense reference dump of per-platform character counts and link rules that largely duplicates material that lives in brand rules and platform docs. Much of it is useful, but the wall-of-text format makes it harder to scan than it needs to be.

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

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

For a validation tool over a deeply nested target schema, the description covers what an agent needs: the dry-run semantics, the success signal (ok: true), the error contract, caption rendering, and the platform-specific constraints that determine pass/fail. An output schema exists, so return values need no further explanation.

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 meaningfully enriches the schema: it explains {link} substitution with UTM tags, which platforms may or must contain {link}, per-platform hashtag and mention limits, and that Google's link belongs on the button rather than in text. These are semantic rules the schema does not state.

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 states a specific verb and resource — 'a dry run of create_post' — and immediately distinguishes itself from the sibling create_post by declaring that it saves nothing. An agent knows exactly what this tool is for 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?

'A dry run of create_post' plus 'ok: true means create_post will accept it' makes the use context clear: validate before creating. It does not, however, explicitly say when not to use it or name a true alternative, so it stops short of the top score.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description is consistent with them while adding real behavioral context: the tool only produces a URL, and the actual platform sign-in must be performed by the user. The parenthetical that the link "starts the platform sign-in straight away where it can" signals platform-dependent behavior not captured by any structured field.

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 purpose before the mechanics and return contents. The clause "it starts the platform sign-in straight away where it can" is slightly tangled but carries non-trivial information, so little 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 two-parameter hand-off tool with an output schema and full annotations, the description covers who can execute it, what it produces, and the flow step. The one real gap is input-side: nothing here helps an agent pick the correct platform or decide when to supply brand.

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 only 50% schema description coverage, the description needs to compensate, but it never explains the platform enum options or the brand parameter. Its only mention of a platform is in the context of returned data, not the input, so it adds no meaning beyond the schema.

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

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

The description states a specific outcome — producing a link that lets the person connect a social account to a brand — and is clearly distinct in intent from post/media tools. It doesn't need to differentiate from a sibling since none of the listed siblings do account connection, but it also does not explicitly position itself against any 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?

"Connecting needs them to sign in to the platform, so only they can do it" is a clear usage constraint that tells the agent this is a human hand-off rather than an operation the agent completes itself. It gives no named alternatives, but there is no competing tool to route to.

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 annotations: approval flow (needs approval, auto-approve brands, approval_url), idempotency_key preventing duplicates, per-platform caption rules, and the X monthly link-post cap. Return shape (allowed_actions, preview_url, approval_url) is also disclosed even though an output schema exists.

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

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

Dense but front-loaded; it is long and buries high-value facts (idempotency, approval flow) inside a wall of per-platform constraints that partly duplicate schema descriptions. Acceptable for a tool this complex, but not tight.

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 high-complexity multi-platform publishing tool, the description covers approval lifecycle, scheduling semantics, failure behavior, idempotency, and per-platform limits – everything an agent needs to call it correctly.

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

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

Schema coverage is 100%, yet the description still adds cross-cutting meaning: scheduled_at offset semantics and the next_slot scheduling algorithm, per-platform media/character/link rules tied to targets, and {link} substitution.

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

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

Opens with a specific verb+resource and scope ('Saves a post across platforms, one target each with its own caption and media'), and names the sibling check_post it complements rather than duplicates.

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

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

Explicitly routes to check_post for dry-run validation, to submit:false/request_approval for drafts, and to get_workspace/get_brand for the required posting times and rules. The alternative paths are stated with their conditions.

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

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

Annotations declare destructiveHint, idempotentHint=false, readOnlyHint=false, but the description adds the critical semantics: the draft is held for human approval, re-calling replaces the draft and withdraws approval (explaining the non-idempotent/destructive flags), and the exact refusal conditions. This is rich, non-redundant behavioral context.

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

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

Front-loaded with the core action, and every sentence substantially earns its place (approval flow, replacement behavior, refusals, spam guidance). Dense but justified; a slight run-on in the refusal clause keeps it from a clean 5.

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

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

An output schema exists, so return values need no explanation. Combined with the approval workflow, refusal conditions, and sibling references, an agent has everything needed to invoke it correctly and predict the outcome.

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

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

Schema coverage is 0%, so the description must compensate, and it does partially: comment_id is sourced from list_comments, and text is bounded by brand rules (get_brand) and platform length. It adds real meaning for both params, though it doesn't spell out the exact format/content expectations of the reply text.

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 ('Drafts') and resource ('the reply to one comment'), with a clear scope that distinguishes it from siblings like create_post or add_media. The parenthetical routes the agent to list_comments for the comment_id, removing ambiguity about the target.

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

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

Explicitly names when the tool applies (replying to a comment), what it does not do ('never sends'), and lays out refusal conditions (person already wrote the reply, already sent, breaks brand rules or length). It also references siblings list_comments and get_brand and gives guidance for spam/abusive cases.

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 and destructiveHint=false; the description goes further by framing the operation as a 'copy' (original not mutated) and explaining the downstream effect that the returned media_id replaces the original in media_ids for create_post/update_post. It stops short of stating whether the original asset is retained or how the edge colour is chosen.

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?

Every sentence carries information (dimensions, rationale, when-not rule, return contract), but the opening is a dense run-on fragment with parenthetical piled on parenthetical rather than cleanly front-loaded statements.

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

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

An output schema exists, yet the description still briefly states the return contract (new media_id and url) and its ripple effect on media_ids, closing the loop for an agent chaining this into create_post/update_post. Nothing needed to call 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?

Only one parameter with 100% schema description coverage, so the schema already carries the semantics ('The slide (an image media_id)'). The description adds the useful constraint that the input is an image slide needing fit, but no format or naming detail beyond that. 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 (fit) and resource (slide) and defines the transformation concretely: 1080x1920, scaled to sit below TikTok's top 14%, centred, on its own edge colour. It is unmistakable against siblings like make_cover or suggest_cover.

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 conditions keyed to a sibling's output ('fixes what check_post reports as a slide's text under the tabs, or a slide that is not 9:16') and an explicit when-NOT: text between 14% and 65% of height needs no fitting.

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 safety, but the description adds extensive behavioral context: data freshness cadence, reasons `engagement.available` can be false, when `vs_previous` is null, and cautions about interpreting insights as causes. This is exactly the kind of limitation disclosure an agent needs and goes well beyond the structured 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?

The definition is a single extremely dense paragraph that enumerates nearly every return field in detail, despite the presence of an output schema. It is front-loaded with the core purpose, but the bulk is verbose and would be better placed in the output schema.

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

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

For a complex analytics tool, the description covers scope, optional filters, return semantics, and important edge cases. It omits explicit routing guidance against sibling tools, but with an output schema present, the extra return-value detail is more than sufficient for 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 description coverage is 50%. The description adds useful meaning for `days` (default 7, up to 90), `since` (still accepted instead of days), and `platform` (optional single platform), but it does not clarify the `brand` parameter. Baseline 3 is appropriate given the partial 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?

The opening phrase 'How a brand's posts did over the last `days`' clearly identifies the resource and scope. It does not explicitly distinguish this tool from sibling analytics tools like `best_times`, even though it nests similar output fields, so it falls 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?

The description gives parameter conditions (default 7 days, up to 90, optional platform, `since` accepted). It does not say when to choose this tool over alternatives such as `best_times` or `list_posts`, so usage 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuine domain semantics beyond them: which content check_post enforces, that pending_rule_changes await a person, and the precedence of rules over playbook advice. It does not describe error behavior when a brand id is invalid, but the interpretive context is substantive.

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?

Every clause carries information with no filler, and the highest-value content (rules, then pending changes, then per-platform data) is front-loaded. But it is delivered as one sprawling run-on sentence with heavy parenthetical nesting, which is hard to parse and largely duplicates what the output schema already enumerates.

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?

Because an output schema exists, the description need not enumerate return fields, yet it supplies the interpretive layer the schema cannot: the rules-vs-guidelines distinction, machine-check status, and rule precedence over playbook advice. It omits when-to-call guidance and failure behavior, which are the remaining 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 description coverage is 100% and there is a single optional parameter, so the schema fully documents that brand is an id from get_workspace and is optional for single-brand workspaces. The description adds nothing about the parameter, 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 makes clear this returns a brand's configuration: rules (with their fields), guidelines, pending rule changes, auto-approval state, and per-platform account/reach data. The verb 'get/retrieve' is implied rather than stated, and it never explicitly contrasts with get_workspace, but the resource and scope are 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?

Usage is implied (call it to inspect a brand's rules, guidelines, accounts and playbook) and it embeds useful interpretive guidance — rules are machine-checked by check_post while guidelines are not, and brand rules take precedence over the playbook. However, it never states when to use this versus get_workspace or how the optional brand parameter should be supplied.

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 one genuinely useful behavioral detail — a media item can be in a 'waiting for upload' state, meaning a fetched item may not yet be usable — but says nothing about missing-id/error behavior or authorization 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 tight clause with no filler, front-loading the key fact ('One media item'). It is a fragment rather than a sentence, but nothing is wasted.

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

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

For a one-parameter read tool with an output schema, the definition is borderline adequate: it need not explain return values, yet most of its text does exactly that while leaving the required media_id and not-found behavior 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 0% and the sole parameter media_id is undocumented in both schema and description. The description annotates the return object instead of telling the agent what media_id is or where to obtain it, so it fails to compensate for the coverage gap.

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 says it returns a single media item and enumerates the fields returned (status, kind, aspect, url, size, provenance), which separates it from the sibling list_media. However, it never states the verb 'retrieve by id', reading more like a return-field inventory than a purpose 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?

No when-to-use guidance, no prerequisites, and no mention of the obvious alternative list_media (or add_media) despite their presence in the sibling set. The agent must infer that this is the single-item lookup counterpart.

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). The description adds real behavioral context beyond that: 'allowed_actions' tells the agent what mutations are currently permissible, 'permalink once live' signals field availability is state-dependent, engagement numbers are 'null where the platform gives none', and suggested_times appear only for overdue/near-due approvals.

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 enormous run-on sentence with multiple nested parentheticals and semicolon-chained clauses, much of it enumerating return fields the output schema already defines. The key routing fact (use show_posts to render) is buried mid-paragraph rather than front-loaded.

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 single-resource getter with an output schema and full annotation coverage, the description is more than sufficient — it even over-delivers on return-field detail. The only real omission is how post_id is obtained and an explicit statement of when an agent should reach for this 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?

Only one parameter (post_id) with 0% schema description coverage, so the description carries the explanatory burden — but it never says what a post_id is or where to obtain one. The parameter's meaning is inferable only from the tool name and the 'with its post_id' aside. Adequate but with a clear gap.

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 opens by scoping the resource precisely ('One post: its targets..., its approval..., allowed_actions; and history') and explicitly disambiguates from show_posts ('It draws nothing; show_posts with its post_id draws it for the person'). An agent can distinguish this retrieval tool from its draw-oriented sibling without opening either schema.

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

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

It names the alternative explicitly and the condition that selects it: use show_posts when you want the post rendered for the person, use get_post when you only need the data. It stops short of stating the positive trigger ('call this to inspect a single post's state'), leaving the when-to-use for this tool 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, destructiveHint=false and openWorldHint=false, so the agent knows this is a safe, side-effect-free read. The description adds semantic context for fields (auto_approve meaning for what you send, needs_reconnect, access = can create drafts), which is useful but not a behavioral trait beyond the data itself.

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 whole body is one roughly 250-word run-on sentence with no paragraphing or list structure, which is hard to scan. It is front-loaded with the resource name, but the remainder is a dense catalog of field definitions that is disproportionately long for a no-argument read tool whose output schema already exists.

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

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

An output schema exists, so return values need not be explained, yet the description goes further by clarifying field semantics and pointing to the sibling tools that consume two of the returned fields. That covers an agent's needs for invocation; only the awkward single-sentence packaging and missing when-not-to-use note keep it from a 5.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify about inputs.

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 makes clear this returns the full workspace/'this connection' record and enumerates its contents, so an agent knows exactly what resource it gets. It implicitly separates itself from get_brand by presenting brands as a nested field rather than the top-level resource, though it never states that distinction 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?

It gives real routing guidance: 'It is the starting context for the other tools: they plan in this time zone,' and it names the specific follow-up tools for two fields (changes_requested -> get_post/update_post; unanswered_comments -> list_comments/draft_reply). There is no explicit 'do not use this for X' exclusion, which keeps it below 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?

Beyond the readOnly/idempotent/non-destructive annotations it discloses the sort order, the precise rule for when a comment stops waiting, the can_reply states (yes, limited with reply_note, or no), and unanswered_total semantics. The warning that text and author are public, untrusted data rather than instructions is a genuinely valuable safety disclosure the annotations do not cover.

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 resource is front-loaded, but the body is a run-on paragraph packing return-field minutiae (comment_id, platform, the post, the author, the reply text/approval/sent status) that overlaps heavily with the existing output schema. Several clauses do earn their place, but the whole could be trimmed substantially.

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

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

Given an output schema and full safety annotations, the description still supplies the ordering guarantees, the waiting-state rule, filtering semantics, and the untrusted-data warning. Nothing essential for calling this read tool 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 only 50%, and the description compensates by explaining the otherwise-undocumented parameters: unanswered_only lists only waiting comments, since filters on when the comment was made, and comment_id or post_id narrow to one. brand and limit are left to the schema, which already documents them well.

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 (listing comments left on this workspace's published posts) and pins the scope to the platforms Yaybird reads. The ordering rule (waiting-for-reply first, then newest first) further distinguishes it from other list tools, and it names draft_reply as the sibling that handles the writing side.

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

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

It clearly frames the workflow context: unanswered_only lists only waiting comments, draft_reply drafts an answer to one, and a person approves each reply, so the agent understands this is the read side. It does not, however, give an explicit when-to-use statement or exclusions against other listing siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: captions arrive ready to paste with {link} filled in, media come in posting order, and the due time is included — so the agent knows what the payload looks like and that this is a hand-off-to-a-human list.

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 with no filler; the scoping statement leads and the sibling reference and parameter note follow. Slightly compressed in places but every 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?

An output schema exists so return values need not be fully spelled out, yet the description still conveys the key payload features (caption, media order, due time). Combined with the until explanation and the mark_posted hand-off, an agent has enough to call and use 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 50%: brand is documented in the schema, while until is undocumented there. The description compensates by explaining until as an ISO time that also surfaces tasks coming due before then, closing the gap. brand is left to the schema, which is acceptable since it is described there.

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

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

States a specific resource and scope: approved manual targets that are due now or overdue and need platform action. It defines what a 'manual task' is (a person must post by hand), which distinguishes it from the automated posting siblings. It does not explicitly contrast with other list tools (list_posts, show_posts), but the 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?

The 'due now or overdue' and 'need action on the platform' framing makes the trigger condition clear, and it names mark_posted as the follow-up once the person has posted. No explicit when-not guidance, but the context is sufficient to select the tool correctly.

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 behavior they cannot express: result ordering (newest first), pagination defaults (20 per page, next_cursor for more), and content exclusions. It does not mention auth or rate limits, but those are low-value here.

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

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

Three tightly packed sentences ordered as identity → pay-off/relations → exclusions and paging. No filler; even the parenthetical '(source_note)' earns its place as a field mapping.

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 an output schema present, enumerating return fields is somewhat redundant, but the description still supplies the ordering, pagination, and cross-tool linkage an agent needs to chain into create_post. The remaining gap is that it doesn't confirm kind/aspect act as optional filters.

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

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

Schema coverage is 60%: brand, limit, and cursor are documented in the schema, while kind and aspect are bare enums. The description names kind and aspect but as returned fields, not as filter parameters, so it does not clarify that they constrain the listing. Marginal added value over 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?

States a specific resource (a brand's uploaded media), its ordering (newest first), and the exact fields returned. It distinguishes itself from siblings by name: get/add_media imply single-item or insert operations, and it explicitly demarcates suggest_cover as the tool for video cover frames.

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 downstream context ('These media_id values are what create_post takes') and one explicit exclusion that routes the agent elsewhere ('Candidate cover frames are left out; suggest_cover lists a video's'). It stops short of a full when/when-not framework — it never contrasts itself with get_media or list_posts directly — but the routing guidance is concrete.

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), and the description layers on real behavior the annotations can't express: the overdue/due_soon approval logic, that such posts carry suggested_times, and pagination (20 default, 100 max, next_cursor). That is substantial context beyond 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?

Front-loads the core purpose and the show_posts routing, and nearly every sentence carries semantics absent from the schema (enums are undocumented otherwise). However it reads as a dense wall of text with the status list and timezone detail packed in, which costs some scannability.

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

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

Given an output schema exists, the description needn't explain return shapes, yet it still surfaces the fields an agent must reason about (targets, approval state, allowed_actions, overdue flags, suggested_times). For a filtered, paged list tool this leaves nothing material 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?

At 57% schema coverage the description compensates heavily: it gives ISO 8601-with-offset syntax for from/to and the timezone fallback rule, explains that from/to filter on post time while targets carry their own local_time, and enumerates all ten status values with their semantics. Only 'brand' goes unmentioned, which the schema covers.

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 with scope: 'posts in time order with their targets, approval state and allowed_actions'. It explicitly routes away from the closest sibling ('It draws nothing; show_posts returns the same data drawn as an approval list'), so an agent can distinguish list_posts from show_posts and get_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?

Names the alternative (show_posts) and the axis of selection (data vs drawn list), then gives concrete use cases: 'finding free times, avoiding doubled posts, or finding a post to change'. When to reach for this tool 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 declare this is a non-read, non-destructive, non-idempotent write. The description reinforces that by saying the result is 'saved as a new image' and returns a fresh media_id/url, implying each call produces a new artifact rather than updating in place. It adds platform-specific behavior (which networks honor an image cover vs a frame time, long-video-only on YouTube) that annotations cannot convey, though it omits auth or rate-limit notes.

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 produces, then the workflow links, then platform rules. Information-dense with almost no waste, though the long trailing platform enumeration is bulky and could be trimmed for agents that only need to 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?

An output schema exists so return values need little explanation (they are still named), and the description covers inputs, cross-tool workflow, and per-platform handling. For a non-idempotent creator tool with four parameters, nothing an agent needs to call 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 coverage is 100%, so the baseline is 3; the description rises above it by linking media_id to specific sources (suggest_cover frame / brand image / video) and clarifying that offset_ms is the video frame time. This cross-tool context is not derivable from the schema alone.

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 with full scope: a title drawn over a picture, saved as a new image. It clearly separates this from suggest_cover (which supplies frames) and from add_media, so the agent can pick it 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?

Explains exactly where the source picture comes from (a suggest_cover frame, any brand image, or a video with offset_ms) and how the result plugs into update_post as cover_media_id with thumb_offset_ms=null. It also enumerates per-platform applicability, which is real when-to-use context. It stops short of an explicit 'use this instead of suggest_cover when...' exclusion, keeping it at 4 rather than 5.

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

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

Annotations already declare not-readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds a genuine precondition not present in annotations ('Only for approved posts') and specifies that the link must point at the live post. It does repeat the idempotency hint ('safe to repeat with the same link'), which earns no extra credit but introduces no contradiction.

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; the core action is front-loaded and the constraint and format notes follow in priority order. Every 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. What remains is the unexplained target_id and the unstated consequence of marking an unapproved post; these are minor gaps for a two-parameter tool.

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

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

Schema description coverage is 0%, so the description must compensate. It does so for permalink, specifying it must be the https link of the live post on that platform, but target_id is never explained (target vs. post vs. account). With only half the parameters clarified, this is partial compensation rather than full.

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: 'Records that a person posted a target by hand.' This is clearly distinguishable from mutation siblings like create_post, retry_post, or update_post, but the description never names or contrasts a sibling explicitly, so it falls just short of the top band.

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?

'Only for approved posts' is a real gating condition that tells the agent when this tool is applicable versus when it is not. It does not name an alternative tool (e.g. request_approval or unapprove_post) for the unapproved case, but the precondition is clear context without needing to open 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 cover the safety profile (readOnly, idempotent, non-destructive, non-open-world), and the description reinforces with 'It reads only' rather than contradicting. It adds genuinely new behavioral context beyond annotations: the 100-post truncation limit and the `more` indicator, plus the interactive affordances (filter, read captions, edit, approve) that define what the planner surface offers.

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 time-zone scoping are front-loaded, and the sibling disambiguation lands early. The middle sentence enumerating in-planner actions ('open a post to read every caption, edit a caption...') is somewhat long for what it adds, but it is relevant to what opening the planner actually exposes.

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 an output schema and full annotation coverage, the description only needs selection guidance and behavioral caveats, both of which are present (time zone, start default, 100-post cap, `more` flag). The only gap is the unmentioned `brand` parameter, which the schema covers but the description never contextualizes.

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 are already documented, and the description only restates the `start` default and time-zone semantics. The `brand` parameter is not mentioned in the description at all, so no meaning is added beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource (opens the week planner) plus scope (seven days of posts in the workspace's time zone, starting from `start`, default today). It explicitly distinguishes itself from the sibling `list_posts` ('returns the same posts as data without the planner'), 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 explicit when-to-use triggers ('when the person asks to see or plan their week, or to open the calendar or planner') and names the alternative (`list_posts`) with the condition that selects it. Nothing about tool selection is left to inference.

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

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

Goes beyond the annotations by disclosing the approval workflow (owner/admin approves in Yaybird) and the returned approval_url, which the agent needs to relay. 'It does not change anything yet' is useful nuance against destructiveHint=true, though it could briefly reconcile that the removal still lands after approval.

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

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

Two sentences, zero filler, with the action and the alternative front-loaded before the approval caveat. Every clause 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?

For a mutation-with-approval tool that already has an output schema, the description covers the workflow, parameter sources and return artifact well. The remaining gap is the selection rule between rule_id and toggle and the default brand 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 coverage is 50%; the description compensates for the two undocumented params by sourcing rule_id from get_brand and defining toggle as a house style switch. It does not clarify the mutual exclusivity/requiredness of rule_id vs toggle, which the 0-required schema leaves ambiguous.

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

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

States a specific verb+resource ('remove one of a brand's rules') and names the two modes (rule_id removal vs toggle off), which cleanly separates it from add_rule and update_rule. It also preempts confusion by noting the tool does not delete immediately.

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

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

Explains the two use cases and where the rule_id comes from (get_brand), which tells the agent when each parameter applies. It stops short of explicitly excluding update_rule or stating that exactly one of rule_id/toggle must be supplied.

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, idempotentHint=true and destructiveHint=false; the description goes beyond them by explaining the idempotency mechanism ('a post already waiting just returns its link'), the side effect that the note is shown to the reviewer, and the hard limit that the call cannot itself approve. Those are exactly the behavioral facts an agent needs and that annotations cannot convey.

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, each earning its place: purpose, handoff destination, idempotency, note visibility, and the non-approval boundary. The most important constraints are front-loaded 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 an output schema present, return values need no explanation; the description instead covers what an output schema cannot — usage context, idempotent re-call behavior, reviewer-facing side effects, and the human-approval boundary. Nothing an agent needs in order to call 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 50%: note is documented in the schema, post_id is not. The description partially compensates by characterizing the acceptable post_id values (a draft, or a rejected post you have fixed), but adds nothing about note beyond what the schema already says. This lands at the baseline for partial 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 verb and resource — sends a draft or a fixed rejected post for human approval — and explicitly contrasts its role with show_posts/approval_url where the approval actually happens. The closing line 'It does not approve: only a person can' sharply separates it from any sibling that might look like an auto-approve action.

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

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

Clearly scopes when to call it: on a draft, or on a rejected post that has been fixed. It also names the downstream surface (show_posts or approval_url) so the agent knows the handoff target. It stops short of naming sibling alternatives to use instead (e.g. create_post, unapprove_post) or explicit when-not-to-call conditions.

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

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

Annotations only declare the generic write/openWorld/idempotent=false profile; the description goes well beyond by explaining conditional refusal states, the immediate-vs-scheduled publish behavior, and the safety rationale that only the person can verify the platform. This is exactly the behavioral 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?

Front-loaded with the primary action and eligibility, and every clause carries distinct information (states, timing, refusals). Slightly dense with parenthetical state references, but 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?

An output schema exists, so return values need no explanation, and the description fully covers the prerequisites, refusal conditions, and timing semantics an agent needs to invoke this correctly. Complete for a single-parameter state-transition tool.

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

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

Schema description coverage is 0% for the single target_id parameter, so the description must compensate; it implies target_id identifies a post target/approval subject but gives no format, source, or how to obtain the ID. It adds some meaning but not enough to fully cover the gap.

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 (retry/publish again) and a specific resource (a target of an approved post that failed), and states the exact eligibility condition by referencing the retry: 'not posted' state from get_post. An agent can distinguish this from create_post, update_post, or mark_posted 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 enumerates when to use it (target is 'not posted' or awaiting automatic retry), when it is refused ('unknown' retry state, unapproved posts), and routes the agent to alternatives (mark_posted for a live post, manual retry from the app). Nothing about the decision is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds substantial behavior beyond them: the chat UI it draws (Approve/Ask for changes/Approve all, greyed approved posts, Waiting/Approved/All filter), pagination limits (20 default, 100 max, next_cursor), and derived data semantics (approval.overdue, due_soon under 30 minutes, suggested_times). This is rich context an agent could not get from the structured fields.

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

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

The purpose and trigger are front-loaded, which is good, but the description is a single dense block and contains redundancy: 'list_posts returns the same calendar without drawing anything' and 'Returns the same data as list_posts' say the same thing twice. The long status enumeration also partly restates the schema enum, diluting conciseness.

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

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

An output schema exists, so return values need not be detailed, yet the description still flags notable data fields (targets[].local_time, approval.overdue, suggested_times). For a 7-parameter, zero-required, read-only tool, the coverage of filtering, defaults, paging and rendering behavior is complete enough 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 only 57%, so the description must compensate, and it does for the highest-risk parameter: every status enum value is explained (e.g. changes_requested = 'sent back with notes to fix', failed = 'a target failed or needs action'), plus date format guidance for from/to (ISO 8601 with offset, UTC default) and paging via next_cursor. It adds meaning beyond the raw schema, though the brand parameter is only 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 ('Shows posts') plus the exact rendering scope: 'one approval list in the chat' with waiting posts first and approve/unapprove controls. It also explicitly differentiates from the sibling list_posts, which 'returns the same calendar without drawing anything', so an agent can distinguish the two without opening schemas.

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

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

Gives explicit triggering conditions ('For posts just saved (by their post_ids), or when the person asks to see or review posts, such as "what is waiting for my approval?"') and names the alternative (list_posts) with the condition that selects it. Nothing about when to use this versus its sibling is left to inference.

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

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

Adds substantial context beyond the annotations: the first call generates the frames and can take a few seconds (explaining why readOnlyHint is false, without contradicting idempotentHint since repeats reuse the same result), previews are 640 px while the final cover is re-rendered at full size, and unreadable videos (>=100 MB, >10 min, odd format) fall back to sample_times_ms until a person opens the app's cover picker.

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?

Single dense paragraph, front-loaded with what the tool returns before moving to usage and platform constraints. Every clause carries decision-relevant information (scoring criteria, platform matrix, latency/fallback), though the platform matrix is arguably about the consumer of the result and makes the paragraph heavy.

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

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

Given an output schema exists, return values need no further explanation, yet the description still covers scoring dimensions, downstream usage, platform applicability, first-call latency, and the degraded path for unreadable videos. Nothing needed to call this tool correctly appears to be 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% for both parameters, so the baseline is 3. The description clarifies that media_id refers to a video and implies ranking/ordering of results, but says nothing about limit (the only other parameter) beyond what the schema already states.

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 — candidate cover frames of a video, ranked best-first — and immediately enumerates what each candidate contains (media_id, url, offset_ms, score, notes). It is clearly distinguishable from siblings such as make_cover or add_media 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?

Explains the downstream chain concretely (feed a candidate into update_post/create_post as cover_media_id + thumb_offset_ms) and gives platform rules that determine whether the call is worthwhile at all (Stories/X/Threads/Bluesky take none; YouTube images only on long videos). It does not, however, explicitly contrast this tool with the sibling make_cover, which is left as 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?

Goes well beyond the annotations (which only cover safety/idempotency) by disclosing that nothing further publishes until a human re-approves, that this override holds even on brands that auto-approve agent posts, and that already-live platforms remain live. This is exactly the consequence-level context an agent needs before mutating state.

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

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

Front-loaded with the core action, then layered with the important edge cases. Efficient overall, though the parenthetical about auto-approving brands and the approval_url clause make it slightly dense for its size.

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

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

An output schema exists, so return values need not be described. For a state-mutating tool with annotations present, the description covers the critical unknowns: resulting state, human-in-the-loop requirement, and handling of already-published platforms. Nothing essential 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?

Two parameters at 50% schema coverage. The revision parameter is documented in the schema and post_id is self-evident, but the description adds no parameter-level meaning (e.g., no guidance that post_id must reference an approved post). Baseline 3 is appropriate given partial coverage handled by 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 ('Puts an approved post back on hold') and defines the resulting state precisely. It differentiates itself from adjacent operations by noting that live platforms stay live (unlike cancel) and by routing re-approval to show_posts/approval_url, so an agent can distinguish it from siblings 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?

Provides a clear trigger condition ('For when the person asks to hold a post back or unapprove it'). It clarifies who can act (only a person, not agents) but does not explicitly name a competing alternative such as cancel_post to contrast against, 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?

Goes well beyond the annotations by disclosing side effects that matter: edits to an approved post force re-approval and notify the approver, the moving-later exception preserves approval, overdue posts move only via next_slot or suggested_times, and refused targets leave earlier edits in place. These are exactly the non-obvious behaviors an agent needs before mutating a live post.

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 edit scope are front-loaded, but the body is a dense wall of platform-specific trivia (character limits, hashtag caps, media rules) that largely duplicates the schema's own descriptions, making the text longer than the decision-making guidance requires.

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

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

An output schema exists and annotations already carry the destructive/non-idempotent profile, so return values and safety need no repetition. The description is strong on approval flow and refusals, but is thin on the meaning of a few top-level fields (account_id, mode) that still have to be inferred.

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 on the top-level parameters is partial, and the description compensates by explaining scheduled_at semantics ('next_slot', moving an approved post later, ISO offsets), the per-target field set, and ai_generated's platform labels. brief, title, post_id and account_id are still left largely to the schema, so it does not fully close the gap.

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

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

Opens with a specific verb and resource ('Changes a post before it publishes') and then enumerates exactly which parts are editable (title, brief, scheduled_at, AI label, per-target caption/media/cover/title/mode/time/account). This clearly distinguishes it from siblings like create_post, check_post, get_post and cancel_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?

Gives concrete context for when edits are applied versus refused (targets already posted or publishing), and routes the agent to get_post, get_workspace, get_brand and suggest_cover for dependent data. It does not, however, explicitly contrast update_post with close alternatives such as check_post or request_approval when deciding whether to edit at all.

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 by disclosing the central behavioral trait: the change is not applied immediately, it requires owner/admin approval in Yaybird, and an approval_url is returned. It also flags full-replacement semantics ('the whole new rule is sent, not just the changed fields'), which an agent would otherwise assume is a partial patch. No contradiction with destructiveHint/idempotentHint.

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 with the purpose front-loaded, then the approval behavior, then the full-send caveat; nothing is padding. The opening 'Asks to change' is slightly indirect for what is really an approval request, but it costs little.

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 gated by an approval flow, the description covers the deferred-application model, the approver role, the returned approval_url, the rule_id source, and the full-object requirement; brand optionality is handled by the schema and the output schema covers return values. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 75%, so the baseline is 3, but the description adds real meaning: rule_id must be obtained from get_brand, and the `rule` object must be the complete rule rather than a delta. That full-replacement constraint is genuinely useful parameter semantics 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?

Names a specific verb and resource ('change one of a brand's rules') and points to where the rule_id comes from (get_brand), which separates it from add_rule/remove_rule in the sibling list. It stops short of explicitly contrasting with those siblings, but the intent 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?

Usage is implied — use this to modify an existing rule obtained from get_brand — but there is no explicit 'use this instead of add_rule when...' routing or stated prerequisites. Adequate but leaves the agent to infer the boundary with add_rule and remove_rule.

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