ShapelessAI

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered by structured data. The description adds context the annotations cannot express: the caller must hold the read OAuth scope, and the underlying API terminology differs from the tool naming. Those two facts materially affect whether a call succeeds.

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?

Twelve words across two fragments, front-loaded with the resource before the scope prerequisite. Every clause carries information. It is perhaps too terse to be maximally useful, but there is no filler to trim.

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 annotations cover the read-only safety profile. The description supplies the remaining critical agent-facing facts (read scope requirement, agent/strategy terminology). Minor gaps remain around whether the roster is paginated or filtered, but nothing essential is missing.

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

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

The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to clarify. Baseline 4 applies; no parameter behavior is misdescribed or left ambiguous.

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

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

The description names the resource concretely ('The agent roster') and resolves a real naming ambiguity by noting the API calls agents 'strategies', which lets an agent map the tool onto what it will see in responses. The listing verb is carried by the tool name rather than the description, and there is no explicit differentiation from agents_save/agents_wake, so it stops short of a 5.

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

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

'Needs the read scope' gives a clear prerequisite for invoking the tool, which is useful operational guidance. However, it says nothing about when to prefer this over siblings like agents_save or agents_wake, nor about any conditions that would make the call inappropriate. Usage is implied rather than stated.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, and the description adds the highest-value behavioral fact beyond them: autoPublishPosts arms publishing with no human approval and requires an elevated scope. It does not disclose edit semantics for omitted fields on a mutation tool where nothing is required, which is the one remaining behavioral gap.

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

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

Two compact sentences with zero filler, and the create/edit rule is front-loaded ahead of the permission caveats so the reader gets the decision rule first.

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

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

An output schema exists, so return values need no explanation, and modes plus scope requirements are covered. The missing piece is patch semantics on edit (whether an omitted field is cleared or preserved) for a tool with zero required parameters.

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 91%, so the baseline is 3 and the schema already carries most parameter meaning. The description goes beyond it by attaching mode semantics to 'id' and a consequence/scope warning to 'autoPublishPosts', which the schema alone conveys only partially.

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

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

The opening clause gives a precise verb+resource pair and resolves the upsert ambiguity outright: create when 'no id', edit 'with id'. That distinguishes it cleanly from agents_list and agents_wake without the agent needing to open 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?

It states the condition that selects each mode (id present or absent) and the permission prerequisites ('publish scope' for autoPublishPosts, 'write' for everything else), which is real when-to-use guidance. It stops short of naming sibling tools for listing or waking agents as alternatives.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and readOnlyHint=false, so the agent knows this is a mutating, external-facing operation. The description adds genuinely non-redundant context: it is publish-scoped, requires the publish scope, and may post automatically with auto-publish. What actually gets destroyed/altered by a wake is not detailed, keeping it below 5.

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

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

Three short sentences, front-loaded with the 'PUBLISH-SCOPED' constraint, then behavior, then return. Every clause carries information and nothing is padded.

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

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

An output schema exists, so the description needn't detail return values, yet it still sketches the key result (the conversation and web url). Combined with the scope requirement and immediate-effect warning, an agent has everything needed to call it correctly.

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

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

Only one parameter and schema description coverage is 100%, so the schema fully documents the agent id. The description adds no extra meaning about the id (e.g. format or where to find it), 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+resource ('wake an agent now') and adds what the wake actually does (plans and proposes, or posts with auto-publish). This is far more than a restatement of the name. It doesn't explicitly contrast with a sibling, but no sibling tool performs a wake, so there is little to distinguish.

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: use it to wake an agent immediately, and it requires the publish scope. The auto-publish branch explains a conditional behavior. It stops short of naming when NOT to use it or a preferred alternative (e.g. agents_save for configuration).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds a non-obvious operational fact beyond that: the call requires the read scope, which the agent would otherwise have to discover through a failed call.

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

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

Two short sentences, zero filler, with the resource identity front-loaded and the auth constraint second. 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-value explanation is unnecessary, and the auth scope is disclosed. What remains unstated is scale or ordering behavior (e.g., pagination or sort), a minor gap for a zero-parameter list tool.

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

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

The tool takes zero parameters, which establishes the baseline of 4 per the rubric. There is nothing for the description to compensate for, and it does not misdescribe any input.

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

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

The description names the resource precisely ("the media library: brand uploads and generated media"), making it clear this is the assets collection distinct from posts_list or connections_list. The listing verb itself is only implied by the name, so it stops short of a full verb+resource statement.

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

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

There is no when-to-use guidance, no conditions or exclusions, and no named alternatives among the many *_list siblings. The one requirement mentioned (read scope) is an invocation prerequisite rather than a usage rule.

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

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

Beyond the readOnlyHint/destructiveHint annotations, it discloses an auth prerequisite ('Needs the read scope') and the iterative loop semantics with a clear exit condition (until open is empty). It correctly routes the mutation to brain_write rather than implying this tool writes, so it is consistent with readOnlyHint=true. Return shape detail is left to the output schema.

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

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

