Hookbird

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds material context the annotations cannot: the tool is free, every metric carries a source report and year plus a plain-language "why", estimates are flagged as estimates and must be disclosed, and `you` is null when the channel isn't connected. The nullability and estimation caveats directly affect how an agent should report results.

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

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

The opening sentence is front-loaded and dense with the right information, and each follow-up sentence earns its place (provenance, estimate caveat, null handling, usage trigger). The usage trigger arriving last, plus the irregular line breaks, makes the ordering slightly less scannable than ideal.

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

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

An output schema exists, so return values need no explanation; what the description must cover is data reliability and scope, which it does (source/year provenance, estimated percentiles, null `you`, 30-day window, per-platform breakdown). Nothing an agent needs in order to call and correctly report on this tool 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 both parameters document their defaults, so the schema already carries the load. The description only implicitly reinforces the `platform` dimension ("per platform") and explains what the niche is compared against, adding marginal meaning beyond the schema — the expected 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?

The description names a specific verb and resource: comparing this account's last-30-day engagement rate and posting frequency against niche median and top 10%, broken down per platform. That scope is distinct from siblings such as radar_trends or strategy_plan, so an agent can select 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?

It gives concrete trigger phrases — "how am I doing?" and "what's good for my niche?" — which map cleanly onto user intent. It stops short of naming exclusions or an alternative tool for adjacent questions (e.g. trend discovery vs. benchmarking), so it lands at a solid 4 rather than a 5.

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

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

Annotations already declare this as read-only, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds meaningful behavior beyond annotations: it explains the "found": false sentinel, the need to obtain a website and call brand_read in that case, and the dependency relationship with hooks and strategy tools.

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

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

The description is front-loaded with what the tool returns, then usage guidance, then the fallback path. Every sentence contributes: field enumeration, first-call instruction, downstream audience-id usage, and the brand_read fallback are all useful and non-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?

Given that this is a zero-parameter, read-only tool with an output schema and complete annotations, the description supplies everything else an agent needs: what the brand profile contains, when to call it, how its result is used downstream, and what to do when the brand has not been read.

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 input parameters, so the baseline is 4 and there is no parameter semantics gap to compensate for. The description does not need to explain input parameters beyond noting that no input is required.

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: it gets the account's brand profile and enumerates the returned fields such as name, website, niche, voice, positioning, competitors, and audiences. It also distinguishes this from brand_read by explaining that brand_read is the fallback when the brand was never read.

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

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

The guidance is explicit: call this first in any content task, and all hooks, angles, plans, and Studio content are written from it. It also states the alternative path clearly: when "found" is false, ask for the website and call brand_read. It additionally explains how to pass an audience id downstream to hooks_generate, hooks_score, and strategy_plan.

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 cost (free), latency (1–3 minutes), the async polling contract (each call waits up to 20 seconds), and the state side effect of overwriting an existing profile. That overwrite note is the kind of consequence annotations (destructiveHint=false) do not convey on their own.

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 paragraphs, front-loaded with what the tool does and how long it takes, then the call sequence, then the guardrail against redundant runs. 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 an output schema present, return values need no explanation, and the description covers the only non-obvious part of the contract: the async job handshake and handoff to brand_profile. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented; the description adds the operational rule that the two are used in separate modes (start with "url", follow with "jobId" only). It stops short of clarifying what happens if both or neither 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?

Specific verb+resource: reads a brand from its website and saves it as a profile, with the extracted facets enumerated (name, logo, colours, voice, products, audiences, competitors, white space). It is clearly distinct from the sibling brand_profile, which it names as the downstream consumer of the result.

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 lifecycle: start with "url", poll with "jobId" only, and call brand_profile when status is "done". It also states the when-not condition — reading again replaces the current profile, so only do it when the user asks or when brand_profile is empty.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so safety and determinism are covered structurally. The description adds non-obvious domain behavior: plan credits are spent first, pack credits never expire, and the period end is reported. It does not mention caching/staleness of the balance, which is the one useful behavioral fact still missing for a read 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?

Content is front-loaded: the return contents come first, then the spending rules, then the call trigger. The first sentence is long and comma-chained, and stray indentation whitespace slightly hurts readability, 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 an output schema present, an annotated read-only profile, and zero parameters, the description fills exactly the remaining gap: what the numbers mean and when to fetch them. Nothing an agent needs to call this correctly is absent.

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 for this dimension is 4. The description correctly implies an account-scoped, argument-free read and raises no ambiguity about inputs.

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

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

