Simplo

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

Goes far beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) by disclosing the real-world consequence: posts publish to live social accounts automatically at their times. It also documents the partial-failure model — failed drafts stay as drafts and come back in a skipped list with enumerated reasons (past, off_hour, needs_picture, not_connected, needs_tiktok_choices, platform_unavailable) and the remediation for each.

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 action, then the safety gate, then failure handling — a sensible order with no filler sentences. It is dense as a single unbroken block, and the long parenthetical enumeration of skip reasons slightly hurts scannability, but each clause carries operational 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?

For a high-consequence, irreversible-feeling bulk publish with no output schema, the description covers consent handling, timezone resolution, partial failure semantics, and per-reason next steps. An agent has everything needed to call it correctly and to recover from every documented failure mode.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning on top: weekStart defines a seven-day window starting at midnight, timeZone has a three-tier fallback (explicit zone, then the zone the week was filled in, then the user's), and confirm is a user-consent gate that must follow an explicit ask. Only the exact weekStart/pattern mechanics are left entirely to 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?

Opens with a specific verb and resource plus scope: 'Schedules every dated draft (draft_scheduled) in a week at the time it is already placed at, in one go.' The analogy to the 'Approve week' button on the Plan page pins down exactly which UI action this mirrors, separating it from single-post tools like publish_post and schedule_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?

States the required workflow explicitly: show the week with list_posts, ask the user, then pass confirm: true. It also names alternatives for failure paths — schedule_post to move a past draft, update_post to add a picture or tiktokSettings — so the agent knows both when to call this and what to do when it partly fails.

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 destructiveHint/idempotentHint annotations by enumerating concrete consequences: the project disappears from list_projects and the app, scheduled posts stop going out, and a connected YouTube channel is disconnected. It also discloses what is preserved (posts and profile) and the restoration path, which is exactly the behavioral 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?

One tightly packed sentence covers effects, persistence, reversibility, and the consent instruction, with the irreversible-sounding consequences front-loaded. No filler and no repetition of structured data.

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 destructive tool, the description covers scope of effect, side effects on linked resources, data retention, and the confirmation protocol. No output schema exists but none is needed since return behavior is not decision-relevant here.

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

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

Schema coverage is 100%, so projectId's meaning and origin (list_projects) and confirm's consent requirement are already documented in the schema. The description reinforces the confirm gate ordering but adds no new format or constraint detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Archives a project") and immediately anchors it to an observable behavior the user knows ("as deleting a brand in the app does"). An agent can distinguish this from destructive siblings like delete_post and from create_project, which is named only as the undo path.

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 preconditions for invocation: ask the user for consent, then pass confirm: true. It also points to create_project with reactivateProjectId for the reverse operation. It stops short of saying when NOT to archive (e.g. when the user only wants to hide scheduled posts, which unschedule_post would handle), so it is strong but not a full routing guide.

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 credit costs, that boldPhoto always generates pictures, that slide text is rendered in real brand fonts, that a passed time never auto-sends, and that replacesPostId deletes the old draft so the plan never holds both. The only gap is the mention of possibleDuplicateOf, which does not appear in the input schema, leaving its origin ambiguous.

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

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

Front-loaded with purpose and then cost, then behavior, then the follow-up routing — a good ordering. It is one dense block and the final sentence about possibleDuplicateOf arrives without context since that field is not in the schema, which slightly blunts the structure.

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 11 parameters and no output schema, the description carries the burden well: it explains what comes back (a preview of every slide), what overflowSlides means and what to do about it, and how scheduledLocal should be checked. Combined with the schema, an agent has what it needs to call this correctly.

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

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

Schema coverage is already 91%, so the baseline is 3, but the description adds real meaning: the picture cost implication, the boldPhoto style forcing pictures, the preference of localTime over scheduledAt, and the deletion/day-inheritance semantics of replacesPostId. It does not repeat the schema's enum explanations, which is the right call.

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 — 'Writes and draws an Instagram carousel about a topic, then saves it as a draft post' — which cleanly separates it from create_post and create_reel among the siblings. The end state (a draft, not a published post) is stated in the same breath.

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

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

Explicitly says this tool never publishes or schedules, and names the follow-up tools: 'schedule it with schedule_post, or publish it with publish_post, after the user approves.' It also gives conditional usage for the time parameters (place the draft on its day) and for replacesPostId (redo a carousel) and possibleDuplicateOf (ask the user).

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 flag this as a non-read-only, non-idempotent mutation, and the description adds the crucial risks on top: a scheduled post auto-publishes to real accounts, times must be on the hour and in the future, drafts with a time never send, and videos are limited to 100 MB and copied to Simplo hosting. That is strong disclosure, but the description says nothing about what happens on partial platform failure or how to recover a mis-scheduled post (unschedule_post/publish_post siblings go unmentioned).

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 a long single block, but front-loaded with the action and then the highest-risk fact (auto-publishing to real accounts). Every clause carries operational content — hour alignment, cover frame, upload fallback, platform exclusions — with no filler, though paragraphs or line breaks would have improved scanability.

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 15-parameter, nested-object mutation with no output schema, the description covers the full decision tree: draft vs scheduled, media source paths, scheduling time formats, video platform coverage, and how to interpret possibleDuplicateOf in the response. Nothing an agent needs 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 already 87%, so the schema carries most per-field meaning; the description still adds cross-parameter logic the schema cannot express, such as uploadId replacing imageUrl or videoUrl, the localTime-versus-scheduledAt exclusivity, and the confirm gate on scheduling. The aiGenerated and tiktokSettings subtleties are left mostly to the schema descriptions.

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

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

The first sentence gives a specific verb and resource plus the two output modes: "Creates a single-image or video post as a draft (the default) or scheduled." It also bounds the media types (single image or video), which implicitly separates it from create_carousel and create_reel, but it never names those siblings, so an agent must infer the boundary.

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

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

Explicit routing conditions throughout: ask the user before scheduling and pass confirm: true, use localTime with timeZone in preference to scheduledAt, pass videoUrl instead of imageUrl for video, and call create_upload_link plus uploadId when the media is a local file rather than a public URL. It even states video does not go to X, and that possibleDuplicateOf should trigger a user question.

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

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

Annotations already declare non-readonly, non-idempotent, open-world, non-destructive, but the description carries the real behavioral weight: creation is asynchronous with analysisStatus "analyzing" and requires re-polling get_brand until a profile appears. It also discloses plan gating ("free, needs an active plan", per-plan brand limits) and an unusual refusal path with a recoverable id — none of which are inferable from annotations.

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

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

Front-loaded with the core action and the async behavior, then the refusal path, then the caution to ask the user — a sensible ordering with no filler. It is a single dense paragraph with long compound sentences, so the conditional branches around reactivate/fource are harder to scan than they could be, but every clause carries operative 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?

Covers what an agent must do before (ask the user), during (choose website vs description, set contentLocale), and after (poll get_brand until the profile answers) invocation, plus the exception path for archived duplicates. With no output schema present, the description supplies the essential return signal (analysisStatus "analyzing") that would otherwise 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 coverage is high (83%), yet the description still adds meaning the schema lacks: contentLocale is the language posts are written in and defaults to the user's interface language, description becomes the profile's description when no website is given, and reactivateProjectId restores the archived brand with its posts and profile rather than creating fresh. It also clarifies the choice between reactivateProjectId and force.

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 ("Makes a new Simplo project (one per brand)") and immediately scopes the two creation paths, website vs. description. This distinguishes it cleanly from siblings like update_brand, get_brand and list_projects, and even reconciles the title mismatch by defining a project as one-per-brand.

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

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

Gives explicit routing rules: pass websiteUrl when a site exists, a description when it doesn't, description-plus-website is treated as extra context, and description-only requires follow-up via update_brand. It also names alternatives by name (get_brand for polling, update_brand for filling profile fields, reactivateProjectId vs force) and states the human-in-the-loop rule "Ask the user before making a brand."

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

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

Beyond the annotations it discloses credit consumption ('COSTS CREDITS (one render)'), latency (~a minute), source deletion semantics with its precondition and refusal path, the sourceRemoved signal, TikTok caption rewriting, and the no-music limitation. These are exactly the side effects an agent cannot infer from readOnlyHint=false / destructiveHint=false.

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

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

It is front-loaded with the core action and every claim is load-bearing for a 10-parameter, credit-charging tool. It loses a point for heavily nested parentheticals (the cover/style clause) that make single sentences hard to parse on first read.

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

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

With no output schema, the description still signals the meaningful result (a new draft, sourceRemoved, removed source), the cost and timing, and the next step. Nothing needed to call it safely 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, but the description adds real meaning on top: what happens when hook/endLine/cta are omitted, why consumeSource exists, how platforms changes the caption and routes the video, and why tiktokSettings must be asked of the user rather than defaulted.

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

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

The opening sentence gives a specific verb and resource ('Turns an existing post's pictures ... into a short animated vertical video and saves it as a NEW draft video post') plus the scope distinction that the original post is untouched unless consumeSource is passed. An agent can distinguish this from create_carousel and create_post without opening any schema.

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

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

It names the explicit pre-step pattern ('make the carousel with create_carousel, then pass consumeSource: true here'), states the follow-up ('schedule it with schedule_post after the user approves'), and rules out behavior ('never published or scheduled here', 'never X'). Exclusions and alternatives are both spelled out.

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

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

Annotations only declare the mutation profile; the description adds everything operationally important: single-use, project-scoped, one file, 15-minute vs 24-hour expiry, per-type size caps (MP4/MOV 100 MB, JPEG/PNG 5 MB), retry after a refused file, and deletion of unused files after 24 hours. It also warns 'never put the file in a tool argument', which prevents a likely misuse.

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

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

Front-loaded with the key distinction and the return value, and nearly every clause carries non-obvious information. The trade-off is density: the branching logic, limits, and expiry rules run together in one block rather than being separated into scannable steps.

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

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

There is no output schema, yet the description fully covers what comes back (uploadUrl, uploadId), how long it lives, and how it is consumed downstream. Nothing an agent needs to call this correctly or explain it to a user 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, and the description goes beyond it: forPerson is explained as changing both who uploads and the expiry window (24h vs 15m), and kind is implicitly tied to the format/size limits. It doesn't restate projectId, but the schema already sources it from list_projects.

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 ('create an upload link'), the exact return value (a single-use uploadUrl), and draws a hard boundary against the public-URL case. An agent can distinguish this from create_post/create_reel/generate_image without opening any schema.

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

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

Gives explicit branching: if you have shell access, run the returned curl; if you don't (Claude.ai, blocked host) or the user holds the file, set forPerson: true and hand the URL over. It also names the downstream step (pass uploadId to create_post or update_post) and the verification sibling (get_upload says whether the file arrived).

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 flag destructiveHint and idempotentHint, but the description adds substantive context beyond them: irreversibility, the human-approval gate, that the post is NOT removed from connected social platforms, and that analytics data is dropped with the record. Those are exactly the consequences an agent needs before committing 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, zero filler, ordered by importance: what it does, then the irreversibility plus approval gate, then the consequences by post state. Each sentence changes how an agent would call the tool.

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

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

Fully adequate for a 3-required-param destructive tool with no output schema: the agent knows the action, the safety gate, and the downstream effects on platforms and analytics. Nothing material is missing to invoke it correctly.

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

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

Schema coverage is 67% and confirm already carries its own description in the schema; the description only restates "pass confirm: true" without adding format or constraint detail. postId and projectId get no semantic treatment in the description beyond the schema's list_projects hint, so baseline 3 is appropriate.

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

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

Specific verb+resource ("Deletes a post from Simplo") plus a scoping clause that separates it from sibling mutations like unschedule_post and update_post by explaining what actually happens to the record and its analytics. An agent can distinguish it from the rest of the post lifecycle tools 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?

Gives an explicit precondition ("ask the user first, then pass confirm: true") and clarifies the scheduled-vs-published outcome, which is exactly the ambiguity that leads agents to confuse this with unschedule_post. It stops short of naming unschedule_post as the non-destructive alternative, so the routing is implied rather than stated.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantive behavior beyond that: the URL expires after 24 hours, it works without signing in, and the archive reflects whatever is planned at the moment the link is opened (deferred snapshot, not a frozen export). Those are exactly the operational facts an agent needs and cannot get from 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-loaded with the return value in the first sentence and reasonably dense throughout, with no filler. The prose is somewhat run-on across clauses (scope, output layout, audience, delivery instruction, expiry), so an agent must parse one long block rather than scan discrete lines.

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

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

With no output schema, the description compensates well by describing the returned artifact (zip, per-post folders, media, caption .txt, filename metadata) and its lifetime. Minor gaps remain: no mention of failure modes (e.g., nothing planned in the range) or the timezone-required behavior beyond the schema hint.

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%, including the timeZone semantics ('sets the day boundaries and the times in file names') and the days default of 7, so the schema already carries the parameter burden. The description only echoes the 1–31 day range and the per-file naming, adding little beyond structured data. Baseline 3 applies.

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

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

States a specific verb and resource up front: 'Returns a link to a zip of the posts planned in a week (or any 1–31 days)', plus the exact archive layout (one folder per post, media plus caption .txt, planned time/platforms in filenames). It implicitly separates itself from scheduling/publishing siblings ('For posting by hand or through another scheduler'), but never names an alternative tool, so the differentiation is by scenario rather than by sibling.

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

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

Gives clear situational context for choosing this tool: use it when the user will post by hand or via another scheduler, when no account is connected, or when on the free trial. It also gives an interaction guideline ('Give the user the url as plain text'). It stops short of explicit exclusions, such as when to prefer publish_post or create_upload_link instead.

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

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

The description discloses traits beyond the annotations: it consumes credits, requires a completed brand profile, persists output as a research session, and defines what an idea contains. The annotations only say it is a non-destructive write, so the description adds substantial behavioral context.

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

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

The description is three dense sentences with no waste. The core action, the cost warning, the prerequisite, and the carousel exception are all front-loaded and easy to scan.

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

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

For a non-destructive write tool with no output schema, it covers prerequisites, cost, persistence, and output contents well. It does not explicitly describe the return value or default behavior for limit/platforms, which keeps it just short of fully complete.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description adds little parameter-specific meaning beyond mentioning topic and the carousel routing, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ('Generates on-brand post ideas') and enumerates the produced fields (hook, caption, hashtags, image prompt, format). It also explicitly distinguishes itself from create_carousel and generate_image for carousel-format ideas.

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 prerequisite ('Needs a completed brand profile'), warns about credit cost, and routes a specific scenario (carousel-format ideas) to create_carousel rather than this tool or generate_image. That gives the agent clear conditions for use versus alternatives.

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 non-readonly, non-destructive, non-idempotent; the description adds the materially important side effects: writes into project image history, consumes credits, and returns hosted URLs plus a preview for verification. It is slightly weakened by "more for higher tiers" when the modelTier schema states every tier currently bills as standard, a cost inconsistency an agent could act on wrongly.

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 action and persistence effect, then return values, then cost, then the alternative. Each sentence carries distinct decision-relevant information with no repetition of the 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?

With no output schema, the description correctly spells out what comes back (hosted URLs + previews), and it warns about credit spend for a mutation-style tool. It falls short only on includeLogo and on the tier-cost statement, which the schema contradicts.

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

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

Schema coverage is 75%, with style, format, prompt, modelTier, projectId and adBackground already documented in-schema. The description adds the meaningful output linkage (URLs go to create_post) but does not compensate for the undocumented parameters, notably includeLogo, and its cost claim about tiers conflicts with the schema's modelTier note.

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

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

Specific verb + resource ("Generates on-brand images") plus the persistence effect ("saves them to the project's image history"). It is clearly distinguishable from create_carousel, create_post and create_reel in the sibling list by naming image generation as its scope.

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

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

Explicitly routes the agent away for a specific case: "For tips, steps or a list of points, a short styled carousel (create_carousel) reads better than one picture." It also names the downstream consumer of the output (create_post), so the agent knows where the result flows.

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 readOnlyHint and openWorldHint=false, but the description goes much further: counts are read once a day so comparisons appear only once history reaches back, historyFrom bounds the history, notes explain gaps, and collected: false with reason tells the agent Instagram-only coverage plus the posting-partner reconnect case. It also discloses staleness via lastSyncedAt, which is the key behavioral risk for a metrics tool.

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

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

One dense paragraph, front-loaded with followers then posts then usage, with no filler sentences. It is however long and partly repeats itself ('Nothing is read from the platforms here' restated by the lastSyncedAt clause), which costs a perfect score.

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

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

No output schema exists, so the description carries the return shape alone and does so thoroughly: followers fields, historyFrom, notes, collected/reason, posts.top and posts.bottom with ranking order and non-overlap, and ranked counts. Nothing needed to call or interpret this 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 100%, so the baseline is 3; the description earns above that by explaining the range coupling in prose ('last 28 days by default, or from and to (dates in timeZone)') and that limit applies to top and bottom separately. It adds little on from/to format beyond what the schema already documents.

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 ('how each connected account is doing': followers at now/7/28 days plus top and bottom posts by engagement) and explicitly separates itself from get_post_metrics, which 'reads them live and lists every post'. An agent can pick between the two 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?

'Use it to say how the account itself is doing, and which posts worked and which didn't' gives the selection criterion, and get_post_metrics is named as the alternative with the condition that selects it (live platform reads, every post). The only missing element is an explicit negative case, which the alternative already covers.

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

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

Annotations only say readOnly; the description adds the crucial behavior that the call can return analysisStatus 'analyzing' and ready: false while the site is being read, and that the agent should retry after a delay. It also discloses a global output rule (posts are always sentence case regardless of the brand's website) that is not in structured fields.

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

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

Front-loads the return contents, then the alternative, then the async-status caveat — sensible ordering. The sentence-case statement is tangential to what the tool returns, though it does convey a brand-writing rule an agent may need later.

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

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

For a simple one-parameter read with no output schema, the description covers both the normal return shape and the pending-analysis case, which is the main failure mode an agent would hit. Nothing important 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 coverage is 100% and the only parameter, projectId, is already described in the schema (with its source, list_projects). The description adds no parameter-level syntax or formatting details, so the baseline 3 applies.

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

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

States a specific verb and resource ('Returns the project's brand profile') and enumerates the contents: voice, audience, products, colors, typography. This clearly distinguishes it from sibling update_brand, which writes the same profile.

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 the read/write split against update_brand and, more usefully, states exactly when to call it again (after create_project or reread_website) and what to do (wait a minute). It does not say when NOT to call it, but the practical guidance is strong.

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 openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the spend order (plan credits first, then bonus), that actions degrade to bonus credits rather than failing, and that content creation depends on subscription status.

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

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

Front-loads the return summary, then unpacks the two credit fields, then closes with the usage call-to-action. Dense but every sentence carries meaning; the em-dash clauses require a second read but are not wasteful.

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

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

With no output schema and no parameters, the description correctly takes on the job of explaining what comes back (creditsRemaining vs planCredits vs status) and how to interpret it. An agent has everything needed to call it and understand the result.

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 are zero parameters, so there is no parameter semantics to carry; baseline is 4. The description is used instead to define return field semantics (creditsRemaining, planCredits, status), which is a reasonable substitute.

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 ('Returns the signed-in user's plan and credits') and scopes it to the current user, which no sibling tool does. An agent can distinguish it from create_post or get_post_metrics 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?

'Check this before running actions that cost credits' gives a concrete pre-condition, and the note that content creation needs an active subscription identifies the gating scenario. It stops short of naming specific credit-consuming siblings, but the trigger condition is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds useful field-level context (status, publish error, TikTok AI labels) beyond annotations, but doesn't disclose error handling, permissions, or rate limits.

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

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

Two sentences, front-loaded with the core purpose. The second sentence is dense but adds useful detail about TikTok-specific fields; no wasted words, though the length is near the upper bound for a simple getter.

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

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

Given a simple read tool with two parameters and no output schema, the description covers return fields well. However, it omits any explanation of the postId parameter and doesn't mention error behavior (e.g., if the post is not found).

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%: projectId is described, but postId is not. The description adds no meaning about either parameter, failing to compensate for the undocumented postId.

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 ('Returns') and resource ('one post'), plus extra scope about status and publish error. It clearly implies a single-post retrieval, distinguishing it from list_posts, though it doesn't explicitly name alternatives.

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 to get details of a single post. No explicit when-to-use or when-not-to-use guidance, and no mention of alternatives like list_posts or get_post_metrics.

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 readOnlyHint/openWorldHint: it discloses that numbers are read live from Instagram, TikTok and X on every call, that error rows carry last-good numbers when an account needs reconnecting or TikTok has no video id yet, that only Instagram and TikTok outside accounts are read, and that TikTok may double-count unmatchedSimploPosts. These are exactly the failure modes an agent needs before trusting the output.

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 essentially waste-free — nearly every clause adds a fact that is unavailable in the schema, and the payload shape is front-loaded before the grouping and outside-post semantics. The single unbroken paragraph makes it hard to scan for a 9-parameter tool, which is the main structural cost.

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

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

With no output schema and nine parameters, the description carries the full burden and does so: it defines the row shape, the overview/group breakdown, outside-account behavior, per-platform reporting quirks and error semantics. An agent can call this correctly and interpret the result without further documentation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: groupBy medians/totals are computed over every row in the range rather than only returned rows, style 'none' holds pictures, videos and plain slides, and includeOutside rows expose platformPostId and url instead of postId. The days/postId interaction ('published within days') is left implicit.

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 concrete verb and resource — 'How the published posts did: one row per post and platform' — and immediately enumerates the metrics returned (views, reach, likes, comments, shares, saves, profileVisits, engagement, lastSyncedAt). It also distinguishes itself from get_account_summary by routing follower counts there, so an agent can separate it from a nearby reporting tool.

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

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

Gives an explicit usage scenario: 'Use it before planning to see what worked: sort by engagement or reach, and pass includeOutside to count every post on the account', plus the meaning of order=asc. What is missing is any contrast with sibling listing tools (list_posts, get_post) — an agent must infer when to fetch metrics versus plain post data.

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

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

Annotations already declare this as a read-only, non-open-world operation. The description adds useful behavioral detail beyond annotations by naming the waiting/uploading/ready states and explaining what is returned once ready.

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 efficient sentence with the core status-checking purpose and readiness outcome front-loaded. There is no unnecessary explanation.

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

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

For a simple two-parameter read tool with no output schema, the description covers purpose, status values, and the successful ready-state return. It leaves minor gaps around uploadId sourcing and error behavior, but is otherwise complete.

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

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

Schema coverage is 50%: projectId is documented as coming from list_projects, while uploadId has no schema description. The description connects this to create_upload_link, which gives helpful context, but it does not explicitly explain that uploadId is the link identifier returned by that sibling.

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 operation: checking whether the file behind an upload link has arrived, with the possible statuses named. It explicitly references create_upload_link, helping distinguish this read/status tool from the link-creation sibling.

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

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

Usage is clearly implied as checking the status of an upload link created by create_upload_link. It does not state explicit exclusions or alternatives, but the context is clear enough for an agent.

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 openWorldHint=false; the description adds real value on top by explaining the operational consequence (a post only reaches a platform that is connected and not needing reconnect) and that it is a read-only surface for a mutation performed elsewhere. It does not describe the shape of the returned list, so it stops short of a 5.

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

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

Three sentences, each doing distinct work: what is listed, why it matters operationally, and where connection actually happens. The key constraint is 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?

For a one-parameter read-only tool with no output schema, the description covers what is returned (connected accounts and unconnected platforms) and the preconditions an agent needs before scheduling or publishing. Nothing needed to invoke 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% and the single parameter projectId already documents itself as a Simplo project id from list_projects. The description adds no additional meaning about the parameter, so the baseline of 3 applies.

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

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

Specific verb+resource: lists social accounts connected to a project, plus platforms that are not connected. The scope (connected vs. not connected) is stated precisely, which distinguishes it from siblings like list_projects or get_brand.

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

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

Explicitly says to check this before scheduling or publishing, and states the hard limitation that connection/reconnection happens in the Simplo app (Brand → Channels) and cannot be done by this tool. That is both a when-to-use and a when-it-won't-help.

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

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

Annotations already declare readOnlyHint and closed-world, so the safety profile is covered; the description adds ordering behavior (planned order vs newest first), pagination semantics (limit + nextCursor), and a genuine cost warning that fields:'full' can run past what the agent can read for a month. It also explains domain states (draft_scheduled never sends by itself, missed posts must be rescheduled). It stops short of describing failure modes or rate limits, so not a 5.

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

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

Purpose and the date-range guidance are front-loaded and no sentence is filler, but the single dense paragraph stacks nested parentheticals (the reelPostIds aside embeds a delete_post recommendation) that slow parsing. It would read better split into scope, filtering, and pagination blocks.

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

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

With no output schema, the description carries the return-value burden and does so: it enumerates the summary fields (id, status, platforms, times, firstLine, slideCount/style, video length, possibleDuplicateOf, reelPostIds) and contrasts them with fields:'full'. Combined with ordering and pagination rules, nothing an agent needs 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 100%, so the baseline is 3, but the description adds meaning beyond the schema: from/to are both inclusive and 'a week across two months is one call', dates are read on the timeZone clock, and fields:'full' is flagged as long output rather than a richer detail level. It leaves month vs from/to tradeoffs mostly to 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 plus scope ('the project's posts') and enumerates the status universe it covers (drafts, scheduled, published, failed, missed). It explicitly separates itself from get_post ('returns one post whole') and delete_post, so an agent can choose without opening sibling 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 concrete when-to-use rules: pass from and to 'to see what is planned in a week', otherwise results come newest first, and narrow with status/platform. It also names alternatives (get_post for a whole post, delete_post for Reel source drafts after user agreement) and explains cursor reuse.

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 openWorldHint=false, so the safety profile is covered. The description adds only that results are one-per-brand; it does not say what to expect for a user with no projects, whether the list is paginated or bounded, or what the call costs.

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

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

Two short sentences with no filler, and the identity of the resource is front-loaded ahead of the routing hint. Nothing could be removed without losing information.

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

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

For a zero-parameter list tool with a clean schema and read-only annotations, this is nearly complete. The one real gap is the return shape: with no output schema, the agent isn't told which fields (e.g. an id vs. a display name) it should extract to feed the downstream projectId.

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?

Zero parameters, so there is nothing for the description to disambiguate; the baseline applies. The note about projectId being consumed elsewhere is useful framing but is not parameter semantics for this call.

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 ('Lists the user's Simplo projects') and adds a clarifying scope detail ('one per brand'), so the agent knows the granularity. It does not distinguish itself from the sibling list_accounts, which an agent must also disambiguate.

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

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

The sentence 'Most other tools need a projectId from here' is an effective ordering signal that tells the agent to call this before other tools. It stops short of stating prerequisites or when-not-to-use conditions (e.g. when a projectId is already known).

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 flag destructiveHint=true and idempotentHint=true, but the description adds the substantive context behind those flags: it posts publicly on the user's real accounts, cannot be undone, and retries skip platforms already published. That mechanism-level detail about partial-success behavior is not derivable from the annotations and is exactly what an agent needs before an irreversible write.

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 action, then the risk, then the mitigation. No filler, and the most safety-critical clause ("cannot be undone") is placed where it will be read before the call is made.

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

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

For an irreversible write with no output schema, the description covers the essentials: side effects, reversibility, the confirm gate, and retry safety. It does not describe what a partial or total failure looks like in the response, which would help an agent report outcomes, but that is a minor gap given the tool's simplicity.

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

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

Schema coverage is 67% (postId undocumented, projectId and confirm documented). The description reinforces confirm's meaning by tying it to the user-approval gate rather than a generic boolean, which is more actionable than the schema's own wording. postId's role is implied by "an existing post" but never explicitly explained.

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 ("Publishes an existing post to its platforms") plus a timing qualifier ("immediately") that cleanly separates it from the sibling schedule_post. An agent can tell at a glance that this is the act-now variant rather than the queued variant.

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

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

Gives an explicit precondition workflow: "always ask the user first, then pass confirm: true," which tells the agent exactly what must happen before invocation. It also notes retry is acceptable because already-published platforms are skipped. What's missing is direct routing advice against siblings (e.g. use schedule_post when the user wants a future time).

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: it discloses that scope 'everything' rewrites description, audience, voice and products and replaces user edits, that it runs in the background, that scope 'look' preserves an uploaded logo, that the call takes about a minute, and that it is free but requires an active plan. This is exactly the context the readOnlyHint=false / destructiveHint=false 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?

Front-loaded with the core action and the default scope, then the riskier mode. It is dense with nested parentheticals, which slightly hampers scanning, but every clause carries operational information and nothing is filler.

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

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

For a long-running, partly background, partly destructive operation with no output schema, the description covers duration, result delivery ('answers with the updated brand when done'), the async polling step, the free/plan constraint, and the confirmation requirement. An agent has everything needed to call it correctly and not surprise the user.

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

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

Schema coverage is 67%, but the description fully compensates: it defines what each enum value of scope actually does, explains the logo-preservation side effect, and states that confirm is required only for scope 'everything' after user agreement. That is meaning well beyond the schema's terse field descriptions.

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

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

States a specific verb and resource ('Reads the brand's website again') plus the trigger scenario ('after a rebrand'). It then splits the tool into its two modes and names the siblings it is not (update_brand, get_brand), so an agent can distinguish it from neighbors 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?

Explicit routing: scope 'look' for visual-only refresh, scope 'everything' for full re-analysis, and 'To set a field to a value you already know, use update_brand instead.' It also states the precondition for confirm: true (user agreement) and the follow-up step (read get_brand a few minutes later).

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

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

Annotations only say this is a non-read-only, idempotent, non-destructive write; the description goes well beyond by disclosing that the post is auto-published to real social accounts, that user confirmation is mandatory, that publishing is hourly on the hour, that the time must be in the future, and that a duplicate-detection field (possibleDuplicateOf, 14-day window) may come back and should be surfaced.

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?

Roughly a hundred words for a genuinely complex tool, with the core action first, then preconditions, then time-format guidance, then return-value hints. No filler sentences; the 'publishes once an hour, on the hour' clause justifies rather than repeats the constraint.

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

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

No output schema exists, yet the description names the two return fields that matter for correctness (scheduledLocal to verify the saved time, possibleDuplicateOf to warn the user) and instructs how to act on them. Combined with the confirmation gate and time-format rules, an agent has everything needed to call this correctly.

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

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

Schema coverage is 83%, so the schema already documents confirm, timeZone, localTime and scheduledAt in comparable detail. The description largely restates those rules (localTime with timeZone vs scheduledAt, future-and-on-the-hour) and adds only modest framing, such as the consequence of omitting a time entirely.

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 with scope: scheduling an existing post or moving an already-scheduled one. The phrase 'an existing post' and 'a post that already went out cannot be rescheduled' cleanly separates it from create_post and publish_post in the sibling list.

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

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

Explicit when-to-use and when-not: works on drafts (including draft_scheduled), scheduled, missed and failed posts, but not published ones. It also states the consent precondition ('ask the user before scheduling, then pass confirm: true') and the no-time fallback, and routes between the localTime and scheduledAt options with a stated preference.

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

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

Annotations already declare non-read-only, non-destructive, idempotent, but the description adds real context an agent needs: nothing is deleted, it alters what publishes to the user's live social accounts, user confirmation is mandatory, the default keeps the post's day while keepDay:false drops it to Unscheduled, and already-published/publishing posts are rejected. Per-item result semantics for batch calls are also disclosed.

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

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

One dense paragraph, front-loaded with the core action and safety warning before the option details; nearly every clause carries information. It is on the long side and could be split into short lines for scanability, but nothing is redundant filler.

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

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

No output schema exists, and the description covers what an agent needs for a live-account mutation: confirmation requirement, the default placement, batch semantics with per-post answers, and refusal cases. Nothing material is missing 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 coverage is 100%, so the baseline is 3; the description earns slightly above that by framing the postId-vs-postIds choice with a real use case ('a week being replanned') and by tying keepDay to the downstream re-scheduling workflow. It largely restates the schema's own semantics rather than adding format or constraint detail.

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

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

States a specific verb and resource ('Takes scheduled posts back to drafts so they no longer go out') and explicitly anchors it to a familiar UI action ('the same as the Unschedule button on the Plan page'). It is clearly distinguishable from delete_post (nothing is deleted), schedule_post, and approve_week, which are named as the re-scheduling path.

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 ('a week being replanned'), when-not-to-use (a post that already went out or is publishing right now is refused), the prerequisite ('ask the user first, then pass confirm: true'), and the follow-up alternatives (schedule_post or approve_week). No inference is required to pick this tool.

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

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

Adds substantial behavior beyond the annotations: partial-update semantics, logo constraints (public https, PNG/JPEG/WebP/SVG, ≤5MB), and the full lifecycle of clearFeedStyle including that cleared style is relearned on next 'My feed'/Refresh. The user-confirmation requirement is also disclosed.

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

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

Front-loaded with the core behavior in the first sentence and the rest ordered by field importance; nearly every clause adds actionable detail. It is a dense single block, though, and would scan better as bullets.

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 15-parameter mutation with no output schema, the description covers the risky and ambiguous fields plus the upload workflow and feed-style consequence. Remaining gaps (exact semantics of keyProducts replacement, priceOffer null-clearing) are already covered by schema descriptions.

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 27% schema coverage across 15 params, the description carries most of the burden and does so for the non-obvious ones: colorPalette 'name:#hex' format, typography intent and case-dropping rule, logoUrl sources, clearFeedStyle booleans. Several fields (name, industry, description, targetAudience, mood, visualElements) are only named, not explained, keeping it short of a 5.

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

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

Opens with a specific verb+resource ('Changes the brand profile') and immediately frames the patch semantics, so it is distinguishable from get_brand. It doesn't explicitly name the read counterpart as an alternative, which keeps it from a 5.

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

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

Gives solid when-to-use context ('for a rebrand or a correction', 'pass only the fields to change') and routes logo file uploads to create_upload_link + get_upload. It also instructs asking the user before calling. No explicit when-not-to-use/exclusion against siblings beyond the upload path.

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

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

Annotations only cover the generic safety profile (readOnly=false, idempotent=true, destructive=false), and the description goes far past them: edits to a scheduled post change what will publish, carousel slides cannot be replaced here and carousels are Instagram-only, video posts cannot go to X, and adding TikTok to a video post without a caption silently rewrites the caption and costs one credit. These are non-obvious side effects and cost implications that annotations cannot express.

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

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

The most important constraint (partial update) is front-loaded and every sentence carries a distinct rule, so there is little filler. The downside is that it is one dense paragraph of long compound sentences, where bullets for the carousel/video/TikTok branches would have been faster to parse for a 15-parameter tool.

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

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

For a 15-parameter mutation tool with no output schema, the description covers the failure modes an agent would otherwise hit: editability limits, carousel and video media rules, the confirm gate, the TikTok caption rewrite, and the create_upload_link path for local files. Nothing material 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?

Schema coverage is already 87%, so the baseline is 3; the description still adds real meaning for the ambiguous params — confirm as the user-approval gate, coverAt as the Instagram profile-grid cover second, uploadId as the create_upload_link handoff, and the caption/TikTok interaction. It does not add much for timeZone, youtubeTitle, tiktokSettings or aiGenerated, which are left to their already-detailed schema 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?

The first clause gives a specific verb and resource ("Edits an existing post's caption, picture or platforms") plus the partial-update rule ("pass only what changes"). It then explicitly separates itself from create_post, schedule_post and unschedule_post, so an agent can pick the right tool 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?

Routing is explicit: scheduledAt is for drafts sitting on a plan day, a scheduled post's time goes through schedule_post, unschedule_post returns it to draft, and published/live posts cannot be edited at all. It also states a hard prerequisite — ask the user first and pass confirm: true for scheduled posts — which is exactly the kind of conditional an agent needs before calling.

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