CreatorsCompanion

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds the real behavioral consequences: the previously active version is archived but reactivatable, library pillar tags follow the active version's pillars, and the call consumes no credits. These are non-obvious side effects an agent could not infer from the schema or 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?

Three tight sentences: effect first, then the archiving/pillar consequence, then routing to siblings and the return value. No filler, and the most important fact (what becomes active) is 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 one-parameter state-change tool with no output schema, the description covers the mutation's effect, its side effects on the prior version and pillar tags, cost, and the return payload (brief_id and active version). 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?

Schema coverage is 100% and the single brief_id parameter is already documented as coming from build_creator_brain or get_creator_brain. The description adds no format or constraint detail beyond that, so the schema carries the load and 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: makes a built Creator Brain version the active one used by every new draft. It is clearly distinguishable from build_creator_brain (creates) and get_creator_brain (reviews), both 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?

Gives an explicit sequencing rule ('Use it after reviewing a build with get_creator_brain') and names the alternative for the adjacent action ('to build a new version use build_creator_brain'). The agent knows both when to call it and when to call a sibling 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?

Annotations only declare non-read-only, non-destructive, closed-world; the description adds quota ('up to 10 documents'), duplicate rejection ('refuses a text that is already there'), cost ('Uses no credits'), and the write-then-read side effect. These are exactly the behaviors an agent cannot infer 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?

Purpose is front-loaded in the first clause and every following sentence carries distinct information (sequencing, alternative, limits, return values, cost). Slightly dense and comma-spliced, but no filler.

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

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

For a two-parameter write tool with no output schema, the description still discloses return values (document_id, read/ready flag), a hard cap of 10 documents, dedup behavior, and credit cost. 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 both parameters are already documented, but the description adds domain meaning by enumerating the content categories appropriate for 'text' (offers, story, results and proof, FAQ, audience notes). It stops short of adding format or length guidance beyond the schema's maxLength.

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: saves pasted creator text as a Creator Brain document and then reads it. It also names what the text should contain (offers, story, results/proof, FAQ, audience notes), which distinguishes it from build_creator_brain and update_creator_profile without needing the 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?

Explicit sequencing guidance: 'Use it before build_creator_brain, which turns the documents into the Brain', plus an explicit exclusion routing name/bio/niche to update_creator_profile. Both when-to-use and when-not-to-use are covered with named 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 only declare it is a non-destructive write; the description goes well beyond that by disclosing that the new version lands as a draft and never replaces the active one automatically. It adds rate limits, runtime, credit cost, and the conditional return shape, which is exactly the behavioral context an agent needs before spending 300 credits.

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?

Well front-loaded: purpose, then draft semantics, then alternatives, then timing and returns. No filler sentences, but the final sentence is a dense run-on covering two return paths plus cost and credits, and 'Takes 45 to 70 seconds' sits awkwardly beside 'ready within about 40 seconds', which is a mild internal inconsistency.

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 contract itself (brief_id plus draft, or brief_id to poll, plus cost and credits remaining) and covers the mutation's safety model. For a costly, rate-limited, long-running build tool, nothing an agent needs in order 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 description coverage is 100% and the 'fresh' parameter already carries a detailed explanation of the 10-minute rebuild window and 90-second in-flight behavior. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Builds the Creator Brain from the creator's documents and profile') and defines the artifact produced: a checked brief of identity, offers, proof, pillars and voice rules. It explicitly separates itself from siblings get_creator_brain and activate_creator_brain, so an agent can route correctly 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 sequencing rule ('Use it after add_brain_document') and names the alternatives with their selection conditions: get_creator_brain to read, activate_creator_brain to switch versions. It also states the practical constraints that shape when to call it (6 times a day, 45-70 seconds, 300 credits).

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds real context beyond them: irreversibility ("cannot be undone"), the return value ("Returns the deleted id"), and cost ("Uses no credits"). It stops short of error behavior (e.g., unknown id, items in use elsewhere), which keeps it at 4.

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

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

Four short sentences, each carrying distinct information: action, irreversibility, alternative routing, return/cost. The permanence warning is front-loaded 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?

For a single-parameter delete with no output schema, the description covers the destructive nature, the irreversibility, the fallback tool for drafts, the returned value, and credit cost. An agent has everything needed to call it correctly and safely.

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

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

Schema description coverage is 100% and the single id parameter is already documented as "The library item id from list_library." The description's "by its id" restates rather than enriches that, so the baseline 3 applies.

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

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

"Permanently deletes one item from the creator's library by its id" gives a specific verb (deletes), resource (library item), cardinality (one), and key (id). It also names the sibling it is not (discard_draft), so an agent can distinguish it 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?

The description explicitly routes usage: "Use it for saved items; for unsaved drafts use discard_draft." That is a concrete when-to-use plus a named alternative with the condition that selects it.

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

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

Annotations already flag destructiveHint=true, but the description adds consequences annotations cannot express: the action is not refunded, the draft cannot be recovered from chat, and no credits are consumed. It also discloses the return value, which matters since no 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?

Four short sentences, front-loaded with the action and consequence, then the alternative routing, then the return value. Every sentence carries information, though 'It is not refunded (it was delivered) and cannot be brought back from chat' slightly overlaps with the irreversibility theme in two clauses.

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

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

For a single-parameter destructive mutation with no output schema, the description covers purpose, sibling routing, irreversibility, cost, and return value. Nothing an agent needs to decide or call 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?

There is a single parameter at 100% schema coverage, and the schema already documents it as 'The draft id from generate_content or list_library.' The description adds nothing about the id format or sourcing beyond what the schema states, so the baseline applies.

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

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

The description names a specific verb and resource ('Removes a delivered draft... from their drafts') and immediately distinguishes the object class from library items, which is the nearest sibling. An agent can tell this apart from delete_library_item 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 states the when-to-use condition ('Use it for unsaved drafts') and names the explicit alternative for the other case ('for items in the library use delete_library_item'). That is a complete routing rule with no inference required.

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 a quota ('Up to 20 edits a day'), cost ('Uses no credits'), and asynchronous behavior ('Returns the new slides when the render finishes within about 40 seconds, otherwise a job_id for get_generation'). The one gap is that destructiveHint=true is never explained — nothing says the existing rendered slides are replaced or whether an edit can be reverted.

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

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

The description is front-loaded with what changes, immediately followed by routing guidance, then limits/return behavior. Every clause carries distinct information — no restatement of the title and no filler.

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

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

With no output schema, the description takes on the burden and does it: it explains the sync success return versus the job_id fallback and names the follow-up tools (get_generation, get_library_item). Rate limit, cost, and partial-update semantics ('unchanged fields stay as they are') round out what an agent needs to call this safely.

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

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

Schema description coverage is 100%, so every parameter including the nested slide fields already carries its own description and examples. The description only restates the field list at a high level and adds no format, constraints, or interaction rules beyond what the schema provides, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Changes the text on slides of a carousel draft') and enumerates the editable surface: headline, subheadline, body, CTA, caption, visual style, plus the re-render side effect. It is clearly separable from generate_content (creates new) and update_draft (text-only drafts).

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 states when to use it and when not to with named alternatives: 'Use it to fix a carousel instead of generating a new one; for text drafts use update_draft.' The agent does not have to open any schema to route between these three tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral facts beyond them: the call is free and nothing is charged, and it reports whether balance and the remaining daily limit cover the cost. It does not describe error behavior or rounding, keeping it below 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?