Three compact sentences, front-loaded with what is returned and followed by the operational loop; no filler. Some phrases ('with hints', 'at the item's path') are telegraphic and would benefit from a touch more precision without adding length.

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

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

For a zero-parameter read tool with an output schema, the description covers purpose, auth scope, and the expected human-in-the-loop cycle, which is what an agent needs to act. It does not describe pagination or list sizing, but with the output schema present and a clear 'until empty' condition, the gap is minor.

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

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

Zero parameters, so there is nothing for the description to clarify and the baseline is 4. The mention of 'the item's path' usefully ties the response items to the brain_write call without adding undocumented inputs.

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

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

The description states a concrete resource and scope: the open questions in Brand Memory returned as human-facing questions with hints, which is a specific onboarding surface rather than generic memory retrieval. The verb is implicit (returns/lists) and it never contrasts itself with brain_read or brain_tree, so an agent must infer the distinction from context.

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 prescribes the full workflow: ask the human, write answers as markdown under the question headings via brain_write at the item's path, then re-call until open is empty. This gives both the when (while open items remain) and the terminating condition, plus the partner tool, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds one genuinely non-redundant fact — the required read scope (auth requirement) — but says nothing about failure behavior for a missing path or what the read returns beyond the output schema.

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

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

Two terse sentences with zero waste and the action front-loaded. It is efficient, though extremely minimal — there is no padding to trim, but also little structure to praise.

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-value detail is not required, and annotations carry the safety profile. Still, for a memory-read tool the description omits what a Brand Memory file is (path resolution, allowed set) and what happens on a missing path, leaving minor gaps.

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

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

Schema coverage is 100% with a single documented 'path' parameter including an example ('positioning.md'), so the description is not required to compensate. 'One Brand Memory file' adds no format or constraint detail 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 (Read) and resource (one Brand Memory file), which separates it from the mutating sibling brain_write. It does not, however, distinguish itself from brain_tree, which likely also surfaces memory content, so sibling differentiation is only partial.

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

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

No when-to-use guidance and no alternatives named. The only usage-adjacent statement is 'Needs the read scope,' which is an auth prerequisite rather than a condition for choosing this tool over brain_write or brain_tree.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the read-scope auth requirement, which is useful, but the opaque 'completion ring' and lack of any note on what is returned or how the listing behaves leave the behavioral picture thin.

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

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

Two short sentences with no filler and the resource named up front. It is concise, though the brevity shades into under-specification rather than crispness.

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, for a zero-param list tool sitting among many list/read siblings, the description should orient the agent on when this file tree is the right source; that routing context is absent, leaving it only minimally complete.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds nothing about parameters, and nothing is missing on this dimension.

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 conveys that this returns Brand Memory's file list, which is a recognizable resource, but the phrase 'with the completion ring' is undefined jargon that leaves the actual behavior ambiguous. It does not clearly differentiate from brain_read or assets_list, so an agent cannot route reliably 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?

'Needs the read scope' states an authorization prerequisite but gives no when-to-use guidance and names no alternative. With siblings like brain_read and assets_list, the agent gets no help deciding when this file-tree listing is the right call versus those.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is conveyed structurally. The description adds the auth requirement ('Needs the write scope') and the .md-only constraint, but does not explain what the destructive behavior actually means (overwrite? append? irreversibility), which is the key gap for a destructive write.

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

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

A single tight sentence with the core constraint front-loaded; nothing is wasted. It is arguably too terse for a destructive write, but as pure structure it is efficient.

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 and an output schema present, the description needn't explain returns or safety, and it does cover auth and file-type constraints. However, for a destructiveHint=true write it omits whether an existing file is overwritten, which is material context an agent needs before calling it.

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

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

Schema description coverage is 100% for both params, so the baseline is 3. The description's '.md paths only' merely restates the schema's own 'must end in .md' constraint and adds no syntax, format, or content-size detail beyond the structured data.

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 ('Write one Brand Memory file') and its purpose ('the agent grounds future posts in it'), which cleanly separates it from read-oriented siblings like brain_read and brain_tree. It doesn't explicitly name the alternates, so it stops short of a 5.

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

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

It gives a precondition ('Needs the write scope') and hints at downstream use ('grounds future posts'), but offers no explicit when-to-use vs. when-not guidance, no mention of overwrite semantics versus siblings, and no exclusion conditions.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true and destructiveHint=false; the description reinforces and extends them with the write-scope requirement, an explicit cost (~$0.007 from credit), a budget cap with default 2 / max 10, chargedUsd as the actual spend, and the web-lookup fallback for unknown small brands. No contradiction, and it adds auth, cost and fallback behaviour that the annotations do not 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?

A single front-loaded sentence establishes the deliverable and return shape before cost and auth details follow. It is dense but each clause (cost, budget cap, chargedUsd, write scope) earns its place; only the italicised cost figure feels slightly redundant with the budgetUsd 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?

With an output schema present, the description need not detail the return object, yet it still signals the handle, colour cuts and PNG key. Between annotations, the 100%-covered schema and the output schema, an agent has everything needed to call this correctly, including the billing and scope preconditions.

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

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

Schema description coverage is 100%, so all four parameters (including 'about' and 'domain') are already documented in the schema, including the 'preferred over a web lookup' note. The description quotes the same budgetUsd defaults and the domain-over-lookup preference, adding little semantic value beyond the structured fields.

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

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

The description names a concrete deliverable ('a company's or product's real logo, ready to place') and states what comes back (brand:<slug> handle, colour cuts, PNG media key). Against siblings like find_photo, find_footage and find_face, the agent immediately knows this is the brand-logo lookup rather than generic imagery.

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 implied usage (pass the brand name, provide domain when known, small brands fall back to a web lookup) but never states when to prefer this over find_photo, reference_search or web_search, nor any exclusion. The context is inferable but the routing decision against siblings is left to the agent.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds real context beyond that: it needs the read scope, needs no key over REST, planned routes return 501 until shipped, and planned entries carry a want door.

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

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

Three sentences, front-loaded with the core purpose, and every sentence carries information about content, planned-entry behavior and auth. Minor deduction for insider jargon ('want door', '501 there') that assumes familiarity with the platform's vocabulary.

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. The description covers what the listing contains, how planned entries behave, the auth requirement, and the REST key exception — enough for an agent to call it correctly, though it omits how large the listing is or whether it is filtered.

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

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

The tool takes zero parameters and the schema is empty with additionalProperties=false, so there is nothing for the description to clarify. Baseline 4 for a parameterless tool is appropriate.

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

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

States a specific verb+resource: an inventory of everything ShapelessAI can do, live or planned, including REST routes, MCP tools, CLI lines and page links. It implicitly distinguishes itself from the sibling capabilities_want by describing the 'want door' that a planned entry carries, but never names that sibling explicitly.

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

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

Usage is implied (use it to discover what the platform can do and how to reach each capability), and it does explain what happens with planned entries (route answers 501 until it ships). However, it gives no explicit when-to-use guidance versus other discovery tools such as tools_list or platforms_list, and no exclusion conditions.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, but the description adds real value beyond them: it discloses the default destination (the account's sign-in email), the alternative destinations (another email or an https webhook POST), and the read-scope requirement. It does not cover idempotency of repeat requests or behaviour on an unknown id.

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

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

Three short sentences, front-loaded with purpose, then destination rules, then the consent and scope caveats. No filler or repetition of the title.

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

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

For a four-parameter subscription tool with full schema coverage and an output schema handling return values, the description supplies the missing operational context: default destination, redirect options, human-approval requirement and auth scope.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by explaining the routing semantics of email and webhookUrl relative to the implicit default (the sign-in email) rather than merely restating the field names.

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

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

States a specific action (subscribe to a ship notification) against a specific resource (a planned capability), phrased so it is unmistakably distinct from capabilities_list, which only enumerates them. An agent knows exactly what this tool accomplishes 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?

"Ask the human first" and "Needs the read scope" give a clear consent and prerequisite condition, and "planned capability" implies the item is not yet shipped. It stops short of naming the alternative workflow (e.g. call capabilities_list first to obtain the id) or stating when not to use it.

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

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

Goes well past the annotations: it discloses the duration limit, the required write scope, where the artifact lands (next to the source) versus what streams back inline, and the budget hold/release lifecycle including that it is free. Annotations only supply readOnlyHint=false and destructiveHint=false, so the description carries the meaningful operational detail.

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

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

Four sentences, purpose front-loaded, each carrying distinct information (what, where it lands, cost mechanics, permission requirement). The telegraphic 'Free:' clause is slightly compressed but is immediately unpacked by the following sentence, so nothing is wasted.

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

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

For a write-producing tool with an output schema already present, the description supplies everything an agent needs: scope requirement, size limit, cost ceiling and hold behavior, output location, and inline return. Return-value details are correctly left to the 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%, so the baseline is 3, but the description adds semantics the schema does not state: the budget is held during execution and released (i.e., not necessarily consumed), and the media_key is scoped to media 'in the media library' from an upload. The 'names' parameter is left entirely to the schema.

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

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

States a precise verb and resource ('Transcribe a video or audio file in the media library') plus the concrete output artifact ('word-timed .srt or .vtt'), which no sibling tool produces. An agent can distinguish this from probe_media or generate_* tools 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 real eligibility constraints — 20-minute cap, requires the write scope, budget must be within default 2 / max 10 — which tells the agent when this call can succeed. There is no sibling transcription alternative to route against, so the absence of explicit when-not guidance is a minor gap rather than an omission.

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

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

Annotations only declare write-capable, non-destructive, and open-world. The description adds real behavioral context the annotations cannot carry: the budget is held during the run and released, default 2/max 10 USD, and a write scope is required. It stops short of saying where the resulting media key lives or whether it persists.

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

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

One tight paragraph that front-loads what gets drawn and the output format before the cost/scope caveats. Every clause earns its place despite the parenthetical density.

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 described, and the definition covers output format, cost model, scope requirement, and the reply-thread option. Minor gap: no mention of failure modes or what happens if the post is private/deleted.

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

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

Schema description coverage is 100%, so the schema already documents url, theme, thread, variant, and budgetUsd. The description restates theme (dark/light), thread (draw the replied-to post), and the budget default/max without adding syntax or format detail 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 verb (Draw/capture) plus resource (a public x.com post) and the exact output artifact (1080px-wide PNG media key), listing the rendered elements. This clearly distinguishes it from rendering siblings like screenshot_page or render_carousel.

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?

Implies usage context (public posts, needs the write scope, free budget model) but never states when to pick this over screenshot_page or render_thumbnail. The 'Needs the write scope' line is useful gating info, yet no explicit alternatives or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered; the description adds the auth requirement ('Needs the read scope') and flags which attributes are meaningful (voice direction, locked parts). That is real context beyond the structured fields, though there is no detail on result size or ordering.

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 compact sentences, front-loaded with what the resource is and then the workflow instruction. Every clause earns its place, though the em-dash sub-clause about `voiceDescription` makes the second sentence fairly dense.

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

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

An output schema exists, so return shape need not be restated, and the description supplies the remaining essentials: the read scope requirement and the key field to inspect. For a parameterless read tool this is close to complete, with only minor gaps around ordering or pagination.

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 schema cannot carry semantic weight and the baseline is 4. The description correctly implies a whole-account listing with no filtering argument, matching the empty input schema.

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

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

States a specific verb (list) and resource (the account's actors) and enumerates what each entry carries: identity, voice, and locked parts. It also names a concrete field (`voiceDescription`) the agent will encounter, which goes beyond a generic 'list actors' label. It doesn't explicitly disambiguate from the sibling `characters_voice`, though the nearby mention of 'designing another' voice implies the distinction.

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 actionable when-to-use guidance: read `voiceDescription` before designing another voice and reuse the actor that already fits, which frames this as the lookup step preceding a voice-design action. It also states the prerequisite ('Needs the read scope'). No explicit when-not or named alternative tool, so it stops short of 5.

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

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

Goes well beyond the annotations: it discloses that the call SPENDS CREDIT, requires the write scope (auth prerequisite), and returns the voice id, a preview clip and the cost. It also explains the persistence side effect that the design is kept on the character for reuse. These are exactly the behavioral facts annotations cannot convey.

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

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

Three dense sentences, front-loaded with the credit cost and scope, then the two modes, then the return shape. No filler; every clause carries a distinct fact.

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 needn't be enumerated, but the description still summarizes them. Combined with cost, auth scope and the two parameter paths, an agent has everything needed to invoke this destructive, credit-consuming tool 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 parameter documentation already exists. The description still adds meaning beyond it: consent is framed as the user's own attestation of rights (not just a flag), and description is explained as durable casting direction reused on later runs rather than a throwaway prompt.

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 ('gives an actor a voice') and immediately distinguishes the two operating modes: designing a voice from casting direction versus cloning from a sample. An agent can also tell it apart from the read-only sibling characters_list, which is named for the character identifier.

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 clearly routes between the two paths ('description designs one...; sampleMediaKey clones a real voice and requires consent: true'), which is genuine when-to-use guidance. It stops short of stating when not to use the tool or naming a sibling alternative for voice work, so it is clear context but not full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description usefully adds a cost model (budgetUsd held during the run then released) and an auth prerequisite ('Needs the write scope'), but it leaves the tension between a read-only tool and a write-scope requirement unexplained, which can mislead an agent about whether anything is mutated.

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

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

Three short sentences with the return content front-loaded, and the cost/scope caveats placed after. The staccato 'Free: ...' fragment is slightly awkward but nothing is wasteful or padded.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile; the description fills the remaining gaps (cost mechanics, credential scope). What is missing is routing guidance against sibling trending tools, which keeps it from a 5.

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

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

Schema description coverage is 100%, so both parameters (budgetUsd default/max, community values) are already fully documented in the schema. The description repeats the budget default and max without adding syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific resource and scope ('the live top of Hacker News or of a subreddit's hot ranking, with scores'), which is unique among siblings like x_pulse and news_search and lets an agent tell what it returns. The verb is only implicit (a fetch/list), and no sibling is named for contrast, so it falls short of a 5.

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

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

Usage is implied by the domain ('what a community upvotes'), but there is no explicit when-to-use, when-not, or pointer to an alternative (e.g. x_pulse/current_pulse for other trend sources). The agent must infer that this is the tool for HN/subreddit rankings rather than being told.

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

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

Goes well beyond the annotations (readOnlyHint/openWorldHint) by disclosing the cost model (~$0.007 per call), the budget cap behavior (default 2, max 10), the chargedUsd cost readout, and an auth requirement ('Needs the write scope'). These are exactly the operational facts an agent needs before spending credit on a call.

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

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

Purpose is front-loaded in the opening clause, and each subsequent clause carries a distinct payload (semantic contrast, cost, budget, scope). The second sentence is dense and slightly run-on across cost/budget/auth, 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 present, return values need not be explained, and the description still names chargedUsd as cost feedback. For a credit-consuming search tool it covers purpose, cost, budget, and auth scope adequately; only explicit sibling routing is missing.

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

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

Schema description coverage is 100%, so the schema already documents query, budgetUsd, and within_days; baseline is 3. The description adds color on the budget default/max and the chargedUsd cost feedback, but adds no semantics for within_days and repeats budget details already in the schema.

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

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

States a specific verb and resource ('Semantic search for pages and LinkedIn or X posts') and crisply distinguishes itself from keyword tools with 'mean what you describe rather than match its words.' It does not name a specific sibling (e.g., web_search) as the contrast point, so the differentiation is conceptual rather than explicit.

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?

Conveys the usage mode well — 'describe a persona saying or feeling something' implies when this tool fits — but never states when to prefer it over keyword search siblings or when not to use it. Usage is implied rather than spelled out as an explicit condition/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?

Adds substantial context beyond the annotations: 15-minute expiry, session/identity constraint ('works only signed in as this account'), the write-scope requirement, and the post-click sequence (browser OAuth, then the account appears in connections_list). These are exactly the operational facts an agent needs and none are in the annotations.

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

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

Three dense sentences, all front-loaded: what the URL is, the sibling relationship, then the lifetime/auth/post-click facts. Every clause earns its place with no filler.

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

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

An output schema exists, so return values need no explanation. The description covers lifetime, auth precondition, permission scope, and the follow-on flow, which is everything needed to call a single-parameter URL-minting tool 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?

There is one parameter and schema coverage is 100%; the schema already explains it is 'a platform id from platforms_list with oauth: true.' The description adds no parameter-level detail, so the baseline 3 applies when the schema carries the semantics.

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 purpose: producing 'the one URL the human clicks to connect a social account on a platform.' It explicitly distinguishes itself from connections_list by noting that tool already carries one link per missing platform, so an agent can route between them without opening either schema.

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

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

Gives clear context for use: you call this to obtain the clickable connect URL for a human, and it works 'only signed in as this account.' The connections_list reference clarifies the relationship. It stops short of an explicit when-not-to-use or named alternative, so it lands at 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true, non-destructive and closed-world, so the safety bar is met structurally. The description adds substantive context beyond that: credentials are never returned ('identity only, no tokens') and the read-scope auth requirement. It omits nothing critical for a zero-param read.

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 resource, then the two special entry types, then the imperative and the scope requirement. Dense but every clause carries information; only the internal em-dash/colon nesting slightly slows parsing.

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-value shape need not be restated, and the description covers the remaining agent-facing concerns: what kinds of entries appear, what to do with a link, and the required scope. Nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, so per the rubric this is the baseline 4. The description adds no parameter detail because none is needed.

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+resource ('Connected social accounts') and enumerates what the listing contains: identity-only accounts plus `connect` links for platforms with no live account and `reconnect` entries for expired ones. It is specific enough to distinguish from connections_link, though the mixed-purpose wording ('plus connect/reconnect') takes a reading to parse.

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

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

Gives a clear usage instruction for the actionable case ('Hand the link to the human') and a prerequisite ('Needs the read scope'). It does not explicitly name connections_link as the alternative for the link-generation path, so routing between the two siblings is left partly to inference.

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

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

Adds substantial context beyond the annotations: explicit credit spend (~$0.06 engine cost plus plan margin), the budgetUsd cap and its default/max, and the chargedUsd reporting of actual cost, plus the write-scope requirement — all reconciling with readOnlyHint=false. The destructiveHint=true is left unexplained (nothing here indicates what, if anything, is mutated or lost), which is the one behavioral gap.

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

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

Front-loads the operation and flags the cost warning early with 'SPENDS CREDIT:', and every clause carries information. It is dense to the point of being hard to parse in the first sentence ('How much X is talking about 2 to 6 short phrases right now: …'), and 'billed with the plan's margin' is marginal detail, but nothing is padding.

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

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

With an output schema present and 100% parameter coverage, the description only needs to cover invocation context — and it covers cost, budget and auth scope well. The remaining critical gap is tool selection: an agent choosing between current_pulse and x_pulse gets no signal here, and the '2 to 6' phrase count conflicts with the schema.

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

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

Schema coverage is 100%, so baseline is 3; the description restates budgetUsd's default/max (matching the schema, so little added value) and mentions the non-parameter chargedUsd output. It also claims '2 to 6 short phrases', which conflicts with the schema's minItems: 1 — a mismatch that could mislead rather than clarify.

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

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

Names a specific verb/resource combination ('measure how much X is talking about phrases right now') and enumerates the concrete outputs (7-day volume, per-day counts, velocity, sample posts, wave flag), so the agent knows exactly what it produces. However, it never distinguishes itself from the near-identical sibling x_pulse (nor community_hot/related_trends), which is exactly the differentiation a 5 requires.

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

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

Prerequisites are stated ('Needs the write scope') and operational bounds are given (budgetUsd default 2, max 10), which tells the agent how to call it safely. But there is no 'use this when…' / 'use x_pulse instead when…' routing or any exclusion, so the choice between this and the sibling x_pulse is left entirely 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 declare readOnly=false, openWorld=true, destructive=false; the description goes well beyond them by disclosing cost semantics (budgetUsd held while it runs and released), the required write scope, login-wall capture behavior, and the rendered output (MP4 with following cursor and camera). This is exactly the kind of behavioral detail annotations cannot convey.

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

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

The description is front-loaded with the core mechanism before the caveats, and each clause carries distinct information (mechanism, output, login behavior, cost, auth). It is a bit dense and could break the budget/scope sentence out, but there is no filler.

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

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

With an output schema present the description needn't explain return values yet it still characterizes the MP4 output, and it covers auth scope, cost mechanics, and the login-wall edge case. The only gap is the missing differentiation from the record_page/screenshot_page siblings, which matters for correct selection.

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

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

Schema description coverage is 100%, so every parameter is already documented, establishing a baseline of 3. The description echoes the budgetUsd default/max and the action vocabulary (type, click, hover, scroll, wait) but adds little syntax or format detail beyond what the schema already provides.

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

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

The description names a specific verb and resource ('A real browser opens a URL and performs the steps you name... returns an MP4 media key'), which clearly distinguishes it from a static screenshot tool. However, it never references its close siblings record_page or screenshot_page, so the agent must infer the boundary rather than being told.

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 useful caveat ('A page behind a login demos as its login wall') and states the write-scope requirement, which implicitly signals when it is callable. But there is no explicit when-to-use-vs-alternatives guidance against the overlapping record_page/screenshot_page siblings, leaving the choice to inference.

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

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

Goes well beyond the annotations: it discloses the auth requirement ('Needs the write scope'), the cost behavior ('budgetUsd ... is held while it runs and released'), and that plan: true performs a dry read without rendering. It also signals the operation is non-destructive by producing a new media key rather than altering the source, which corroborates destructiveHint=false.

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

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

Front-loads the core action and output, then layers capability, prerequisites, and cost. Every sentence conveys information, but the long feature list ('reframes to 9:16, tightens pauses, burns in captions, lays music and places overlays, a logo and a look') makes it dense and slightly sprawling for an opening paragraph.

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 33-parameter mutation with an output schema, the description supplies the essential operator context: probe_media first, plan-then-render loop, write scope, and budget semantics. Return values need not be explained since an output schema exists. It does not hint at which parameter families are mutually exclusive or ordering, but the exhaustive schema covers those.

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 33 parameters are exhaustively documented in the schema, so the schema does the heavy lifting. The description only references a few names (keep_text, keep_ranges, remove_ranges, budgetUsd, plan) at a high level without adding syntax or constraints 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 verb and resource ('Cut a video in the media library') and enumerates the concrete forms it accepts (an upload, a generated or found clip, a render), then names the output ('a new media key'). This is clearly distinguishable from siblings like generate_footage, render_thumbnail, or probe_media.

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 strong prerequisite and workflow: 'Run probe_media first' and 'plan: true reads the paper edit back before rendering.' It also frames the two edit modes (keep_text from the transcript vs keep_ranges/remove_ranges for seconds), so context is clear. It stops short of naming an explicit sibling alternative or a when-not-to-use condition for the tool itself.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so the description doesn't need to restate the write/safety profile. It adds genuine non-obvious behavior instead: that a budget is held while the call runs and released afterward, and that the fetched asset stays reference material by default. It doesn't describe failure/refund behavior if the fetch fails, which keeps it from a 5.

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

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

Three sentences, front-loaded with the action and media types, then scope/cost facts. Every sentence carries information; no filler. Slightly terse on routing, but 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?

An output schema exists, so return values need not be explained. Combined with annotations covering safety and the schema covering params, the description supplies the remaining context an agent needs: cost handling, access scope, and the reference-vs-publish stance. Only the sibling-routing guidance 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 all three parameters are already documented, including the budget default/max and the enum semantics for 'purpose'. The description mostly restates those (the budget hold, the reference-material default). Baseline 3 is correct when the schema carries the parameter documentation.

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: pull an image, video, audio file or PDF at a public URL into the media library as a media key. The media types and the resulting artifact ('media key') make the operation unambiguous. It does not explicitly name or contrast a sibling (e.g. assets_upload), so it falls short of a 5.

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

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

'A fetched file is reference material until you know you may republish it' gives useful framing about intent, and 'Needs the write scope' is a real precondition. However, it never says when to pick this over the nearby siblings assets_upload, reference_search, or list_page_assets, leaving the routing decision 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 readOnly/openWorld/non-destructive, but the description adds substantial behavior beyond them: the per-call cost (~$0.001), the budgetUsd cap semantics, the chargedUsd return field, and an auth requirement ('Needs the write scope'). The write-scope note sits in mild tension with readOnlyHint but describes authorization, not mutation, so it is not a true contradiction.

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

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

Three dense sentences, front-loaded with purpose and scale, then output shape, then cost/budget/auth. Every clause carries information; nothing is padding.

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

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

For a search tool with an output schema, full param coverage and rich annotations, the description supplies the remaining agent-relevant context: the citation-integrity caveat and the cost/budget model. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all five parameters with descriptions. The description restates budgetUsd defaults/max but adds no new parameter semantics (min_year, min_citations, max_results are untouched). Baseline 3 is appropriate when the schema does the work.

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

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

States a specific verb and resource — semantic search over 322M scholarly works — and describes the exact input ('a claim or topic in') and output shape ('title, year, citation count, venue, url and abstract'). This clearly distinguishes it from media-search siblings like find_photo/find_footage and from web_search, all 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?

Usage is implied by the framing ('a claim or topic in, works out') and the downstream caveat 'Cite only what the abstract supports', but no alternative sibling is named and no explicit when-to-use/when-not condition is given (e.g. vs web_search or news_search). Adequate but leaves routing 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 declare readOnlyHint=false and openWorldHint=true; the description supplies far more: a sourcing preference order (Wikipedia free-license portrait, else self-published photo), a cost model (~$0.007, credit-funded), a budget cap with default and maximum, the chargedUsd reporting, licensing/attribution obligations, and a required write scope. This is exactly the 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?

Four sentences, front-loaded with the action and sourcing rule, then disambiguation, licensing, and cost. Every sentence carries information, though 'a fraction of a cent' is redundant next to the explicit '$0.007' and the cost/auth clauses are densely packed.

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?

Output schema exists, so return values need not be spelled out, yet the description still flags chargedUsd and attributionRequired as things to act on. Combined with auth scope, budget cap, licensing constraints, and the disambiguation rule, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100%, so all four parameters, including defaults and max for budgetUsd and the 0-based wrapping of variant, are already documented in the schema. The description largely restates that (about for namesakes, budget default/max), adding only the per-call cost figure. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource with scope baked in: fetch a real photograph of a named person into the media library. The 'named person' scope inherently separates it from sibling asset tools like find_photo, find_footage, and generate_image, which deal with non-person or synthetic imagery.

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

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

Gives concrete usage conditions: pass 'about' when the name is common so namesakes are disambiguated, and restrict output to static use with attribution when attributionRequired is true. It stops short of naming alternatives or stating when-not-to-use (e.g., for non-person imagery), so it is clear context without explicit routing.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, but the description adds real value beyond them: the budgetUsd hold-and-release mechanic, the explicit 'Needs the write scope' auth requirement, and the B-roll restriction. It says less about failure/refund behavior or what happens on partial matches, which keeps it short of a 5.

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

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

Terse, front-loaded with the action, then constraints, then cost/auth. Every clause carries information, though the long parenthetical source list makes the opening sentence dense.

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

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

With an output schema present, return values need no explanation, and the annotations plus description cover the write/scope and cost profile. For a mutation tool with an external budget, it is nearly complete, missing only explicit routing to sibling generation tools.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including source enums and orientation behavior. The description largely restates budgetUsd's default/max and the query word-count guidance already in the schema, adding no new syntax or edge-case meaning, so the 3 baseline holds.

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 (fetch one licensed video clip) and resource, enumerates the source libraries, and notes the destination (media library as a media key). An agent can distinguish this from generate_footage or edit_footage without reading 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?

Provides concrete constraints (B-roll only, no faces/logos/branded property; search in two to four words) that imply appropriate usage, but never names an alternative such as generate_footage, edit_footage or find_photo or states when to prefer them. Usage is implied, not routed.

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

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

Adds substantial behavior beyond annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false): the write-scope auth requirement, the budget hold-and-release cost semantics, and the licensing/attribution obligation ('credit it when attributionRequired is true'). These are exactly the operational facts an agent needs and are not derivable from structured fields.

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

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

Three dense sentences, front-loaded with the core action and value, then licensing, then cost/scope. No filler, though the 'Free:' lead-in to the budget sentence reads awkwardly and forces a re-read of the pricing claim.

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 auth scope, cost behavior, and licensing. The main omission is explicit routing guidance versus generate_image/find_footage, which is the one thing an agent still has to guess.

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

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

Schema description coverage is 100%, so the schema already documents query, source, variant, budgetUsd, and orientation in detail. The description only restates the budget default/max already in the schema and adds no new syntax or format guidance, 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 ('Fetch one licensed real photograph ... or a blank meme template into the media library as a media key'), naming the value produced. It is clearly distinguishable from generation siblings (generate_image, generate_footage) and video siblings (find_footage) by the 'real, licensed' qualifier.

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?

Implied usage is present: this is for real licensed stock/Pixabay photos or meme templates rather than generated content, and the source enum contextualizes the choice. However, it never explicitly says when to choose this over generate_image or find_footage, nor any exclusion conditions, so the agent must infer the routing.

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

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

Goes well past the annotations: exact credit cost (~$0.18 default), budgetUsd cap behavior, chargedUsd reporting, required write scope, SynthID watermark, and platform AI-labeling obligation. The destructiveHint=true annotation is corroborated by the explicit spend warning rather than contradicted.

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

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

Dense but front-loaded: the core action, the cheaper alternative, and the spend warning all come before the parameter caveats. Slightly run-on in the cost/watermark run of sentences, but each sentence carries distinct information.

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

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

For a paid, credit-spending, watermark-bearing generation tool, the description covers cost, cap mechanism, permissions, return handle ('Returns a media key'), and legal labeling. With an output schema present, it correctly avoids re-explaining the full return shape.

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; the description still adds value by tying parameters to aggregate economics ('about $0.18 of engine cost a default call', budgetUsd default 2/max 10) and by framing duration as something 'you will cut most of'. It largely echoes the schema's per-second pricing, so it does not reach a 5.

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

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

States a precise verb+resource+scope: 'Generate one short AI video clip from a prompt: one continuous camera move over one subject, silent unless with_audio'. It is clearly distinguishable from sibling find_footage (which it explicitly names) and from generate_image/edit_footage.

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

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

Routes explicitly: 'The dearest asset there is; try find_footage first', giving a when-not-this-tool condition. It also states when the with_audio variant is worth it ('when the clip sound IS the point: rain, a crowd, a machine').

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description goes well beyond them: it discloses the credit spend (~$0.016 per default call), that budgetUsd caps it (default 2, max 10), that chargedUsd reports actual cost, and that the write scope is required. This is exactly the cost/side-effect context an agent needs before invoking a paid mutation.

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 before the cost detail, and the credit/scope warnings are placed last where they belong. Slightly redundant with the schema on budgetUsd and the premium tier, but no sentence is wasted.

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

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

For a seven-parameter paid generation tool the description covers medium, sizing input, budget ceiling, output key handoff, and auth scope, and an output schema exists so return values need not be explained. The only real gap is the absence of explicit when-to-use-this-vs-find_photo/generate_footage routing.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, and the description largely restates it (budgetUsd default/max, premium as 'the dearer model'). It adds only marginal framing, e.g. that premium quality and reference_keys are discretionary, 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 ('Make one image from a prompt'), plus its key scope constraints (aspect ratio, up to 6 reference keys). An agent can tell it apart from generate_footage/render_thumbnail by the image medium and the prose-prompt requirement, 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 operational context ('in the aspect ratio of the platform it is for', 'put the key in posts_create mediaKeys', 'omit [reference_keys] for a purely imagined scene') but never states when to choose this over siblings like generate_footage, find_photo, or render_thumbnail. Usage is implied rather than routed.

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

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

Goes beyond annotations by disclosing the cost mechanism (budgetUsd held while running, then released, making the call free) and an auth requirement ('Needs the write scope'). Annotations already cover the read-only/open-world safety profile, so this supplementary context is a genuine add.

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 dense sentences with the output inventory front-loaded, followed by the operational cost/scope notes. No filler; every clause carries information.

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

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

With an output schema present and 100% schema coverage for the three params (including the viewport enum), the description need not restate return shapes or param syntax. It covers what is read, cost, and auth, which is everything an agent needs to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds real meaning: it clarifies budgetUsd is held and released (net free), not a charge, and that the read reflects the visitor's view. Defaults and max repeat the schema but the semantics do not.

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

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

States a specific verb+resource (read a page's visual identity) and enumerates the concrete outputs: heading/body typefaces, palette by role as hex, button radius, logo. This distinguishes it cleanly from siblings like read_page, screenshot_page, and list_page_assets.

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?

Implied context is present ('measured as a visitor sees it', free with a budget cap), but no explicit when-to-use vs alternatives. It never names read_page or screenshot_page as the alternative for the non-style case, leaving selection to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds a useful auth note ('Needs the read scope') and outlines the return content, but does not cover pagination, clipping thresholds, or error behavior. With annotations carrying the safety burden, a 3 is appropriate.

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 tightly packed sentences: the return contents come first, then routing alternates and the scope requirement. No filler and nothing redundant.

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

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

An output schema exists, so return values need not be re-explained, and the description nonetheless previews the brief's contents. Combined with annotations covering safety and the routing to siblings, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% and the single 'id' parameter is documented in the schema as 'The job id.' The description adds nothing about id format or sourcing beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Compact context for continuing a conversation') and enumerates exactly what the brief contains (clipped last messages, artifact inventory, post statuses, web url). It explicitly names the sibling tools jobs_get and jobs_continue, so an agent can distinguish it without opening schemas.

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

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

Routes the agent directly: use jobs_get for the full transcript and jobs_continue to reply, which frames this tool as the compact middle-ground. It also states the prerequisite ('Needs the read scope'), covering both alternative selection and access requirement.

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 mark this as a non-read-only, non-destructive, closed-world mutation, so the safety profile is covered. The description adds genuinely useful context beyond them: it requires the write scope (auth prerequisite) and that resuming carries full history. It stops short of saying whether the message re-triggers execution or what the budget/pause interactions are.

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

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

Two tight sentences, no filler, with the core action front-loaded and the resume use case plus the auth requirement trailing. Every clause carries information an agent needs.

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

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

With an output schema present, return values need not be described, and the write scope, resume semantics and attachment capability are stated. Minor gaps remain around side effects of continuing a run (whether it consumes budget or resets state), but the definition is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so every parameter (id, text, model, autoRun, budgetUsd, mediaKeys) is already documented in the schema, including the 4000-char limit and model list. The description only alludes to 'files attached' (mediaKeys) and adds nothing further, 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 ('Send another message to a job') and adds a second distinct purpose ('resume a stuck or failed run with full history'), which an agent could not infer from the name alone. It does not name the sibling it is not (jobs_run / jobs_create), so it falls short of the 5-level sibling differentiation.

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

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

Gives a clear usage condition: this is the tool for resuming a stuck or failed run with full history preserved. However, it never contrasts with jobs_run (start a fresh run) or jobs_create, and states no when-not-to-use or prerequisite checks beyond the write scope.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so safety is partly covered. The description still adds real value: the run persists server-side after the call returns, it yields a job id and web url for polling, and it requires the write scope. It does not mention rate limits, budget enforcement, or what happens when the run fails.

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

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

Three tight sentences with zero waste. The core action is front-loaded, the persistence behavior follows, and the scope requirement closes it out.

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 spelled out, and annotations cover the safety profile. The description supplies the async persistence model and auth scope, leaving only minor gaps around failure behavior and cost/budget semantics.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only adds that files may be attached, which loosely maps to mediaKeys; it says nothing about goal, model, autoRun, budgetUsd, or characters beyond what the schema already explains in detail.

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

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

States a specific verb and resource ("Start a durable job from a goal") plus the optional attachment capability, which is enough to identify the operation. It hints at the async lifecycle ("the run keeps going server-side") but never names the sibling tools that consume the returned job id (jobs_get, jobs_continue, jobs_run), so it stops short of full sibling differentiation.

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?

"Needs the write scope" gives a clear prerequisite, and the durable/server-side framing implies this is the async entry point. But there is no explicit when-to-use versus jobs_run, jobs_continue, or jobs_brief, and no when-not-to-use guidance for an 8-parameter tool with a rich sibling set.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and a non-open-world scope, so the safety profile is covered. The description adds real value on top: it discloses the returned fields and the read-scope auth requirement. It doesn't mention size/cost or truncation behavior for large transcripts, which keeps it short of a 5.

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

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

Three compact sentences, each carrying distinct information: payload, routing alternative, prerequisite. Front-loaded with the result shape and free of 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, the description needn't explain return values yet still summarizes them, and it covers the read-only nature, the auth prerequisite, and the sibling routing. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the schema documents the single 'id' parameter, so the description's job here is marginal. It doesn't add format, source, or lookup guidance for the job id (e.g., where ids come from), so baseline 3 is correct.

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

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

Names a specific verb and resource ('One job in full') and enumerates the payload (transcript, running/idle status, outputs with queue state and media, web url), so the agent knows exactly what comes back. It explicitly differentiates itself from the sibling jobs_brief.

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

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

States the alternative ('Use jobs_brief when you only need enough to reply') and the condition that selects it, plus a prerequisite ('Needs the read scope'). Nothing about when to pick this over jobs_brief is left to inference.

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

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

Annotations already declare readOnlyHint=true/openWorldHint=false, so the safety profile is covered; the description adds real context beyond them: 200-per-page size, newest-first ordering, the cursor contract (non-null nextCursor means older jobs exist), and the required read scope. It stops short of return-shape or rate-limit detail, which the output schema partially covers.

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

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

Three tight clauses, front-loaded with purpose and pagination contract, zero filler. Every sentence carries usable 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 present, return values need not be explained, and the description still covers ordering, page size, pagination mechanics, and auth scope. Only the `origin` filter goes unmentioned, which the schema handles.

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

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

Schema description coverage is 100%, so the schema already documents both params; baseline 3 applies. The description reinforces the `before` cursor's origin from nextCursor but says nothing about the `origin` filter, adding only marginal value over the schema.

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

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

Clear specific verb+resource ("List jobs") with extra scope detail: liveness, web url, page size, ordering. However, it never distinguishes itself from sibling listing/reading tools such as jobs_get, jobs_tail, or jobs_brief, so the agent must infer the boundary.

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

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

Usage is implied by the listing semantics and the description gives operational guidance (pass nextCursor back as `before`, needs the read scope), but it offers no explicit when-to-use vs alternatives or when-not-to-use conditions relative to jobs_tail/jobs_get/jobs_brief.

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 it a non-read-only, non-destructive, open-world operation. The description adds context annotations can't: it is an approval action a headless caller must supply, requires the write scope, and produces drafts rather than live deliverables. Only the failure/edge behavior (e.g., no pending plan) is unstated.

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

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

Three sentences, front-loaded with the action and followed by the trigger and prerequisite. The 'approval click a headless caller has nobody to make' phrasing is evocative but still carries information about the intended caller.

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 action, trigger, auth scope, and the draft nature of outputs. Missing only edge-case behavior such as what happens when no plan is pending.

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 id and budgetUsd are already documented in the schema; baseline 3 applies. The description neither adds format guidance for the id nor explains the budget parameter's effect on the run.

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 pair: approving/running the job's newest proposed plan, which is clearly distinct from siblings like jobs_continue (resume work) or posts_approve (approve a post). The 'newest proposed plan' narrowing tells the agent exactly which artifact is acted on.

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

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

"Use it after a turn ended with a plan waiting" gives an explicit triggering condition, so the agent knows when to fire it. It does not name an alternative tool or state a when-not case, which keeps it short of a 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the write-scope requirement, which is genuine value beyond annotations, but it omits what stopping does to the job's state, whether it is reversible, or whether partial results are preserved.

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

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

Two terse sentences with zero filler; the action and the auth requirement are both front-loaded and 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 write-scope note covers the main implicit prerequisite for this mutation. Only the behavioral consequences of stopping a job remain unstated, which is a minor gap for a simple action 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?

There is a single parameter 'id' that the schema fully documents at 100% coverage, so the description need not elaborate. It adds no meaning beyond the schema, which is the expected baseline for a fully-covered single-parameter 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+resource combination ('Stop a running job') that is instantly distinguishable from siblings like jobs_run or jobs_continue. It does not explicitly name those siblings, but the action 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?

'Stop a running job' implies the usage condition, but there is no explicit when-to-use guidance, no mention of prerequisites such as the job actually being in a running state, and no reference to alternatives like jobs_continue for resuming.

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, non-destructive, closed-world behavior, but the description goes further by disclosing the replay-then-live flow, exact stop conditions (run end, 60 seconds, 200 events), the return shape, cursor-resume semantics, the meaning of live:false, and the required read scope.

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 tightly structured: core behavior first, then return/resume, then fallback, then prerequisite. Every sentence adds necessary information with no redundancy.

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

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

For a live-streaming watcher with rich schema and an output schema already present, the description covers all an agent needs: trigger semantics, stop conditions, resume mechanics, failure fallback, and auth requirements. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces cursor behavior and the 60-second cap, but adds no new syntax, format, or constraints 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 opens with a specific verb and resource: 'Watch a job's run', then immediately defines the scope as replaying events from a cursor and following live until termination. It distinguishes itself from jobs_get by explicitly stating when no live stream is available.

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

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

It provides clear context for use and names jobs_get as the fallback when {live: false}. However, it does not explicitly compare itself to other sibling tools like jobs_list or jobs_get for general live-run monitoring, leaving some alternative routing implicit.

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

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

Beyond the annotations, the description discloses real behavioral traits: the tool is free, the budgetUsd amount is held while it runs and released, the result is a verified token safe to paste, and it requires a write OAuth scope. The 'Needs the write scope' note sits in mild tension with readOnlyHint=true, but it describes an auth requirement rather than a state mutation, so it is not a direct contradiction.

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

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

Three compact sentences with no filler; the output artifact is front-loaded and the cost/auth caveats follow. The first sentence is dense with an inline URN example but remains readable.

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

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

For a two-parameter lookup with an output schema and read-only annotations, the definition covers purpose, cost behavior, auth scope, and usage constraint. Return-format detail is not required since an output schema exists, so the description is nearly complete; the only soft spot is the unexplained 'write scope' requirement.

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. The description adds meaning beyond the schema by explaining that budgetUsd is held while the call runs and then released, and by characterizing what the query accepts (a large company name or topic keywords), which goes past the schema's example strings.

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

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

The description states a specific resource and output: the verified LinkedIn mention token (e.g. @[Microsoft](urn:li:organization:1035)) for a company, or companies for a topic. It is clearly distinguishable from siblings like posts_publish or find_photo. It leads with the noun/return artifact rather than a verb ('Look up X'), which slightly weakens the action framing.

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?

'Ready to paste into a LinkedIn post' implies the context of use, and 'Tag only a company it returns' constrains how results may be used. However, there is no explicit when-to-use vs when-not guidance and no alternative tool is named among the many siblings, so the agent must infer the scenario.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered; the description adds genuinely non-redundant behavior: the cost model ('Free', budgetUsd held while it runs and released) and the auth requirement ('Needs the write scope'). The write-scope note sits in tension with readOnlyHint and the 'Free' framing next to a held budget is slightly ambiguous, which keeps it from a 5.

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

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

Roughly 45 words, front-loaded with the resource and scope, then the handoff, then cost and auth. Nothing is padding, though the clipped telegraphic fragments ('fetch_asset the one you want', 'Free: ...') require a beat of parsing rather than reading cleanly.

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 explain return encoding, and it still adds useful output context (ordering, pixel sizes, per-asset purpose). Required param, cost behavior and auth scope are all covered, leaving only pagination/truncation (>40 entries) unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents url, viewport, budgetUsd and max_assets in full. The description only restates the budgetUsd default/max, and output-ordering facts like 'largest first' are not a parameter at all, so it adds little beyond the schema — the baseline 3 applies.

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

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

The description names the concrete resource returned (images, videos, logos, social preview card) plus its scope and ordering ('largest first, with real pixel sizes'), so an agent knows exactly what comes back. The verb 'list' is carried by the title rather than the description, and there is no explicit differentiation from near-neighbours like probe_media or screenshot_page, which keeps it just below a 5.

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

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

'fetch_asset the one you want' gives a clear follow-on action and effectively routes the agent to the correct sibling once the list is in hand. It states the intended workflow context but gives no exclusions or conditions for choosing this over probe_media or screenshot_page when the goal is merely to know what media exists.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds a real behavioral constraint the annotations do not capture: 'Needs the read scope,' i.e., an auth prerequisite. It stops short of saying what happens on a missing scope, but that is a minor gap.

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

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

Two short clauses, no filler: the identity/return summary is front-loaded and the auth requirement follows. Every clause carries information.

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

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

An output schema exists, so the description needn't enumerate return structure in detail; naming email, plan, and credit balance is sufficient orientation. The auth-scope caveat plus the safety annotations make this complete enough for a zero-parameter identity call, though a note on failure behavior when the scope is absent would close the last gap.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly avoids inventing parameter detail and instead spends its words on the returned fields, which is the appropriate emphasis for a parameterless call.

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

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

Names the exact resource (the credential's identity) and enumerates the concrete return fields: email, plan, credit balance. No sibling tool in the list does identity resolution, so the agent can distinguish it immediately 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?

The description implies the usage context (inspecting who the current credential is), but never states when to call it versus alternatives or under what conditions — e.g., as a preflight check before other calls. With no real sibling competitor, the absence of exclusions is less costly, but the 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?

Goes well beyond the annotations by disclosing the cost model (~$0.01 engine cost per default call, margin-billed), that budgetUsd caps spend (default 2, max 10), that chargedUsd reports actual cost, and that write scope is required. This explains why a search carries readOnlyHint=false and destructiveHint=true, resolving potential confusion.

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

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

Front-loads what the tool returns, then the freshness knob, then a prominently flagged cost/auth block. Efficient and well-ordered, though the mid-sentence cost clause is slightly dense.

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

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

An output schema exists so return format need not be spelled out, and the description covers cost, scope, and the freshness parameter adequately. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so all three parameters are already documented by the schema. The description restates within_days (window narrowing) and budgetUsd (default/max) plus adds chargedUsd context, but adds no syntax or format detail beyond the schema baseline.

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

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

States a specific verb and resource — fresh, dated journalism on a query — and scopes the source precisely: a curated news index with press-release wires filtered out. This distinguishes it from generic siblings like web_search or current_pulse without opening their schemas.

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

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

The scope note ('press-release wires filtered out') implies its niche versus other search tools, and 'Needs the write scope' flags a prerequisite. But it never explicitly names when to prefer this over web_search, current_pulse, or concept_search, so the agent must infer the choice.

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

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

Annotations only declare write/destructive/openWorld, but the description discloses the credit spend magnitude (~$0.06 engine cost, billed with plan margin), the budgetUsd cap semantics (default 2, max 10), the chargedUsd feedback field, and the required write scope. That is exactly the operational context an agent needs before committing to an irreversible spend.

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 integration, then cost/scope in a compact three-sentence block with no filler. The first sentence is densely packed with parentheticals, but every clause carries signal.

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 explain returns, yet it still names the key artifacts (media key, beat grid, chargedUsd) and covers cost, budget, and auth scope. For a paid, mutating, world-generating media tool, nothing material is missing.

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

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

Schema description coverage is 100% and the schema already spells out budgetUsd's default/max, allow_vocals' rationale, and duration_seconds' loop-repeating grid behavior. The description largely restates those same points (budget cap, style-as-input, beat-grid length), so it adds little 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 verb and resource ('generate an instrumental music bed') and immediately constrains it ('from a style ... never an artist'), which sharply distinguishes it from generate_image and generate_footage. The downstream artifact (media key plus beat grid) reinforces what the tool actually produces.

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 with the result ('Pass the key as edit_footage's music') and names the required write scope, which is real routing guidance. It lacks any explicit when-not-to-use or cost-alternative guidance (e.g. prefer find_footage when a free existing track suffices), so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint, destructiveHint false, and openWorldHint false. The description adds useful behavioral context beyond annotations by stating that it works with any key, including no scope, which addresses authentication requirements for the read operation.

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

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

Three compact sentences with no wasted words. The most important content, what the tool returns, is front-loaded, followed by when to use it and an auth caveat.

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

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

For a zero-parameter read-only list tool with an output schema, the description is complete enough. It explains the returned platform properties, provides the key usage prerequisite, and notes auth behavior, leaving no critical gap.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly does not waste space describing input parameters, and the empty schema fully covers the required input semantics.

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 exactly what the tool returns: every platform the rail posts to, with text limits, media rules, documentTitle requirements, first-comment support, and settings JSON Schema. It is specific and distinguishes itself from the sibling posts_create by telling the agent to read it beforehand.

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 usage context: 'Read it before posts_create' and notes that it works with any key (read scope or none). This is strong guidance, though it does not explicitly name when not to use it or contrast with unrelated 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 destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the mutation profile is covered. The description adds value beyond them by stating the concrete consequence (content goes out) and the auth requirement ('Needs the publish scope'), which an agent could not infer from annotations alone.

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

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

Two short clauses, zero waste, and the irreversible consequence is placed first for maximum salience. Nothing needs trimming and nothing important is buried.

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

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

With an output schema present, return values need not be described, and the auth scope plus publication consequence are covered. The only gap is absence of routing guidance relative to the closely named posts_publish sibling.

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

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

Only one parameter, and schema description coverage is 100% ('Post ids to approve'), so the schema already carries the meaning. The description adds no extra semantics about id format, how many ids are accepted, or behavior of unknown ids, 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 effect: approving moves proposals to the schedule and they will be published. The uppercase 'PUBLISHES CONTENT' front-loads the outcome clearly. It does not distinguish itself from the sibling posts_publish, which a reader may confuse with approval.

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

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

The description implies when the tool applies (turning proposals into scheduled, outgoing content), which is useful context. But it names no alternatives such as posts_publish or posts_dismiss, and gives no explicit condition for choosing approval over dismissal or direct publishing.

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 free-plan rate limit (10 posts/day), the 402 free_daily_cap reset behavior, the required 'publish' scope, and that the post lands in the account's next free queue slot. These are operationally critical facts the schema and annotations do not 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?

Dense and front-loaded with the core action first, then preconditions, then limits. The telegraphic style is efficient, though a few clauses ('at a time, in the account's next free queue slot, or now') are slightly compressed.

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

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

An output schema exists and annotations cover safety, so return format is not needed. The description supplies the missing prerequisites and rate-limit context; only the routing versus posts_publish/posts_approve is left 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 field descriptions are already rich, so the baseline is 3. The description mostly restates schema content (queue vs scheduledAt, settings via platforms_list) and adds only cross-tool references rather than new parameter semantics.

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

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

Opens with a specific verb+resource ('PUBLISHES CONTENT: puts a post you wrote on the rail') and names scope ('one connected account'). It is clear what it does, but it never differentiates itself from the sibling 'posts_publish' (or 'posts_approve'), which an agent must disambiguate against.

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 real preconditions: read platforms_list first for limits/settings schema, needs the publish scope, and describes the queue-vs-now-vs-scheduledAt selection. Lacks any explicit exclusion or contrast against sibling publishing tools.

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

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

Annotations already declare destructiveHint=true, but the description adds real value beyond them: exactly which states are affected vs. spared, and that write scope is required. It doesn't cover reversibility or rate/confirmation behavior, but with annotations carrying the destructive profile this is solid extra context.

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

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

Four short, front-loaded sentences. The eligible-state scope comes first, followed by the exclusion, the reason guidance, and the auth requirement. No sentence is padding.

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

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

For a destructive mutation with an output schema, the description covers scope, exclusion, auth, and optional-parameter intent, so an agent can call it correctly. Return values are handled by the output schema, leaving little missing.

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

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

Schema description coverage is 100%, so both parameters are already documented. The note 'Pass the user's reason when they gave one' reinforces the optionality of reason but adds little syntax or meaning beyond the schema's own 'if they said' description. Baseline 3 is appropriate.

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

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

States a specific verb (cancel/dismiss) and resource (posts) and enumerates the eligible states (proposed, scheduled, failed, handed-off). It implicitly differentiates from posts_publish by stating 'Nothing already publishing or published is touched,' but never names a sibling tool to route the agent between them.

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

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

Provides clear context for when the tool applies (cancel posts in the four pre-publish states) and an exclusion ('nothing already publishing or published'). It stops short of naming alternatives like posts_publish or posts_approve or stating any explicit when-not-to-use beyond the state filter.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real value by disclosing that the response is the post's *live* (fresh) state, that it includes a human-facing calendar url, and that a read scope is required — none of which is encoded in the annotations.

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

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

Two short sentences, front-loaded with the core purpose and followed by the return/auth detail. Nothing is padded and no sentence is redundant.

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