Opens with a specific verb and resource: "How many Hookbird credits this account has left", then names the exact components returned (plan credits, pack credits, total, monthly allowance, period end). An agent can distinguish it from studio_formats (prices) and studio_generate (spending) 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 triggers: "Check this before a large generation or when the user asks about credits." It also explains the economy that motivates the check — Studio generations spend credits while hooks, brand, plans, Radar and benchmarks are free — so the agent can infer when a credit check is warranted.

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/idempotentHint, but the description adds substantial context beyond them: cascading deletion of comments, per-channel id semantics, repetition-collapsing behavior ('deleting it deletes every repetition'), the side effect that published posts stay live on the network, and irreversibility. It even points at output.errors for failure diagnostics.

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 trigger condition and prerequisite, then the behavioral caveats. Six sentences is on the long side but each carries distinct information (comments, per-channel ids, repetitions, publish semantics, irreversibility); nothing reads as 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?

Covers trigger, prerequisite lookup, id scope, cascade behavior, cross-system effects, irreversibility, and error reporting (output.errors). With an output schema present, no further return-value explanation is needed; nothing an agent needs to call this destructively correct 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 is 3, but the description adds real meaning: the id identifies a single channel's copy of a post, and a multi-channel post has a separate id per channel, plus how repeating posts share an id. That is semantics an agent cannot get from the schema's bare 'id of the post to delete'.

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 ('delete an existing post') and enumerates the states it applies to (scheduled, draft, published, errored), which immediately separates it from create/update siblings. An agent can tell exactly what this tool does without opening the schema.

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

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

Gives clear usage context ('when the user wants to delete an existing post') and a prerequisite workflow: find the post first via list-your-posts and pass its id. It references 'list your posts' rather than naming the concrete sibling postsListTool, so the routing is slightly indirect but still actionable.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the description needn't re-explain safety. It adds nothing beyond that — no mention that each call produces a new non-deterministic output, whether credits are consumed (a credits_balance sibling exists), or how the 'video' case differs. The one added sentence is confusing rather than informative.

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

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

The purpose is front-loaded in the first clause, which is good, but the remaining text is a run-on with stray line breaks and a second, semi-coherent instruction about video that does not earn its place. Roughly half the content is useful.

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

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

An output schema exists, so return values needn't be described, but the single undocumented required parameter and the confusing video clause leave real gaps for an agent deciding when and how to call this generator. The annotation set carries the safety profile, yet the operational guidance is incomplete.

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 required 'prompt' parameter with 0% schema description coverage, so the description must explain what the prompt should contain and the description says nothing about it. The image-vs-video sentence introduces ambiguity about whether the prompt is for an image or a video.

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

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

The verb+resource is clear ('Generate image to use in a post'), but the trailing clause about 'ask if they want to generate a picture of a video' muddies what the tool produces and blurs the line with the sibling generateVideoTool. An agent can identify the basic action but not confidently distinguish image output from the video alternatives.

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

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

It does name a concrete trigger condition: use when the target platform requires an attachment and none was supplied. However, it never references the obvious alternatives (generateVideoTool, generateVideoOptions, uploadFromUrlTool) that an agent should weigh before generating, and the final instruction is ambiguous.

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 the operation as read-only, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds a workflow hint that some options require another call, but it is too vague to be confidently actionable.

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

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

The description is a single sentence with no wasted words, but it is a comma splice that is not front-loaded with a clear action. It is concise but under-informative rather than well-structured.

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

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

The tool is simple and has an output schema, so return values need not be explained. However, the description does not clarify what the listed options contain or how they relate to sibling generation tools, leaving gaps for an agent deciding how to proceed.

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

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

Schema description coverage is 100%, and the single optional 'reasoning' parameter is fully documented in the schema. The description adds no meaning beyond that structured field, so the baseline of 3 applies.

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

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

The phrase 'All the options to generate videos' identifies the resource but does not use a clear verb and leaves 'options' ambiguous (models, formats, parameters?). It does not clearly differentiate this listing tool from siblings like generateVideoTool or videoFunctionTool, though the title helps.

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

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

The description gives no explicit instruction on when to call this tool versus generateVideoTool, videoFunctionTool, or videoStatusTool. The clause 'some tools might require another call to generateVideoFunction' is vague and does not tell the agent when to use this tool or when not to.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, non-idempotent), it discloses the key async trait: generation takes minutes, the call only kicks off a job, returns a jobId, and requires polling. That is exactly the behavior an agent cannot infer from annotations. It does not cover failure modes, credit costs, or cancelability.

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 front-loaded purpose is good, but the body is a run-on with inconsistent line breaks, an awkward conditional clause, and a trailing colon leading to an empty list. The empty enumeration is dead weight that leaves the reader expecting content that never arrives.

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-required-parameter tool with 0% schema coverage, the description leaves the entire input contract unexplained; the one attempt to document the video types is an empty list. The async/jobId workflow and the surrounding sibling choreography are well covered, but an agent still cannot construct the arguments from this 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 description coverage is 0% across three required parameters, and the description says nothing about 'identifier', the vertical/horizontal 'output' enum, or which keys belong in 'customParams'. The dangling 'Here are the type of video that can be generated:' colon looks like it was meant to enumerate customParams values but the list is empty, so no meaning is added.

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+resource ('Generate video to use in a post') and implicitly separates it from generateImageTool by discussing an attachment-driven workflow. It gets muddied by the confusing phrase 'ask if they want to generate a picture of a video', which blurs whether this tool makes videos or images.

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

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