Two sentences, front-loaded with what is computed and what it is checked against, followed by the usage cue and the free-of-charge note. No filler or redundancy.

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

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

There is no output schema, so the description carries the return-value burden and does so: per-format cost, total cost, and coverage against balance and daily limit. Combined with the free-of-charge note and the 100%-covered input schema, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the format keys, variants, architectures, and the source_url link fee. The description only restates the per-format/total framing and adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (calculates) and resource (credits for a generate_content request), plus the scope: per format, in total, and against both balance and today's daily limit. It is clearly distinguishable from the sibling generate_content, which actually spends credits.

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

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

"Use it to answer what a format or a request costs" gives a clear usage context, and the pairing with generate_content is implicit in the wording. It stops short of an explicit when-not or a direct instruction to call this before generate_content, so it is not a full 5.

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

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

Goes well beyond annotations by disclosing cost model ('charged on its own', 'Uses credits (see get_account)'), an asynchronous fallback with a concrete latency window (~40 seconds) returning a job_id for get_competitor_results, and the qualitative output ('why each one fits'). These are exactly the operational traits an agent needs and that readOnlyHint/openWorldHint 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 compact sentences, front-loaded with the core purpose, then workflow, then cost/async behavior. Every sentence carries information not duplicated in schema or annotations; 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?

There is no output schema, and the description compensates by explaining both return shapes (results inline or a job_id to poll via get_competitor_results) and the latency threshold that selects between them. For a cost-bearing, open-world search tool, nothing critical is missing.

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

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

Schema description coverage is 100%, so focus, language and platform are already documented, including the enum values. The description only adds the constraint that a single call searches one platform, which is marginal but consistent with the schema baseline of 3.

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

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

States a specific verb and resource ('Finds creators in the same niche') plus the exact platform scope (Instagram, TikTok or YouTube) and the differentiating output ('why each one fits'), which separates it from siblings like find_viral_posts and get_creator_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 clear downstream context ('Use it to choose whom to follow with track_creator') and states the per-call constraint that each call covers one platform, so the agent knows to call it repeatedly per platform. It does not state when not to use it, e.g. versus find_viral_posts, so it stops short of full routing 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 only declare openWorldHint and destructiveHint=false, but the description adds the traits that actually matter here: a ~40 second sync budget that flips the response from inline posts to a job_id, and that the call consumes credits (pointing to get_account). The async/sync disclosure and credit cost are exactly the operational facts an agent needs before invoking a non-readOnly, open-world search.

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

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

Front-loaded with purpose, then usage routing, then operational behavior, then scoring semantics — a sensible order for scanning. It is dense and slightly overpacked into one block, and the "2 to 4 specific keywords" point duplicates the keywords field description, but no sentence is wasted.

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

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