It names the trigger condition (a platform requires an attachment that wasn't provided), a prerequisite sibling ('videoFunctionTool' for things like voice id), and the follow-up sibling ('videoStatusTool' polling until 'completed'). There are no explicit when-not-to-use rules, and the 'picture of a video' sentence introduces ambiguity about the alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond them by clarifying the domain meaning of 'group' (customers) and how the returned ids are consumed downstream, which is genuinely useful context an agent would otherwise have to guess.

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

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

Two short sentences with zero filler: the first defines the operation, the second routes the agent to the follow-up tool. Front-loaded and appropriately sized for a trivial list tool.

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

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

With an output schema present, the description need not explain return values, and annotations cover the safety profile. The only minor gap is no mention of whether the full set is returned or whether results are paginated/limited, but nothing essential for correct invocation is missing.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain and the baseline of 4 applies. The description correctly adds nothing spurious about inputs.

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

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

States a specific verb and resource ('lists the available groups') and immediately disambiguates the term by equating groups with customers. An agent can distinguish this from siblings like integrationList without inspecting the schema.

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

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

Explicitly tells the agent what to do next: take a group id and pass it to integrationList to filter integrations by group. That is a concrete downstream-use guideline rather than a vague hint. It stops short of stating when not to call it, but for a zero-parameter enumeration tool that exclusion is rarely needed.

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

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

Adds real behavioral context beyond the annotations: 'Free (no credits)', ordering guarantee ('Best first'), and that each result carries its pattern and estimated percentile. Annotations already cover safety profile (non-destructive, non-read-only, non-idempotent), so this complement is enough, though it doesn't say whether generated hooks are persisted server-side.

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

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

Front-loads what is produced and that it is free, then moves to prerequisites and next actions. A few parentheticals add length but each carries usable information; 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?

With annotations, full schema coverage and an output schema present, the description only needed to cover prerequisites and the cross-tool workflow, which it does. Minor gap: no mention of whether results are stored or how failures surface, but that is close to negligible for a generation tool with an output schema.

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

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

Schema coverage is 100% and documents all four parameters including defaults and the enum, so the baseline is 3. The description only restates that topic, audience id and platform aim the output; it adds no format or constraint detail beyond the schema.

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

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

States a concrete verb and resource ('Write hooks — the first line or first 2 seconds of a post') and immediately describes the output shape (score 0-100, pattern, percentile, rationale, best first), which distinguishes it from the similarly named hooks_score sibling that evaluates rather than writes.

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

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

Explicitly says to call brand_read first if brand_profile is empty, names the steering inputs (topic, audience id from brand_profile, platform), and gives the follow-up action: pass the best hook as 'hook' to studio_generate. When, prerequisites, and next step are all covered.

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

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

Adds genuinely non-obvious context beyond the annotations: the call is free (no credits), a brand profile is optional but sharpens output, and percentile values must be labeled as 'estimated'. It also enumerates the return payload's shape (pattern, strengths, fixes, rewrite, breakdown, percentile), which tells the agent what to do with the result.

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 verb, scale and cost, then use cases, then prerequisites — a sensible order with no filler. The sentence enumerating return fields is somewhat redundant given an output schema exists, and the ragged line breaks add noise.

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

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

For a 4-parameter scoring tool with an output schema, the description covers cost, prerequisites, trigger conditions, interpretation caveats and the effect of the save flag's domain context. An agent has everything needed to call it and explain the result 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 schema already carries parameter definitions and the baseline would be 3. The description edges above baseline by explaining that the tool 'works without a brand profile, but is sharper with one', which gives implicit guidance on the optional audienceId parameter.

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

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

States a specific verb and resource ('Score one hook') plus the scale (0 to 100), and even defines what a hook is ('the opening line of a post or video'). The singular scope inherently separates it from the sibling hooks_generate, which produces hooks rather than rating one.

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 trigger ('when the user asks "is this hook good?"') and a proactive use case ('check a hook before generating content with it'), plus a prerequisite note that a brand profile is optional but improves results. It stops short of naming a sibling alternative or stating when not to use it, so it is clear but not fully exhaustive.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and non-open-world, so safety is covered. The description adds the scoping behavior of the group filter but says nothing about result volume, pagination, or what an 'integration' record contains — acceptable given an output schema exists.

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

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

Two sentences with the core purpose front-loaded and the optional behavior second — no wasted text. Minor grammar slip ('This tool list') keeps it from the top mark.

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

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

With rich annotations, a fully described parameter, and an output schema, the description needs only state purpose and the filter option, which it does. Nothing an agent needs in order to call it is missing.

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

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

Schema coverage is 100% and the single optional parameter is fully documented in the schema, including the groupList cross-reference, which the description largely repeats. Baseline 3 applies since the schema carries the explanatory load.

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

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

States a specific verb+resource: list available integrations used for scheduling posts. That is clearly distinct from siblings like integrationSchedulePostTool or integrationSchema, though the description does not explicitly name those alternatives to draw the contrast.

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

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

Explains the optional filter case and where the group id comes from (groupList tool), which is genuine usage guidance for the parameter. However, it never says when to call this versus integrationSchedulePostTool or integrationSchema, nor any prerequisites, so selection guidance is only implied.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and non-idempotent, so the safety profile is covered; the description adds genuinely new behavior: each output item carries a previewUrl, and validation failures return output.errors with a documented retry path. It does not explain why the operation is flagged destructive (immediate 'now' publishing is irreversible) or disclose any rate limits, so it stops short of full disclosure.

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

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

Purpose and the negative constraint are front-loaded, and the two examples earn their space by resolving an ambiguous cardinality rule. The formatting is a bit list-heavy for a description of this length, but there is no filler sentence.

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 deeply nested, multi-object creation tool, the description supplies the usage trigger, the exclusion, the dependency on integrationSchema, the return-value cues (previewUrl, output.errors), and the retry path. With an output schema and full annotation coverage present, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, and the two worked examples add real meaning the schema does not convey: the cardinality relationship between socialPost and postsAndComments (N posts vs. one post plus comments). The array-length descriptions are slightly indirect and the 'first item is the post' note repeats the schema rather than extending 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 specific verb and resource ('create a draft, scheduled, or immediate social media post on their connected channels') and names the schema tool it depends on. It also explicitly carves out what it is not ('Do not use this to update or delete existing posts'), which separates it from deletePostTool and other post-management siblings.

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

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

The opening clause gives an explicit trigger condition ('Use this when the user wants to create...'), the closing lines give an explicit exclusion ('Do not use this to update or delete existing posts'), and it points at integrationSchema as the prerequisite for building settings. When/how-not/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 readOnly/idempotent/non-destructive/closed-world, so the description does not need to restate safety. Instead it adds genuinely new behavioral context about the response: the schema may demand an id, that ids come from 'tools', and that 'tools' may contain a mention lookup. That is workflow information an agent cannot get 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?

The first two sentences restate the same idea ('we need to understand the schema' / 'helps us get the schema'), and the third sentence has a typo ('the requires some id') that slightly obscures meaning. The follow-up guidance is useful, but the prose could be halved without losing information.

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

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

For a 2-parameter read tool with an output schema, the description supplies the missing piece: what to do with the result (resolve ids via 'tools', then triggerTool) and the mention-lookup path. An agent can call this correctly and knows the next step, though a note on premium gating (isPremium) is absent.

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 platform enum is fully enumerated in the schema, so the structured data already carries the parameter burden. The description mentions neither 'platform' nor 'isPremium' and adds no semantics beyond the schema; baseline 3 applies.

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

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

States a specific resource and action ('get the schema of the integration') and frames it in the workflow of scheduling a social media post, which distinguishes it from siblings like integrationSchedulePostTool or integrationList. The first-person phrasing ('we need to understand') is less direct than a crisp verb+resource statement, but the intent is unambiguous.

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

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

Gives an explicit trigger ('Everytime we want to schedule a social media post') and a follow-up rule: if the returned schema requires an id, look in 'tools' and call triggerTool. It also flags the mention-lookup use case for tagging people/pages. What it lacks is any statement of when NOT to use it or how it differs from integrationList.

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 read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond that: results are newest first, paginated at 18 per page, and searchable by original filename, plus the returned path can be reused as an attachment URL.

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

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

Two sentences, front-loaded with the core purpose and immediately followed by practical integration guidance. There is no wasted text.

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

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

Given the rich annotations, complete input schema, and presence of an output schema, the description is complete enough for an agent to select and invoke the tool correctly. It also explains how to use the returned path, which is the key operational nuance.

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 in the schema. The description restates that search works by original filename, but adds no syntax or format detail beyond what the schema provides.

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

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

The description provides a specific verb and resource: list media already uploaded to the media library. It also scopes the result set (newest first, 18 per page) and distinguishes the tool from upload siblings by emphasizing 'already uploaded.'

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

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

It gives a clear usage path: use the returned path as an attachment URL in integrationSchedulePostTool instead of re-uploading. This is helpful routing guidance, though it does not explicitly state when to list versus upload in other scenarios.

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

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

Adds real context beyond the annotations: merge semantics (unpassed keys are preserved), the dependency on integrationSchema for valid keys, and that validation failures surface in output.errors and the call is retryable. It does not explain what happens when a passed key overwrites an existing value, which matters given destructiveHint=true.

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 and scope in the first two sentences, then layers prerequisites and error behavior. Five sentences is on the long side and the integrationSchema note is repeated in both the description and the schema, but nothing is wasted.

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

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

With an output schema and annotations already covering safety signals, the description supplies the missing pieces an agent needs: merge behavior, the schema-lookup dependency, and retry-on-validation-error. Only the overwrite/reversibility angle for existing keys 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 meaning the schema does not: merge-only semantics, that 'settings' keys come from integrationSchema, and that 'id' must come from a prior list call. It stops short of elaborating on id-vs-label resolution, which only the schema's nested value description 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 (update provider settings of an existing post) and scopes it precisely to posts that were NOT published yet. It also draws the boundary that content and publish date are untouched, which separates it from publish/schedule and content-editing 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?

Gives a concrete precondition-plus-workflow: find the post first via listing your posts, then pass its id, and only pass the keys you want changed. It does not name the exact sibling (postsListTool) or say what to do for already-published posts, so routing is implied rather than explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's job is added context, and it delivers: it discloses that the result is state-agnostic (scheduled, draft, published, errored) and enumerates the returned item fields including error and media details. No pagination or result-size limits are mentioned for a potentially wide window.

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

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

Front-loaded with the core action, then scope, then the required-parameter rule, then the return shape. Every sentence carries information an agent needs; 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 an output schema present, the description needn't detail return values, yet it still sketches item contents, which is a plus. The only real gap is the absence of any note on result size, pagination, or ordering across a year-long 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?

Schema coverage is 100%, so the baseline would be 3; the description adds genuine meaning by marking startDate/endDate as required UTC and explaining the wide-window idiom for listing everything. The optional 'customer' filter is left to the schema alone.

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

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

States a specific verb (list), resource (the organization's posts), and scope (scheduled within a date window), and notes it maps to the "List Posts" API endpoint. Siblings like deletePostTool and postSettingsTool operate on single posts, so this reads as a distinct bulk-list operation.

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

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

Explains that both dates are required (UTC) and gives a concrete recipe for the common case: pass a wide window such as now to a year ahead to see all upcoming posts. It also clarifies that all states are returned, which prevents agents from trying to filter by state. It stops short of naming alternatives among the many post 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?

Beyond the read-only and open-world annotations, the description discloses that results are cached for 24 hours, that the tool is free, that each ad includes hook text, platform, days running, and a why, and that providers indicates which sources are enabled and why any are off. It also handles the important behavioral case of empty results from disabled providers.

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 the core purpose and then layers in result fields, provider behavior, and downstream usage. It is slightly verbose with indentation artifacts and parenthetical asides, but nearly every sentence carries useful operational context.

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

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

Given six optional parameters, full schema coverage, rich annotations, and an output schema, the description is complete enough for correct invocation. It covers return fields, caching, provider status, empty-result handling, where to find competitor names, and how to use the results with hooks_generate.

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 still adds some meaning beyond the schema by clarifying that q can be a free search term and that competitor names come from brand_profile, which helps the agent populate those parameters correctly.

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: finding ads a competitor or search term is running from connected ad libraries. It distinguishes this from research and content-generation tools by explaining that it returns hooks, platform, run duration, and a short rationale, and it names its downstream use with hooks_generate.

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

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

It gives clear when-to-use guidance: look up competitor names in brand_profile, use radar_ads to find competitor ads, then remix winning hooks with hooks_generate. It also gives an explicit edge-case instruction: when ads is empty and no provider is enabled, tell the user ad sources are not set up rather than inventing ads.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds valuable behavioral context beyond those: caching for 12 hours, free cost, and the provider-availability semantics (which sources are on/off and why). It does not cover rate limits or quota, but the added context is substantial.

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 purpose and key output details, then defaults, then provider caveat, then use case. It is appropriately sized and every sentence contributes, though the middle sentence is slightly long with parenthetical nesting.

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

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

Given the output schema exists and annotations cover safety, the description is nearly complete: it covers purpose, defaults, caching, cost, provider semantics, and recommended use. Only minor behavioral details (e.g., pagination or rate limits) are absent, which is acceptable for a read-only tool with an output schema.

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

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

Schema description coverage is 100%, so each parameter is already documented in the schema. The description adds only the default behavior for niche/region from brand profile, which is also stated in the schema. No extra format or constraint details beyond the schema are provided.

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 specifies the resource (trending hashtags, sounds, creators, top posts) and the scope (niche, country) with concrete output fields (ranked, views, post counts). It is clear what the tool returns, though it does not explicitly name or differentiate against the sibling radar_ads tool.

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

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

Explicitly states the use case: 'Use it to pick a timely topic for hooks_generate or a sound/hashtag for a post.' It also names the fallback behavior ('an empty list means no source covers it, do not invent trends') and the default source of niche/market, leaving little to inference.

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

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

Annotations mark this as non-read-only and non-destructive, but the description adds important behavioral context absent from annotations: plan creation is free, channel ids create DRAFT posts in the calendar with nothing published, angles are written first when the audience has none, and the operation takes about a minute. This is exactly the kind of side-effect, cost, and timing disclosure that helps an agent invoke the tool correctly.

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 the core purpose and then structured by action. It is somewhat dense, but every sentence adds useful operational detail and there is no obvious 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?

Because an output schema exists, the description need not explain return values. It covers cost, timing, side effects, prerequisites, action selection, and the handoff to studio_generate, leaving no essential gap for an agent calling 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 schema already documents each parameter. The description still adds cross-parameter meaning: 'channels' accepts platform names and/or channel ids, and channel ids additionally create DRAFT posts; 'cadence' means posts per week; and 'weeks' covers 1–8 weeks. This goes beyond the schema descriptions, though not comprehensively for every parameter.

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

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

The description names both verbs and the resource precisely: 'Create or read a content plan: a calendar of posts...' It also explains the two actions ('create' builds a plan; 'get' returns or lists plans), so an agent can distinguish this tool's purpose without inspecting the schema.

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

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

It states when to use each action and gives explicit alternatives: use 'create' to build a plan, use 'get' with planId to read one or omit planId to list plans. It also routes the agent to studio_generate for making an individual post and tells it to confirm audience, channels, cadence, and weeks with the user first.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description does add real context beyond that: per-duration credit pricing (including Premium/realistic-model tiers), required inputs per format, what each outputs, and that it returns hook formulas usable as 'hook' on studio_generate plus org avatars. That is solid added value, but it stops short of operational traits like response size or latency for an enumeration endpoint; a 3 is fair with annotations carrying safety.

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 returns, then the call sequence. The long parenthetical format enumeration is slightly dense but each item conveys a distinct capability the agent may need to match against a user request, so the length is largely earned.

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

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

The tool is a zero-required-input listing call with an output schema, and the description already summarizes the return payload (formats with prices, inputs, outputs, hook formulas, avatars) plus the required downstream workflow. Nothing an agent needs to call it correctly is missing.

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

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

There is a single optional parameter ('reasoning') and schema description coverage is 100%, so the schema fully documents it. The description correctly implies the tool is callable with no meaningful input. Baseline 4 applies since the description adds no contradicting or missing 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?

Specific verb ('List everything Studio can generate') plus a concrete enumeration of the resource: post formats, slideshows, UGC talking heads, stories, hook+demo videos, voiceovers, images, clips, avatars. It is clearly distinct from sibling studio_generate (which produces) and studio_recipes.

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: 'Call this before studio_generate, tell the user the price in credits, and get their confirmation before generating.' It names the alternative tool and the prerequisite workflow, 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 only say readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds the material behavior an agent actually needs: generation consumes credits at the format's price, confirmation is required first, execution is asynchronous with rough latency by content type, results land in the media library, and credits are refunded on failure. That is substantial value beyond the annotations.

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

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

Core purpose is front-loaded in the first sentence and every subsequent sentence carries operational information (price, confirmation, async, polling, refunds, recipes). It is dense but slightly overlong, with the recipe rule appearing twice (once in the body, once in the final sentence).

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

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

For a 14-parameter, credit-spending, async generator, the description covers cost, confirmation, execution model, follow-up tool, output destination, failure handling, and the recipe shortcut. An output schema exists, so return-value shape needs no further explanation.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by explaining the formatId/recipeId mutual requirement (neither is schema-required) and by defining recipe precedence over passed values. It does not add detail on hook, angle, or mediaIds beyond what the schema already documents.

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

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

States a specific verb (generate) and resource (content in a Studio format) and immediately points to studio_formats for the format catalog, making it clearly distinct from studio_status (polling) and studio_recipes (saved presets). An agent can pick it over the siblings 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 routing rules: check studio_formats for price/inputs, pass formatId or recipeId, tell the user the price and get confirmation first, then poll with studio_status using the returned generationId. It also covers the recipe path and the precedence rule ('what you pass yourself wins'), leaving little to inference.

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

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

Annotations already establish read-only, idempotent, non-open-world behavior. The description adds valuable beyond-schema context: the call is free (no credits), recipes never carry topic/hook/media, and settings from a recipe are overridden by explicit arguments. That is substantive behavioral guidance rather than restatement.

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 resource, followed by usage and caveats in a logical order. The parenthetical list of settings is lengthy but earns its place by clarifying what a recipe contains; overall the text is tight with only minor 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?

With an output schema present and zero parameters, the description does not need to explain return shape or inputs. It still covers what the tool returns (recipes with formats and settings), how to use the result, cost, and limitations, leaving nothing essential for correct invocation 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?

The tool takes zero parameters and the schema is empty, so the baseline is 4. The description does not need to document inputs, and its enumeration of recipe fields is extra context rather than a schema substitute.

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

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

States a specific verb ('List') and resource ('Studio recipes'), and defines what a recipe is (named format plus settings). It does not explicitly distinguish itself from the sibling studio_formats tool, leaving a possible ambiguity, but the purpose is otherwise unmistakable.

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 context: use it to find a recipe id, then pass that id as recipeId to studio_generate, with explicit precedence ('anything you pass yourself wins'). It also clarifies what a recipe never holds, so the agent knows to still supply prompt/hook/mediaIds. No explicit when-not or comparison to studio_formats, hence not a 5.

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

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

Beyond the readOnly/idempotent annotations, it discloses the 25-second long-poll wait, the three terminal/intermediate states, that 'done' yields hosted media-library URLs plus a suggested caption, and that 'failed' produces nothing and refunds credits. This is exactly the mutation-adjacent behavior (credit refunds, output artifacts) 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 the action and the polling rule, then branches cleanly by status. Slightly long, with the retry instruction restated ('no need to wait between calls' / 'call it again'), but every sentence 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 an output schema and rich annotations already present, the description fills the remaining gaps: polling cadence, per-status meaning, and credit-refund behavior. Nothing an agent needs to poll and interpret results correctly is missing.

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

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

Schema coverage is 100% and the single parameter's schema description already says it is the generationId returned by studio_generate, which the description largely repeats. No additional format, validation, or lifetime details are added, 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 ('Check a generation started with studio_generate') and ties it to the sibling that produces the generationId. An agent can distinguish this from studio_generate, studio_formats, and videoStatusTool without opening any schema.

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

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

Explicitly says when to call again ('status is "queued" or "running" call it again'), how to pace it (25-second long-poll, so no need to wait between calls), and what to tell the user after a few calls. It also implicitly excludes use before studio_generate by requiring its generationId.

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

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

The description discloses behavior annotations cannot convey: invoking it may refresh the stored integration token, and on refresh failure it marks the channel as needing reconnect and notifies the organization. That explains the otherwise surprising destructiveHint=true on a data-fetching tool. It does not cover failure modes for an unrecognized methodName, keeping it below a 5.

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

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

The first sentence front-loads the core purpose well, but 'methodName is required' merely restates the schema's required array, and the literal '[input:callable-tools]' artifact is noise. The auth-refresh sentence, while valuable, is dense and arrives before the parameter guidance is fully resolved.

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

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

An output schema exists, so return values need no explanation, and the description covers the auth side effects and the origin of methodName. What is missing is how to construct dataSchema keys per helper and what happens when an invalid methodName is supplied.

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 67% schema coverage, the description meaningfully adds to the schema: it explains that methodName is required and originates from the integrationSchema callable tools, and that dataSchema carries user-supplied inputs like a search term. It does not explain the key/value pairing rules or what keys a given helper expects.

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 concrete verb and resource: call a provider helper function (a methodName from integrationSchema) to fetch provider-specific data such as ids or search results. It implicitly differentiates itself from the sibling integrationSchema, which lists the callable tools rather than executing them. It stops short of an explicit 'not for X' statement, so it lands just under the top band.

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

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

It gives clear context for use: settings need provider-specific data, and the methodName must come from the integrationSchema callable tools. It also notes that some helpers need user-supplied values, which tells the agent to check the schema before calling. There is no explicit exclusion or named alternative, so it is a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and idempotentHint=false, so the description's job is to add nuance, which it does: it explains the upload-domain validation constraint and that the result is { id, path } or { error }. It does not cover size/type limits, overwrite or duplicate behavior, which would be needed for 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?

Effectively three sentences with the primary action and the local-file exclusion front-loaded. Slightly dense with nested parentheticals from the API URL and the img-src aside, but nothing is wasted.

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

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

A single required parameter plus an output schema means little needs explaining, and the description covers what it returns (id, path) and the failure shape { error }. The only gap is operational limits on the upload itself.

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

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

Schema description coverage is 100% and the schema already says 'public http(s) URL; local files and private hosts not supported'. The description largely restates this constraint, adding only the framing of why (upload-domain validation), 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 ('Upload a remote image or video into the media library from a public http(s) URL') and immediately scopes it against local/private files. It is clearly distinguishable from siblings such as uploadWidgetTool and mediaListTool.

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 trigger ('before scheduling a post when the user provides an external media URL not already hosted on our domain') and an explicit when-not ('Local or private files cannot be fetched by this tool'), naming the alternative public API endpoint as the escape hatch.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely new behavior: polling cadence for the processing state and the meaning of an empty result. It does not discuss what happens if the sessionId is invalid or expired, which is the main remaining gap.

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

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

Four short sentences, front-loaded with what it lists and scoped immediately, then status semantics. Every sentence adds information an agent needs to call it correctly; 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 an output schema present, return values need not be explained, and the description still covers the status lifecycle and readiness for post attachment. It is nearly complete; only session expiry/error handling is unaddressed.

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

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

Schema coverage is 100% and the schema's sessionId description already says "returned by uploadWidgetTool." The description restates that origin but adds no format, validation, or lifetime details beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource+scope: lists media uploaded in a specific upload-widget session, keyed by sessionId. It explicitly distinguishes itself from the broader library listing ("not the whole media library"), which separates it from sibling mediaListTool.

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 call conditions and follow-ups: empty list means nothing uploaded yet, "processing" means wait ~10 seconds and call again, "ready" means it can be used as a post attachment. It also ties the input to its producer (uploadWidgetTool), so the agent knows the prerequisite 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?

With annotations declaring readOnlyHint=false, idempotentHint=false and destructiveHint=false, the safety profile is already covered. The description adds that the ticket is 'short-lived', a genuine behavioral detail beyond structured fields, but says nothing about whether repeated calls issue new tickets or invalidate prior ones.

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 with zero filler, front-loading the purpose and the provenance of the input. Every clause earns its place.

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

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

An output schema exists, so return values need not be explained, and the one parameter is fully documented. What remains missing is the downstream half of the workflow — what the ticket is used for and how it relates to uploadWidgetTool/uploadWidgetStatusTool after issuance.

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's own description of sessionId ('returned by uploadWidgetTool') already carries the semantics. The tool description merely restates that origin, adding no new meaning about format, validation or lifetime.

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: gets a short-lived upload ticket, scoped to a sessionId. It ties itself to the sibling that produces the sessionId (uploadWidgetTool), which makes its role in the widget flow distinguishable from uploadWidgetTool and uploadWidgetStatusTool.

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

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

It implies the prerequisite chain by saying the sessionId comes from uploadWidgetTool, so the agent knows to call that first. However, there is no explicit statement of when this tool must be called (before an upload?) or when it should not, and no alternatives are named despite several upload 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?

Goes well beyond the annotations by disclosing the environment-dependent behavior (widget only appears in MCP Apps hosts; otherwise nothing renders and local files must go through the public API, with a docs link), and that it returns a sessionId whose uploaded files surface in conversation or via uploadWidgetStatusTool. That is exactly the non-obvious operational context annotations cannot carry.

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

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

Front-loaded with the action and the routing rule, then the environment caveat and return note. Slightly redundant at the tail: 'uploadFromUrlTool is only for public URLs' restates the routing already given in sentence two.

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

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

An output schema exists, yet the description still explains the key return value (sessionId) and how the actual uploaded files reach the user, plus the host-app fallback path. Nothing an agent needs in order to call it and handle the result 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline applies. The description does not clutter the call signature with irrelevant instructions, which is correct for a no-arg tool.

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

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

States a specific verb and resource ('Show the user an upload widget to add images or videos from their own device to the media library'), and explicitly separates itself from uploadFromUrlTool and from the status tool. An agent can distinguish it from every upload-related 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 an explicit trigger ('when the user wants to attach a local file to a post'), an explicit exclusion with the named alternative ('when the media is already available on a public URL, use uploadFromUrlTool instead'), and an environment precondition for when the widget is even available.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only that it retrieves additional information and does not clarify what kinds of functions or identifiers are involved, what is returned, or any limitations.

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

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

It is a single sentence but is rambling and front-loaded with filler ('Sometimes when we want to...'). It does not clearly lead with the operation or purpose.

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

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

An output schema exists, so return values need not be explained. However, the description still leaves the two required inputs undefined and does not situate the tool among the many video-related siblings, making it inadequate for correct invocation.

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

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

Both required parameters, identifier and functionName, have 0% schema description coverage. The description never mentions either parameter or explains what an identifier or function name means in this context.

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 vaguely says it may get additional information like voice_id when generating videos, but does not state a specific operation or resource. It is not clearly distinguishable from siblings such as generateVideoOptions or generateVideoTool.

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

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

It implies the tool is used when extra video-generation information is needed, but gives no explicit when-to-use guidance, prerequisites, exclusions, or alternatives. The agent is left to infer its role among several video-related siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond them: it enumerates the three terminal states (pending, completed, failed), the expected latency ('a few minutes'), and the polling cadence, which the annotations cannot express. It does not mention rate limits or job expiry, hence 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, each carrying distinct information: purpose/provenance, polling cadence, and terminal-state outcomes. Purpose is front-loaded and there is no filler.

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

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

For a one-parameter polling tool with an output schema, everything the agent needs to act is present: how to obtain jobId, how long to wait between calls, and what each terminal status yields. The output schema already handles return structure, so no further detail is required.

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 jobId parameter is already documented in the schema as 'The jobId returned by generateVideoTool'. The description repeats that provenance without adding format, lifetime, or validation detail, so the baseline of 3 applies.

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

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

States a specific verb and resource (check status of a video generation) and anchors it to the originating sibling 'generateVideoTool' via the jobId. An agent can immediately distinguish this polling tool from generateVideoTool or generateImageTool 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 concrete operational guidance: the tool is used after generateVideoTool returned a jobId, and while pending the agent should wait ~30 seconds and re-call. It stops short of naming explicit exclusions (e.g. 'do not use for image jobs' or 'do not call generateVideoTool again'), so it is clear context rather than full when/when-not guidance.

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