With no output schema and 8 parameters including 4 enums, the description still covers return shape (post_key per post, or job_id), the meaning of viral_score and the 18+ outlier threshold, and credit consumption. Nothing blocking a correct first call 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 88%, so the schema does most of the work, but the description adds cross-parameter behavior the schema cannot express: keywords plus window defaults, and that omitting both falls back to the longest recent window (180d TikTok, 365d Instagram/YouTube). The keyword-quality advice (2 to 4 specific terms beat one broad niche) reinforces rather than extends the schema's field description, so it is useful but partly redundant.

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 ("Searches Instagram, TikTok or YouTube for posts that outperformed in the creator's niche") plus the value delivered ("what to borrow from each"). That framing separates it cleanly from list_my_posts, get_feed, and find_competitors 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 use case ("find ideas worth remaking") and names the follow-on siblings with their distinct roles: save_inspiration stores, generate_content remix rewrites in the creator's voice. It also routes the async case to get_viral_results and the display case to show_posts, so the agent knows which tool to pick at each step.

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 openWorld/readOnly/destructive, so the description carries most of the weight and does it well: it discloses credit consumption per draft, a small link fee, its absence on remix, a free dedup path for identical requests, and a ~40 second sync cutoff that falls back to a job_id for get_generation. The one gap is that the 40-second boundary is hedged as "about", leaving timeout behavior imprecise, and no pagination/output-shape detail is given (though none is needed for a generation 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?

Front-loaded with the capability, then routing, then cost and async behavior – a sensible information hierarchy with no filler sentences. It is dense and runs long in a single paragraph, which slightly hurts scanability for a tool with six distinct modes, but nothing is redundant.

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

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

For a complex, nested, multi-mode generation tool with no output schema, the description covers all three input modes, the nested remix keying options, cost mechanics, dedup behavior, and the async handoff to get_generation. The "it reads the creator's profile, voice examples and Creator Brain itself, so nothing needs to be looked up first" line removes the most likely agent misstep of calling get_voice or get_creator_brain first.

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 baseline is 3, but the description adds real meaning the schema cannot: it states the implicit prerequisite for remix (post must come from list_inspiration, find_viral_posts or get_creator_report), ties source_url to a fee and remix to none, and frames fresh as re-running a request from "the last few minutes" in cost terms. It does not explain the carousel_style house-style fallback beyond the schema, but overall it beats the baseline.

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

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

"Writes drafts in the creator's saved voice, in one or more formats ... from an idea, a link, or a post to remix" names the verb, the resource, the input modes, and the output artifact in one sentence. The format list (Reels/TikTok scripts, LinkedIn, X, newsletter, YouTube, carousel) plus the explicit contrast with estimate_cost and get_generation makes it unmistakable against siblings.

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

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

Routes the agent explicitly: remix for a post from list_inspiration, find_viral_posts or get_creator_report; fresh for new versions of a recent request; estimate_cost to see the total first. These are concrete when-to-use conditions tied to named sibling tools, not inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The one genuine addition is 'Free.' — it tells the agent the call consumes no credits, which is not in any structured field and matters in a credit-metered product. Nothing is said about auth requirements or whether the balance is real-time versus cached.

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 sentence, verb first, with the payload enumerated and the cost caveat placed at the end where it reads as a qualifier. No filler words and nothing repeated from the title.

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

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

With no output schema in place, the description does the right thing by listing the returned fields, and with zero parameters and full annotation coverage there is little else required. The remaining gap is minor: it does not clarify whether 'daily credit limit' is a cap, remaining allowance, or reset window.

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 the schema baseline of 4 applies and there is nothing for the description to compensate for. It correctly uses the space to describe the response payload instead.

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') plus the resource and enumerates exactly what comes back: plan, credit balance, daily credit limit, and per-format/per-action credit prices. That is far more concrete than the title 'Get account'. It stops short of naming the adjacent siblings (get_credit_history, estimate_cost, get_creator_profile), so an agent must infer the boundary itself.

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

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

Usage is only implied: the closing 'Free.' signals there is no credit cost to calling it, which nudges an agent to check balance/pricing before paid operations. There is no explicit statement of when to use this versus get_credit_history (past transactions) or estimate_cost (pre-flight cost projection), which are the obvious confusable 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/openWorld=false/no destruction, and the description adds context they cannot: the metric window (30 days), the cost profile ("Uses no credits"), the return structure (accounts[], top_posts[], bottom_posts[]), and the behavior when no account is connected.

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 what is returned, then usage and alternatives, then edge case and cost. Every clause carries distinct information (metrics, differentiation, output shape, credit cost) with no filler.

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

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

With no output schema, the description compensates by naming the returned keys and the empty-state message, and it flags the no-credit cost for a read-heavy analytics call. An agent has everything needed to call it correctly and know what to expect.

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

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

Schema description coverage is 100% and the single `limit` parameter is fully documented in-schema, so the baseline is 3. The description only implies the limit through "strongest and weakest recent posts" without stating count or the 1–10 cap, adding no real meaning beyond the schema.

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

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

States a specific verb and resource (returns the creator's own analytics), enumerates exactly what is measured (followers, posts, views per account, 30-day change, strongest/weakest posts), and explicitly contrasts with tracked-competitor data in get_feed and get_creator_report.

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

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

Gives explicit when-to-use guidance ("plan from what already works for this creator") and routes the agent away to named alternatives for competitor data. It also covers the empty-state case (no account connected returns where to connect one), so nothing is left to inference.

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

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

Annotations already cover read-only, non-destructive, open-world behavior, and the description adds real value on top: default result count of 10, closest-match ordering, the exact fields returned, and the important cost trait "Uses no credits." It does not cover error cases such as an invalid or still-running job_id, which keeps it from a 5.

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

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

Three sentences, front-loaded with what is returned and the job_id default, followed by usage and return details. Dense but every sentence carries information; the return-field enumeration slightly bloats the middle sentence but is useful given no 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?

With no output schema, the description must carry return semantics, and it does: field list, count, and ordering. For a simple two-parameter read tool, the remaining omission (error behavior for missing/incomplete jobs) is minor.

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 the schema does not: omitting job_id falls back to the latest search, which is a behavioral parameter semantic not documented in the schema. It also restates limit's default and ordering, which is redundant but harmless.

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 (creators of a find_competitors search), and explicitly ties the job_id to the find_competitors sibling, making the producer/consumer split between the two tools obvious. It also names track_creator in describing the returned handle/platform, further situating the tool in the workflow.

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

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

"Use it to check on a search that was still running" gives a clear triggering condition, and referencing find_competitors implies the prerequisite call. It lacks an explicit exclusion (e.g., what to do if results were already returned inline) but the context 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?

Beyond the readOnlyHint/destructiveHint annotations, the description discloses the cost profile ('Uses no credits'), the returned fields (brief_id, version, status) and the full status vocabulary (building, draft, active, archived, failed), plus the fact that the Brain is derived from documents. That is real context an agent needs for a review-then-activate workflow.

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 purpose before the alternative-tool routing, and every clause maps to something an agent needs (contents, default behavior, workflow, return shape, cost). The first sentence is dense with an enumeration that could be trimmed, but nothing is redundant.

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

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

There is no output schema, but the description compensates by naming the key returned fields and status values. For a single optional-parameter read tool, the description covers contents, defaults, workflow position, return shape and cost — nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns a step up by explaining the meaning of the optional brief_id in workflow terms — it selects a pending build surfaced by build_creator_brain rather than the active Brain, and is the input to a subsequent activate_creator_brain 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 ('Shows the creator's Creator Brain') and then enumerates exactly what the brief contains — identity, audience, offers, proof, stories, content pillars with pillar ids, voice rules, status, source documents. It explicitly contrasts with the sibling get_creator_profile, so an agent can distinguish 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?

Gives explicit routing rules: omit brief_id to read the active Brain; pass the brief_id from build_creator_brain to review a new build before calling activate_creator_brain; use get_creator_profile for profile basics. Both the when-to-use and the when-to-use-something-else conditions are named.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the credit cost ('Uses no credits') and the return shape ('Returns the fields and missing[]'), which annotations do not convey. It stops short of describing error or empty-profile behavior, so it is 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?

Front-loaded with what the tool shows, then alternatives, then return shape and cost. Every sentence carries information, though the middle sentence is a long run-on chaining three sibling references that could be split for readability.

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

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

With no output schema, the description must convey return values, and it does name the fields and missing[]. For a zero-parameter read tool with full annotation coverage this is nearly complete; only the exact structure of the returned object is left implicit.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description correctly spends no words on inputs and instead describes outputs.

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 the creator's profile basics') and enumerates the exact fields returned: name, bio, niche, target audience, content language, social handles, missing fields, and a Creator Brain line. This is clearly distinguishable from get_voice, get_creator_brain, and get_started, which are 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?

Explicitly routes the agent: use this to check or fix basics with update_creator_profile, voice examples live in get_voice, the full Brain in get_creator_brain, and get_started gives the whole setup in one call. Both the when-to-use and the alternatives are stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds genuinely new context with 'Uses no credits,' which matters for cost-aware tool selection. It also discloses the response shape without a formal output schema, though it says nothing about size limits or latency of a full script fetch.

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 the main behavior front-loaded and the alternative/sibling noted before the return-shape detail. The parenthetical asides about save_inspiration and generate_content remix are useful but slightly cluttered.

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 nested objects, the description carries the return-value burden and does it: it names creator, top_posts[] and post, and explains the post_id mode returns the full script. It also names downstream consumers of post_id, which is exactly what an agent needs to chain calls.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds the important behavioral distinction that post_id switches the return mode from creator+top_posts to a single full post with script. It leaves 'limit' to the schema, which documents it adequately.

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 ('Returns a tracked creator's analysis') and enumerates the concrete payload: content pillars, funnel mix, top posts with hooks and topics. It also states the alternate mode when post_id is supplied, so an agent can tell this apart from get_feed without opening a schema.

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

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

Explicitly routes the agent: use post_id to drill into one post, use get_feed to cover every tracked creator at once. The prerequisite that the creator must already be tracked is implied by 'tracked creator' and supplied in the schema, but there is no explicit 'do not use for untracked creators' statement.

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/non-destructive annotations, the description discloses ordering (newest first), the hard cap (up to 50, no pagination path), the return shape field by field (label, signed amount, reason, balance after, date), and that the call is free ("Uses no credits"). Those are exactly the behavioral facts an agent needs 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?

Purpose and scope are front-loaded, the sibling routing follows, and the return details and zero-cost note close it out. Every sentence carries information; the short final sentence "Uses no credits." is a well-placed, high-value fact rather than filler.

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

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

With one optional parameter, no output schema, and annotations covering the safety profile, the description fills the remaining gaps: what each returned record contains, how many, in what order, and that the call costs nothing. 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?

Schema description coverage is 100% and the limit property already documents the default of 20 and the maximum of 50. The description only reinforces the cap and ordering, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource ("Lists the creator's latest credit movements") and immediately enumerates the movement types covered: usage, refunds from failed runs, purchases and grants. It also names the sibling to use for the narrower need ("for the current balance alone, use get_account"), so an agent can separate it from get_account 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 answer where credits went" gives the triggering question, and the follow-up clause names the explicit alternative (get_account) with the condition that selects it. This is a clear when-to-use / when-to-use-something-else pair with no inference required.

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 read-only, open-world and non-destructive behavior, but the description adds genuinely new traits: results are sorted by performance, and the call costs no credits. What's missing is any note on recency window ('lately' is undefined) or result volume behavior beyond the limit parameter.

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 return shape and immediately followed by the differentiator. The final sentence packs return field details and three downstream tool hints together, which is dense but each fragment carries actionable information.

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

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

With no output schema, the description does the work of describing the return ('posts[] with post_id', plus hook, topic, pillar, funnel stage and numbers), which is adequate for a two-optional-parameter read tool. The underspecified recency window ('lately') is the only notable gap.

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

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

Schema description coverage is 100%, so both limit (default 8, max 50) and platform (enum of instagram/tiktok/youtube) are already fully documented. The description adds no additional meaning about these parameters, 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 ('Returns what every tracked creator posted lately'), the ordering ('highest performing first'), and the fields carried per post. It explicitly contrasts with the sibling get_creator_report (one creator in depth, full script), so the agent can tell the two apart 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 an explicit when-to-use ('plan from what works across all tracked creators') and names the alternative with its distinguishing condition ('get_creator_report covers one creator in depth and returns a post's full script'). It also routes downstream: post_id feeds save_inspiration, generate_content remix, and show_posts.

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 destructiveHint=false, and the description adds genuinely new behavioral facts: it consumes no credits and reports job status (running or done) plus remaining credits. It stops short of describing pagination or error behavior for an unknown job_id, 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?

Three short sentences, front-loaded with the return content, then the usage rule, then the cost note. Every sentence carries distinct information with no repetition of the title.

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

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

With no output schema, the description compensates by naming the returned fields and pointing to generate_content for the exact shape. For a single-parameter read tool with annotations covering safety, nothing an agent needs 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 schema already documents job_id with an example, so the description only adds that the id can originate from edit_carousel as well as generate_content. That is a marginal gain over the structured field, matching the baseline 3.

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

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

States a specific verb and resource ('Returns the drafts of a generate_content or edit_carousel job by its job_id') and enumerates what comes back (status, cost, credits left), which clearly separates it from get_library_item and the generate/edit tools.

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

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

Explicitly says when to use it ('to check on a job that was still running') and names the alternative for the other case ('for one saved item use get_library_item'), so the routing decision is unambiguous.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds value beyond them: it discloses the cost model ('Uses no credits') and that the result is tagged with kind library or draft. It does not cover failure behavior for a missing or cross-account id, which keeps it from a 5.

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

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

Three short sentences, front-loaded with the operation and return payload before the usage hint. The clause 'Returns item, with kind library or draft' is slightly clipped/awkward but carries real information, so there is little waste.

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

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

With no output schema, the description correctly takes on the burden of describing return fields, naming the major content attributes and the kind discriminator. For a one-parameter read tool this is nearly complete; only error/not-found and draft-vs-item resolution are 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 coverage is 100% for the single id parameter, so the schema already documents it fully. The description reinforces that the id can address either a library item or a draft, but adds no format, sourcing, or lookup guidance 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 and resource ('Returns one library item or draft in full by its id') and immediately enumerates the payload (text, hooks, call to action, on-screen hook, caption, notes, content pillar, funnel stage), so the agent knows exactly what it gets. This is clearly distinguishable from list_library (paged summaries) and update_library_item (mutation).

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 usage context: call it after list_library or generate_content when the full piece is needed, which implicitly routes list-style needs elsewhere. It does not state explicit exclusions (e.g., when to use get_generation instead of fetching a draft), so it falls short of a full when/when-not statement.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral context beyond that: it saves nothing and consumes no credits — critical for an agent that might otherwise avoid calling an aggregate tool to save quota. It stops short of describing response shape beyond the top-level keys, but that is a minor gap.

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

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

It is front-loaded with what is returned, then when to use, then alternatives, then the return keys and cost — a logical order with no filler sentences. The long enumeration of payload contents is dense but each item helps an agent decide whether one call replaces several sibling calls; the closing 'Uses no credits' is slightly redundant with the earlier credit mention.

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

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

With no output schema, the description carries the burden of telling the agent what comes back, and it does so by listing the top-level keys (account, profile, voice, creator_brain, library, research, next_steps). Combined with the cost and no-write disclosure, an agent has everything needed to call this correctly and interpret 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?

The tool takes zero parameters, so the baseline of 4 applies; there is no parameter meaning to add or omit. The description correctly spends its words on scope and output instead.

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 with a specific verb and resource — it shows who the creator is and what is set up — and then enumerates the exact payload (plan, credits, profile field gaps, voice examples and CTAs per format, Creator Brain status, library items, drafts, tracked creators, next-step suggestions). This makes it unmistakably distinct from the many sibling get_* tools.

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

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

It names explicit triggers (creator is new, asks what CreatorsCompanion can do, setup is unclear) and explicit non-triggers (not needed before writing, because generate_content and the other tools read profile and voice on their own). It also routes to narrower alternatives: get_account for balance alone, get_creator_profile for profile fields alone.

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 annotations by disclosing the credit cost model and its conditionality ("uses credits only when the transcript is not stored yet"), which is exactly the kind of side effect an agent needs before calling a tool annotated readOnlyHint=false. It also states the return payload (text and language). It does not cover latency or whether a stored transcript is cached per-post, but nothing contradicts 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?

Front-loads the core action, then routing, then the misuse case, then return values and cost. Every sentence carries distinct information; no restatement of the title or name.

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 names the return payload (text plus language); with three optional, mutually-exclusive-looking params it explains where each key comes from and what to do instead for links. The credit disclosure closes the remaining question an agent would have before invoking it.

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 baseline is 3, but the description adds genuine meaning beyond the schema: each key is tied to its originating tool (find_viral_posts, list_inspiration), and it clarifies what the parameters are NOT ("It takes those keys, not a link"). That negative constraint is not expressible in the schema properties.

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 spoken words of a post") and immediately names the two key shapes it accepts and the siblings that produce them. An agent can distinguish it from generate_content's source_url path and from get_generation 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 when-to-use ("read a post before remixing it with generate_content") and explicit when-not-to-use with the alternative named ("for a pasted link, generate_content with source_url reads the video itself"). The routing decision between the two tools is fully specified.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds non-annotation behavior worth knowing: it falls back to the latest search when job_id is omitted, it costs no credits, and it describes the resulting posts[] shape and viral_score calculation.

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 dense and front-loaded: purpose first, then the fallback rule, then return shape and scoring semantics. The clause 'Returns posts[] with post_key, for get_transcript, save_inspiration and generate_content remix' is compressed to the point of mild ambiguity, but no sentence is wasted.

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

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

With no output schema, the description carries the burden of explaining returns and does so, including the viral_score scale and the 18-point outlier threshold. It is silent on pagination or result-capping behavior, which matters given a load_more_viral sibling exists.

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 job_id field is already documented as coming from find_viral_posts, giving a baseline of 3. The description does add one piece of meaning beyond the schema — that omitting job_id returns the latest search — but gives no detail on identifier format or errors for an unknown job_id.

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

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

The description opens with a specific verb and resource ('Returns the posts of a find_viral_posts search') and explicitly ties itself to the sibling that produces the job_id, so an agent can distinguish it from find_viral_posts and load_more_viral 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?

It states a clear use case ('Use it to check on a search that was still running') and names downstream tools that consume the returned post_key (get_transcript, save_inspiration, generate_content). It does not explicitly say when not to use it versus load_more_viral, which is the closest ambiguity.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered; the description adds genuinely new behavior: full texts for a single format versus a short preview of all formats when format is omitted, and that the call consumes no credits. It does not mention ordering, truncation limits, or error behavior for an unsupported format, so it falls just short of exhaustive.

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 purpose, then routing guidance, then return shape and cost. The opening sentence is long, carrying a parenthetical format list and a four-way provenance list, but every clause conveys information an agent needs; no filler sentences.

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

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

For a single-optional-parameter read tool with no output schema, the description covers what it returns (full text vs. preview), what it costs (no credits), where the data comes from, and which siblings to prefer. Nothing an agent needs in order 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% and the enum is self-documenting, so the baseline would be 3. The description earns more by explaining the semantic effect of omitting the optional format parameter (preview of every format rather than full texts), which the schema does not convey.

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 the voice examples and calls to action the writer imitates') and enumerates the supported formats, plus the provenance dimension (creator-written, imported, edited, starter text). It also explicitly disambiguates from get_creator_profile, which covers name, bio and niche.

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 guidance ('Use it before update_voice_examples or import_voice_from_posts') and names the sibling to use instead for a different need (get_creator_profile). Both the alternative and the condition that selects it are 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?

Goes well past the destructiveHint/openWorldHint annotations by naming exactly what is destroyed ("overwrites example slots 1 onward", "clears leftover starter text"), what side effect occurs (the handle is saved to the profile), the rate limit (10/day), and the price (100 credits). That is the full behavioral profile an agent needs before a costly, 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?

Front-loaded with the operation, then side effects, then the alternative and cost. Every clause carries information, but the paragraph is dense and chains many clauses into a single flow, which makes scanning slightly harder than a short bulleted ordering would.

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 enumerates the return payload (slots overwritten and cleared, failed posts, cost, credits left). Combined with cost, rate limit and side effects, nothing material is missing for a destructive, credit-consuming operation.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds rationale the schema lacks, notably the warning that passing a handle saves it to the profile and therefore must be the creator's own, plus the credit implication of the 5-post cap. The ordering semantics of posts are already in the schema, so this is reinforcement rather than new meaning.

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

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

"Turns up to 5 of the creator's own posts into voice examples" states a specific verb, resource and scope, and immediately disambiguates from update_voice_examples and list_my_posts by naming both. An agent can route this 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 prerequisite ("Use list_my_posts first to get the urls and texts") and an explicit alternative with a selection condition ("for pasted text use update_voice_examples (free)"). It also constrains inputs ("pass only the creator's own handle"), covering when-not as well as when.

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, non-destructive, closed-world), so the marginal bar is met by stating the cost behavior ('Free') and previewing the payload: a tagline per architecture, plus fit guidance when a format is supplied. It stops short of saying what is returned when format is omitted (all formats grouped, presumably) or how many entries to expect.

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 sentence plus a one-word fragment, no filler, and the core purpose is front-loaded. The semicolon-clause and trailing 'Free.' are terse to the point of being cryptic on first read, but 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 single optional-parameter read-only list with no output schema, the description supplies enough: what the items are, what each item carries (tagline, fit guidance), and that it costs nothing. Only the no-format case is left implicit.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: passing format not only filters results but changes the response to include when each architecture fits. That behavioral difference is not in the schema's 'Only this format' 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?

Specific verb + resource, and it de-jargons the term by defining architectures as 'the script structures generate_content can use', which an agent could not infer from the name alone. It ties itself to the generate_content workflow but does not explicitly distinguish itself from other list_* siblings such as list_carousel_styles.

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?

'Free.' is a real usage signal — with estimate_cost and get_credit_history among siblings, the agent knows it can call this speculatively without burning credits. The 'architectures generate_content can use' phrasing implies the call-before-generate workflow, though the when-to-use step is never stated outright and no exclusions are given.

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

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

Annotations already declare readOnlyHint and non-destructive behavior, and the description adds two facts those annotations cannot convey: the call consumes no credits and the response is a static list with a preview per entry. It stops short of noting whether the list is cacheable or user-specific, which keeps it from a 5.

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

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

Two sentences, both front-loaded: purpose and field inventory first, then the workflow instruction and the cost note. No sentence is redundant, and the return-field list replaces the need for a separate 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?

There is no output schema, but the description enumerates the returned styles[] fields (slug, name, description, preview_url, requires_portrait), so the agent knows exactly what comes back. For a zero-parameter read tool with annotations covering safety, nothing material is missing.

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

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

With zero input parameters, the baseline is already high. The description still adds useful meaning by explaining that the returned 'slug' is what feeds the carousel_style parameter in sibling tools, connecting this tool's output to another tool's input.

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 with a specific verb and resource ('Lists the visual styles an Instagram carousel can be drawn in') and immediately enumerates what each entry carries. This is clearly distinct from siblings like list_architectures or list_inspiration, which an agent could otherwise confuse with it.

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 states exactly when to call it: 'before generate_content or edit_carousel to pick carousel_style,' naming both downstream siblings. This is an explicit ordering constraint that removes any need for the agent to infer the workflow.

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, destructiveHint=false and openWorldHint=true, so safety is covered; the description still adds real context: ordering (newest first), the returned fields (numbers, hook, note, status), the status vocabulary, the saved_key for chaining, and the cost profile ("Uses no credits"). It stops short of saying whether results are capped or how to page beyond the limit, which is the one behavioral gap.

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

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

A single dense sentence, front-loaded with the resource and scope before the routing advice and return details. Almost every clause earns its place, though the embedded field list (numbers, hook, note, status) makes it slightly packed and harder to scan than two shorter sentences would 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?

With only 2 optional params, no output schema and no nesting, the description covers what the tool does, when to use it, what it returns and what it costs — more than enough for a simple read tool. The only omission is limit/pagination behavior, which matters slightly given the maximum of 50.

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%: status carries its own description while limit has none. The description compensates for the status enum by mapping values to human labels (saved = To remake, used, archived), but says nothing about limit — no hint that it caps at 50 or what happens when more items exist. Partial compensation justifies the baseline 3.

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

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

States a specific verb and resource ("Lists the posts the creator saved for inspiration") plus the source (viral searches, tracked creators), and explicitly separates it from the lookalike sibling list_library ("the creator's own saved drafts are in list_library"). An agent can distinguish it from list_library, get_library_item and find_viral_posts 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 an explicit use case ("Use it to pick a post to read or remix") and names the downstream tools it feeds (get_transcript, generate_content via saved_key). It also names the exclusion: own saved drafts live in list_library. When-to-use, what-to-do-next and the alternative are all present.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description still adds context the annotations cannot express: 'Uses no credits' (important for an agent that calls estimate_cost elsewhere) and 'Returns items[] with the id to pass on', which tells the caller what to do with the result. It does not mention pagination limits or totals, which keeps it off a 5.

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

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

Front-loaded with what the tool returns before the filter options, and every clause carries information (ordering, preview fields, filters, sibling alternative, return shape, cost). The middle sentence is dense and slightly run-on ('to plan a mix or find a piece'), but no sentence 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?

With no output schema, the description correctly compensates by stating the return shape ('items[] with the id to pass on') and per-item contents. For an 8-parameter, paginated list tool it covers the essentials; only pagination/total-count behaviour and the drafts-vs-library distinction (left to the schema's kind description) are 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 88%, so the schema already documents kind, text, offset, status, platform, pillar_id and funnel_stage, including the enum meanings. The description only restates the filter dimensions generically ('status, pillar, funnel stage, platform or words in the title') without adding format, defaults or edge-case behaviour beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Lists the creator's saved library items and delivered drafts') and immediately scopes it with ordering ('newest first') and returned fields (preview, pillar, funnel stage). It also names the sibling it is not ('get_library_item returns one in full'), so an agent can choose between listing and fetching 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 a concrete motivation for the tool ('to plan a mix or find a piece') and the available filter axes, plus an explicit redirect to get_library_item for full content. What is missing is an explicit when-not (e.g. use find_competitors or list_my_posts instead when the items aren't the creator's own library), so it stops just short of full routing 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 cover the read-only, open-world, non-destructive profile, and the description adds substantial context beyond them: a 30/day rate limit, no credit cost, pagination via next_cursor, and the fact that video captions are truncated to 200 characters because the import transcribes them. That truncation note is exactly the kind of non-obvious behavior an agent 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?

Front-loaded with purpose and the sibling routing, then the operational details. It is dense — a single long sentence carries the return shape and truncation caveat — but no sentence is filler.

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

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

There is no output schema, and the description compensates by describing the returned fields (url, kind, date, text) and next_cursor. Combined with the rate limit and credit note, an agent has everything needed to call and consume 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that cursor yields older posts and that url and text are the fields to hand to import_voice_from_posts. It does not restate the handle default, which the schema already 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 and resource ('Lists the creator's own recent posts') and enumerates the five supported platforms. It also distinguishes itself from siblings by naming import_voice_from_posts and the research tools, so an agent can route correctly 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 explicit sequencing ('Use it before import_voice_from_posts') and an explicit exclusion with the alternative ('to look at other creators' posts use the research tools'). The 30-per-day limit is also stated, which is actionable usage context.

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 readOnlyHint and destructiveHint=false, so the description's added value is the cost information ('uses no credits') and the fact it returns the slot budget (slots used and limit), which is real operational context beyond the schema. It stops short of describing ordering or whether results are cached or limited, so not a full 5.

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

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

Three short sentences, front-loaded with what is returned, then routing guidance, then return/cost detail. Every sentence carries distinct information with no restatement of the title.

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

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

No output schema exists, and the description compensates by describing the return shape (creators[] with id, slots used, limit). For a no-parameter read tool with annotations covering safety, 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?

There are zero parameters, so per the baseline this scores 4; the description correctly notes that it returns creators[] with their id, which is the only 'input-adjacent' semantic an agent needs before calling it.

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

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

States a concrete verb and resource (lists the creators the creator tracks) plus the payload contents: scan status, content pillars, this month's numbers. It is immediately distinguishable from siblings like get_creator_report or untrack_creator, which operate on a single already-chosen creator.

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

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

Explicitly routes the agent: use this to pick whom to study via get_creator_report, or which slot to free via untrack_creator. That both names the alternatives and the conditions that select them, so the agent never has to infer the workflow.

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 declare non-readonly, non-destructive, open-world): it discloses credit consumption per page, a billing exception when a page adds no new posts, and async behavior where the call may return a job_id while loading instead of results. That is exactly the cost/async context an agent needs before calling a paid, non-idempotent-in-effect tool.

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

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

Front-loads the action and scope in the first sentence, then layers prerequisite, return shape, cost, and metric semantics. The closing viral_score definition is tangential to invoking this tool and could be trimmed, but every other clause earns its place.

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

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

With no output schema, the description takes on the burden of describing return values and does so ('the whole result list with new_posts ... or the job_id while it loads'), plus cost implications and the meaning of viral_score. Nothing material is missing for an agent to call and interpret 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?

Schema coverage is 100% and the single job_id parameter is fully documented as coming from find_viral_posts, matching the description. The description adds no format, lifetime, or reuse guidance for job_id beyond what the schema already says, so baseline 3 applies.

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

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

States a specific verb and resource ('Adds the next page of results') scoped to a named sibling operation ('a finished find_viral_posts search'), which separates it cleanly from find_viral_posts (start a search) and get_viral_results (retrieve results). An agent can pick this tool 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 trigger is given: 'Use it when the first page was not enough,' and the 'finished ... search' qualifier rules out calling it on an in-flight job. It does not explicitly compare against get_viral_results or state what to do once pages are exhausted, so it stops short of full when/when-not routing.

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

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

Annotations already declare non-destructive, non-read-only, open-world behavior, so the description's added context is what matters: it discloses that the call consumes no credits, that it also mutates status of already-saved posts, and that it returns the saved post including saved_key. It stops short of covering failure modes (e.g. invalid or expired job_id/post_key) or idempotency, which is why it is 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?

Front-loaded with the core action and the input variants, then the routing rule, then the return value and cost. Dense and largely waste-free, though the first sentence is long enough that the three input modes would read better as a short list than as a comma-chained clause.

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

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

For a mutation tool with no output schema and no required parameters, the description covers source inputs, alternative tool, status semantics, return value (saved_key) and cost. Nothing an agent needs in order to call this correctly and interpret the result 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 baseline would be 3, but the description adds genuine meaning the schema does not: it establishes the mutual exclusivity of the input paths (job_id + post_key OR post_id OR saved_key) and frames saved_key as the status/note-change handle. That resolves the ambiguity created by six optional parameters with zero required fields.

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 ('Saves a post to the creator's inspiration list') and enumerates the two input modes (viral search via job_id/post_key, tracked creator via post_id) plus the status-transition mode. An agent can distinguish it from save_to_library, list_inspiration and unsave_inspiration 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 an explicit when-to-use rule ('posts to come back to or remix later') and an explicit exclusion with the named alternative ('drafts and finished pieces go to save_to_library instead'). It also names the downstream tools the result feeds (get_transcript, generate_content), so the agent knows the follow-on 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?

Beyond the annotations, the description discloses that the tool returns the new library item id, uses no credits, and triggers automatic content-pillar and funnel-stage tagging within a minute. It also clarifies that the selected hook becomes the chosen hook and comes first, which is useful behavioral context for a non-destructive 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?

The description is compact and front-loaded, covering the two save paths before hook behavior, auto-tagging, the alternative tool, return value, and cost. Every sentence contributes useful information without redundancy.

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 five-parameter tool with no output schema, the description supplies the missing operational context: save modes, hook selection behavior, automatic tagging, return value, and credit cost. An agent has enough information to call it correctly without opening the schema.

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

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

Although the schema has full parameter descriptions, the tool description adds meaningful semantics: draft_id and title/text/platform are alternative save modes, and hook may be either a number or text and affects ordering. This goes beyond the structured schema by explaining relationships between parameters.

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

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

The description names a specific verb and resource: saving a delivered draft or new creator text to the library. It clearly distinguishes the two save modes by draft_id versus title/text/platform, and separates itself from update_library_item, which edits library tags manually.

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 explicitly explains when to use each mode: pass draft_id to save a delivered draft, or provide title, text, and platform to save new text. It also tells the agent when to use update_library_item instead for manual tag changes.

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 destructiveHint=false, so the description's real contribution is the partial-success behavior: it returns the posts it found (up to 12) plus the references it could not find. It also discloses that the call uses no credits, which is material in a credit-metered product. It stops short of describing ordering or error semantics beyond the missing-reference case.

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 card contents and then the invocation contract. Every clause carries information the agent would otherwise have to guess: sources, key pairing, the 12-item cap, partial-failure handling, and credit 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?

There is no output schema, so the description must explain the return value itself, and it does: found posts in the given order plus unfound references. Combined with the 12-item cap, credit note, and source-to-parameter mapping, 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 100%, so the baseline is 3, but the description adds the non-obvious pairing constraint that post_keys should be sent together with their originating job_id and that job_id defaults to the latest search. That relationship is not spelled out in the schema and prevents silently rendering keys from the wrong search.

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 ("Displays chosen posts as cards in the chat") and then enumerates exactly what each card contains (platform, handle, views, outperformance, hook/caption, Remake button). That level of specificity makes it unmistakable against siblings like list_my_posts or get_viral_results, which retrieve rather than render.

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 exact upstream tools that produce valid inputs (find_viral_posts, get_viral_results, load_more_viral, get_feed, get_creator_report) and maps which key type comes from which source. There are no explicit exclusions or when-not-to-use cases, but the routing is unusually concrete for this dimension.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing a daily quota ('10 account syncs a day'), a deduplication window ('an account synced in the last 10 minutes is handed back without using one'), a latency boundary ('about 40 seconds'), and the async fallback contract ('otherwise a job_id: call again with job_id to check'). It also states the cost model ('Uses no credits'), which is behavior no structured field conveys.

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 paragraph is ordered deliberately: what it does, when to use it, when not to, scope, quota, return behavior, cost. Every sentence carries distinct operational information — nothing restates the title or the schema, and the two most decision-critical facts (the alternative tool and the quota) are placed early.

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, and the description compensates by describing both return modes — per-account results on completion and a job_id for the async path — plus the cost and quota implications of calling it. Combined with three fully documented, all-optional parameters, an agent has everything needed to invoke it correctly on the first try.

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: it explains the scope default ('Syncs every connected account, or one by account_id or platform') and frames job_id as a re-entry mode rather than a new sync. The only thing left implicit is how platform and account_id interact if both are supplied.

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 — 'Refreshes the creator's own connected accounts (followers, views and recent posts)' — and immediately anchors it to a known analog ('the same sync as Refresh on the website's Analytics page'). It explicitly separates itself from get_analytics, so an agent can distinguish it from the closest sibling 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 both the trigger ('when the creator asks to update their numbers or get_analytics shows an old last_synced day') and the exclusion ('to read the numbers use get_analytics'). It also routes the out-of-scope case away from the tool entirely: 'Connecting a new account happens on the website.' Nothing about 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?

Annotations declare a non-destructive, open-world write, and the description adds substantial context beyond them: it consumes credits per new scan, a recently-scanned creator is free, the first scan takes minutes, and slots are limited so untracking frees one. This cost/latency/idempotency detail is exactly what annotations cannot express.

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

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

Front-loaded with the action and scope, then alternatives, then return/latency, then cost. Sentences are dense with semicolons but each carries distinct information; only the credit-cost sentence overlaps slightly with the 'see get_account' pointer.

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

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

With no output schema, the description steps in to describe returns (per-creator outcome, total cost, credits left) and the async follow-up path (get_creator_report after a few minutes). For a mutating, credit-consuming, open-world tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is 75% and the schema already documents handle format, the 5-item cap and the platform enum, so the description largely restates it. It does not clarify the singular 'creator'+'platform' vs. 'creators' array relationship or what the 'label' enum (competitor/inspiration) changes, leaving meaningful ambiguity unaddressed.

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 ... creators ... to the creator's tracked list and scans their posts'), plus scope (up to 5) and supported platforms. It is clearly distinguishable from siblings like list_tracked_creators and get_creator_report, which it names.

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

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

Explicitly says when to use it ('for competitors or inspiration found with find_competitors') and routes to alternatives: untrack_creator to free a slot, list_tracked_creators to see the list, get_creator_report for the follow-up report, get_account for credit balance. No inference is required.

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, but the description goes well beyond them: it names the side effect (the post disappears from list_inspiration), discloses that the removal is recoverable via the website, states the return value (the removed saved_key), and confirms no credits are consumed. Reversibility is exactly the context an agent needs before invoking a destructive tool, and none of it is derivable from the annotation flags.

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

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

Four short sentences, front-loaded with the effect, then side effect, then the alternative routing, then the return value and cost. Every sentence carries distinct information; nothing restates the tool name or 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?

For a one-parameter destructive tool with no output schema, the description covers effect, reversibility, cost, return value, and the alternative tool for the adjacent intent. There is no gap an agent would need to guess at in order to invoke this correctly.

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

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

Schema coverage is 100% and saved_key already carries a concrete example (instagram:C8xYz12AbCd), so the schema does the heavy lifting. The description adds the complementary detail that the returned value is that saved_key, closing the loop between input and output for an agent chaining calls.

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 — removes a post from the creator's saved inspiration list — and immediately names the affected surface (list_inspiration), which is itself a sibling tool. An agent can distinguish this from save_inspiration and delete_library_item 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 when-to-use ("clear out posts") and names the alternative plus the exact parameterization for a near-miss case: "to keep a post but move it out of the way, save_inspiration with status archived." That is a rare, concrete disambiguation between two sibling tools.

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

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

Goes well beyond the annotations by disclosing the economic consequence that scan credits already spent are not refunded, while the untrack action itself costs no credits. It also states what is returned (the removed creator and slots used) and what state changes (feed and plan slot).

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

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

Four short clauses, front-loaded with the effect, then the routing guidance, then return values and the credit caveat. Every sentence supplies information the agent needs and none 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?

With no output schema, the description compensates by describing the return payload and the non-refund rule. Combined with the destructive annotation, an agent has everything needed to call this correctly and understand the cost of doing so.

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 creator_id parameter is already documented as 'The id from list_tracked_creators'; the description repeats that provenance but adds no format or validation detail beyond it. Baseline 3 applies when the schema carries the parameter meaning.

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

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

States a specific verb and resource ('Stops tracking a creator') and immediately names the concrete consequences: removal from the tracked list and feed, and freeing a plan slot. This is clearly distinguishable from the sibling track_creator.

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 tells the agent when to use it ('to make room before track_creator') and where to get the required id ('list_tracked_creators shows the ids'), which are exactly the two siblings an agent would otherwise have to guess between.

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 destructiveHint=true annotation, the description discloses the precise destruction semantics ("a pillar left out is removed") and the id-based edit-vs-create contract. It also covers target scope (active Brain vs. a given draft brief_id), the side effect that new drafts use the change at once, the return value, and the zero-credit cost — none of which the annotations 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 action, then the list contract, then routing, then scope/cost. Every sentence carries distinct information — even the short trailing "Uses no credits" materially affects whether an agent should call estimate_cost first.

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 by stating the return ("the saved pillars with what changed"). Combined with the replacement contract, prerequisite read, draft-vs-active targeting, and cost, an agent has everything needed to invoke this destructive mutation correctly.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds a semantic the schema does not: this is a full-list replacement where ordering is significant and omission equals deletion. The per-field id/angle/shape/leads_to behavior is largely already in the schema descriptions, so the added meaning is real but concentrated in the list-level contract.

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 with a specific verb and resource ("Sets the content pillars of the creator's Creator Brain") and enumerates the exact operations supported: rename, reword, add, remove, reorder. It also states the hard cap (up to 6), which immediately separates it from sibling tools like update_creator_profile or add_brain_document.

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

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

It gives an explicit trigger ("Use it when the creator wants different topics") and a prerequisite ("read the current pillars and ids with get_creator_brain first"). It then routes away to the correct alternatives for adjacent needs — add_brain_document plus build for offers/proof/voice rules, and update_creator_profile for name, bio and niche — so the agent has a complete decision tree.

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 partial-update semantics ("Only the fields passed change"), the return payload (fields changed plus fields still missing) and the credit cost ("Uses no credits"). What it omits is any acknowledgment of the destructive edge the annotations flag: the schema notes an empty string removes a handle, and the description never warns that a call can erase data.

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

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

The trigger condition and the sibling routing are front-loaded, and the return/credit facts are packed into short trailing sentences. The middle sentence is long and comma-heavy, stacking quoted examples and two alternative-tool redirects into one clause, but nothing is redundant.

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

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

For a nested-object, zero-required, mutation tool with no output schema, the description covers trigger, scope, merge behavior, return shape and cost, which is nearly everything an agent needs. The remaining gap is the destructive empty-string removal, which the annotations emphasize but the prose never mentions.

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 per-field meaning is already documented. The description still earns above baseline by stating the merge behavior that the schema cannot express — that omitted fields are left untouched — which is the single most important semantic for a 6-param partial update.

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?

"Saves the creator's profile basics" pairs a specific verb with a specific resource and then enumerates exactly which fields are in scope (name, bio, niche, target audience, content language, social handles). The sibling set contains get_creator_profile, update_voice_examples and add_brain_document, and the description draws the line between them 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 names two concrete triggers — the creator self-describing in chat, with quoted example phrasing ("I post about...", "keep in mind that my audience is..."), and a draft tip naming a missing field. It also routes competing intents away: update_voice_examples for voice samples, add_brain_document for offers and story.

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 readOnlyHint=false, so the mutation profile is known; the description adds genuinely new facts: it returns the updated draft and consumes no credits. The one appreciable gap is whether omitted fields are preserved or cleared, which matters for a destructive in-place edit of array fields like hooks and ctas.

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 its field scope, followed by disambiguation, then cost and return behavior. No filler, no restatement of the title.

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

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

For an eight-parameter mutation tool with no output schema, the description covers scope, sibling routing, return value, and credit cost. It falls just short on merge-vs-replace semantics and on what happens to array fields (hooks, ctas) that the schema describes as full ordered lists.

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 100% schema coverage the schema already defines all eight parameters, so the baseline is 3. The description nonetheless adds cross-platform context by noting the 'option' parameter applies to LinkedIn and X and that only one option is edited at a time, which helps an agent map platform to parameters rather than treating them as a flat list.

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

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

States a specific verb and resource ("Edits a delivered draft in place") and enumerates exactly which fields are editable: title, main text, hooks, CTAs, on-screen text, caption. It also distinguishes itself from two named siblings (update_library_item, edit_carousel) so the agent can route 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 an explicit when: "keep the creator's changes on a draft before saving." Gives explicit alternatives with conditions: library items go to update_library_item, carousel slides go to edit_carousel. Nothing is left to inference.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description adds real behavioral context beyond them: the call is credit-free and returns the updated item. It also discloses a subtle persistence rule (manual pillar/funnel assignments survive automatic tagging). It does not, however, address the destructive flag directly — whether replacing `text` discards the previous version is left unexplained.

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: what it edits, how to use it plus the sibling redirect, and the return/cost facts. The editable-field list is front-loaded and the exclusion follows immediately; nothing is redundant.

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

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

With 9 parameters, full schema coverage and no output schema, the description covers the field scope, the draft-vs-saved routing, the return value and credit cost. The remaining gap is the destructive semantics — an agent still cannot tell whether overwriting text or clearing pillar_id/funnel_stage is reversible.

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 exceeds that by explaining the persistence semantics of pillar_id and funnel_stage ("a pillar or funnel stage set here stays"), which the schema does not say, and by clarifying the status vocabulary in prose. Other parameters are left to the schema, which is fair given full coverage.

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

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

Names a specific verb ("Edits") and resource ("a saved library item") and enumerates exactly which fields are editable: title, text, hook, CTA, notes, status, pillar, funnel stage. It also explicitly separates itself from update_draft, so an agent can distinguish it from the closest sibling 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 a positive usage frame ("Use it to plan and track saved pieces") and an explicit exclusion with the alternative named ("For unsaved drafts use update_draft"). That is both when-to-use and when-not-to-use guidance in one line.

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 openWorld=false, so the overwrite warning is consistent rather than novel, but the description adds real detail beyond them: slot-1-onward overwrite, starter text cleared vs. creator's own examples kept, per-slot return of what was saved/cleared, and "Uses no credits." The only gap is that it does not flag what happens to the previously saved set for slots beyond the new array length in explicit terms, though the overwrite model is strongly implied.

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

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

Four sentences, front-loaded with purpose, then the routing rule, then the overwrite semantics, then the return and cost note. Every sentence carries decision-relevant information and none repeat the title or 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 3-parameter mutation with no output schema, the description covers purpose, alternatives, destructive overwrite behavior, return summary, and cost. An agent has everything needed to call it correctly and warn the creator about clearing starter text.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks: the effective limit is 5 examples except 3 for the newsletter (schema only says maxItems 5), and the crucial instruction "Pass the full set" governs how the array parameter is submitted. The CTA limit of 3 matches the schema and adds little.

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 uses a specific verb and resource ("saves pasted posts as the voice examples... and calls to action of one format") and states the downstream effect ("so new drafts copy that wording"). It also names the sibling it is not (import_voice_from_posts / list_my_posts), so an agent can distinguish 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?

Explicit when-to-use: "Use it when the creator pastes their own posts or CTAs." Explicit alternative and routing condition: "to pull posts from a social account use list_my_posts and import_voice_from_posts." No inference required.

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