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, so the safety profile is partly covered; the description adds genuinely new context by disclosing the permission model (publish scope vs write) and flagging that autoPublishPosts removes human approval from publishing. It does not explain edit-overwrite semantics (whether omitted fields are cleared) or the replayed/idempotency behavior, which are the remaining gaps.

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

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

Two sentences, no filler, and the create-vs-edit rule is front-loaded ahead of the permission caveat. Every clause carries information an agent needs before calling.

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 annotations covering safety, the description only needs to cover mode selection and permission gating, which it does. For a 12-parameter mutation tool it is close to complete, though it says nothing about how edits treat unspecified fields or how autoPublishPosts interacts with connectionIds.

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 92%, so the schema already carries parameter meaning, including the autoPublishPosts danger note and the detailed idempotencyKey guidance. The description's mentions of id and autoPublishPosts largely restate what the schema says, adding scope requirements but little else beyond it. Baseline 3 applies.

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

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

The description names a specific verb and resource and splits the two operating modes by an observable signal: no id means create, an id means edit. That discriminator is stated up front, so an agent knows which behavior it will get before opening the schema, and no sibling (agents_list, agents_wake) offers competing create/edit semantics.

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 explicit routing logic between the two modes and states the prerequisite scopes (publish scope for autoPublishPosts, write for everything else). It stops short of naming alternatives or when not to use this tool, which keeps it out of the top band.

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?

Annotations only tell the agent this is a non-read-only, non-destructive, closed-world write; the description adds real behavior on top: the artifact is filed next to the source, the text is also returned inline, and the write scope is required. It also declares cost behavior ("Free: nothing is charged"), but that sits awkwardly against the budgetUsd parameter with a default of 2 and max of 10, leaving the actual billing semantics ambiguous.

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

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

Four short sentences with the core action front-loaded, then side effects, then cost, then auth. Every clause carries information an agent would otherwise have to guess at, and nothing is repeated.

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 does not need to enumerate return fields, and it still usefully notes that the transcript comes back inline alongside the file. Coverage of scope, duration limit, side effect, and auth makes it complete for a four-parameter tool; only the unresolved free-versus-budget conflict 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 media_key, names, format, and budgetUsd are already documented in structured data, which sets the baseline at 3. The description's only parameter-adjacent contribution is restating the srt/vtt options, and it never reconciles the "free" claim with the budget parameter, so it adds no new meaning beyond the schema.

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

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

"Transcribe a video or audio file in the media library ... into a word-timed .srt or .vtt" gives a specific verb, a specific input source, and concrete output artifacts. The 20-minute ceiling and the word-timing detail further pin down what this produces, so an agent can distinguish it from siblings like probe_media or edit_footage 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 establishes the context of use (an existing item in the media library, capped at 20 minutes) and states the prerequisite "Needs the write scope," which is actionable pre-call guidance. It stops short of naming when-not-to-use or an alternative sibling for longer files, so it is clear but not fully 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, destructiveHint=false, so the description's job is to add context, and it does: it discloses the output artifact type and dimensions, the auth scope required (write), and that the call is free of charge. It does not cover failure modes (private/deleted posts, rate limits) or how the returned media key is later consumed, which keeps it below a 5.

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

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

Front-loaded with the core action and output, followed by two short high-value sentences on cost and scope. The parenthetical field list is dense but efficiently conveys what the render contains. No filler sentences, though the phrasing is compressed to the point of being slightly cryptic ('media key').

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

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

An output schema exists, yet the description still helpfully characterizes the returned artifact, and annotations carry the safety profile, so the remaining burden is small. The agent knows the input format (confirmed by schema), the theme/thread options, the cost, and the required scope. Only edge-case behavior for private or unavailable posts is unaddressed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning for two parameters only ('dark or light' for theme, 'optionally under the post it replies to' for thread) and says nothing about variant or budgetUsd. It also asserts 'Free: nothing is charged' while a budgetUsd parameter with a $2 default and $10 cap exists, which is mildly confusing rather than contradictory.

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

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

Specific verb (draw/capture) and specific resource (a public x.com post), plus the concrete rendered output (1080px-wide PNG media key with avatar, name, text, media, date, counts). This clearly separates it from generic page capture siblings like screenshot_page or record_page, though those siblings are never named. Purpose is unambiguous 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?

Usage is implied rather than stated: you reach for this when you want a rendered X post card as an image asset. There is no explicit 'use this instead of screenshot_page when...' guidance despite several capture-adjacent siblings, and no when-not-to-use condition. The prerequisites ('Needs the write scope') are stated, which partially compensates.

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 that this is a non-read-only, open-world, destructive operation, and the description adds substantial behavioral detail beyond them: it spends credit, costs about $9.3 of engine cost on a default call, bills face-only likeness at about $0.10 per presenter second, takes 10 to 60 minutes, requires the write scope, and returns a media key. It also explains budget capping, chargedUsd reporting, and that max_usd can make the processor refuse a plan before spending. This is exactly the operational context an agent needs before invoking an expensive 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?

The description is dense but front-loaded: it starts with what the tool does, then modes, time, cost, and scope constraints. Every sentence carries useful information, though the cost discussion is repeated across the main description and multiple parameter notes. It is appropriately sized for a complex, expensive tool, but not maximally tight.

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

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

The tool is high-complexity, high-cost, and potentially destructive, and the description covers the critical gaps: spend magnitude, budget caps, runtime, output media key, write scope, and mode-specific behavior. An output schema exists, so return values need not be explained further, and the annotations already carry the safety profile. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: recording_media_key replaces the presenter and voice at no Omni cost, face_media_keys drives generated likeness, only_segment is the cheap probe, and max_usd/budgetUsd cap spend. It does not explain every parameter relationship, notably resume_from and name, but the cost and mode interactions it does explain go beyond the schema.

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

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

The description states a specific verb and resource: remake a reel at a URL with the account owner as presenter, preserving cuts, shots, timing, and captions. It also distinguishes the two operating modes (recording versus face-only likeness generation) and names measure_reel as the script source for recordings. An agent can identify exactly what this tool does without opening the schema.

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

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

It gives explicit conditions: only for a reel the user asked to copy, with their own face and voice, and recording_media_key required unless face_media_keys are provided. It also states that only_segment is the cheap probe before a full clone and that face-only generation is capped by max_usd and labelled AI-generated. Those constraints and exclusions make the correct use case unambiguous.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds two things annotations do not: cost behavior ('nothing is charged') and an auth prerequisite ('Needs the write scope'), which is genuinely useful since a read-only call requiring write scope would otherwise surprise the caller. It omits rate limits and how many items the 'top' contains, keeping it off a 5.

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

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

Three short sentences, front-loaded with what the tool returns, then cost, then the auth requirement in the position an agent needs it. There is little waste, though 'Free: nothing is charged' restates the same idea twice and would read tighter as a single clause.

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

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

An output schema exists, so return shape need not be explained, and the description covers the two things the schema cannot: that the call is free and that it requires write scope. For a two-parameter external-content read, that is close to sufficient; depth of the 'top' list and ranking semantics remain unstated.

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 both community and budgetUsd fully documented inline, so the schema carries parameter semantics and baseline 3 applies. The description reinforces the community dimension ('Hacker News or of a subreddit') but adds nothing new about budgetUsd, and its 'nothing is charged' claim sits awkwardly against a parameter whose documented default is $2.

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 exact resource and scope: the live top of Hacker News or a subreddit's hot ranking, and notes that scores are included. It is specific about what is returned at a glance. It stops short of distinguishing itself from plausibly similar siblings such as news_search, web_search, or related_trends, so an agent must infer the boundary.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The only selection signal is the implicit 'Free: nothing is charged', which hints this is a zero-cost option but never says to prefer it over a paid or broader search sibling. An agent choosing between this and news_search or web_search gets no routing 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?

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?

Goes well beyond the annotations by disclosing cost (~$0.06 default call, billed with margin), the budgetUsd cap (default 2, max 10), the chargedUsd return field, and the write-scope requirement. It does not explain why the tool carries destructiveHint=true beyond spending credit, which is a minor remaining gap.

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

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

Front-loads the core purpose in the first clause, then layers scale limits and the alternative before the cost details. Dense but each clause carries information; slightly crammed into two long sentences.

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

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

For a 2-param tool with an output schema and annotations covering the safety profile, the description covers purpose, scale, cost, budget control, and alternative routing. The only omission is the rationale for the destructive/write flag.

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

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

Schema coverage is 100%, so both parameters are already documented in structured form, including the budgetUsd default/max that the description repeats. The description adds the 'in seconds' timing nuance and the chargedUsd output hint, but adds little parameter meaning beyond the schema.

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

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

States a specific verb and resource: measures how much X is talking about 1-6 phrases, and enumerates outputs (7-day volume, per-day counts, velocity, sample posts, wave flag). It explicitly distinguishes itself from the sibling x_pulse ('to learn what people are saying, use x_pulse').

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

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

Names the alternative tool (x_pulse) and the exact condition that selects it (qualitative content vs. counts). Also bounds scope ('counts only, in seconds') so an agent knows what this tool will not return.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description discloses real-browser execution, the MP4 return type, the login-wall limitation, and the required write scope — meaningful context for a non-read-only, open-world tool. One flaw: it asserts "Free: nothing is charged" while the schema exposes budgetUsd with a default of 2 and a max of 10, a cost inconsistency the agent must resolve.

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

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

Four compact sentences, front-loaded with the mechanism and the return artifact, with caveats after. Some phrasing is soft ("drawn like a screen-recorded demo", "Free: nothing is charged") but nothing is genuinely wasteful for a tool of this complexity.

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 return shape needs no prose, and the description covers execution model, auth scope, and the login-wall failure mode. The only real gap is the unresolved tension between "Free" and the budgetUsd parameter, plus no note on step-count or runtime limits.

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

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

Schema description coverage is 100%, so every parameter including zoom, aspect, viewport, browser_bar, and budgetUsd is already documented in the schema. The description's step verb list (type, click, hover, scroll, wait) largely restates the steps parameter description rather than adding syntax or edge-case meaning. 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?

The description states a concrete verb+resource: a real browser opens a URL, executes named steps, and returns an MP4 media key. That output detail separates it from still-image siblings like screenshot_page or read_page. It never names record_page or other adjacent capture tools, so an agent must infer the boundary rather than read it.

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

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

Usage context is implied by the mechanism (a real browser driving a scripted flow) and the login-wall caveat tells the agent one situation where the result will be wrong. There is no explicit when-to-use versus record_page/screenshot_page/edit_footage guidance and no statement of when not to call 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?

Adds real context beyond the annotations: the result is a NEW media key (the source is not consumed), write scope is required, and plan mode performs no render. However, 'Free: nothing is charged' directly conflicts with the schema's budgetUsd ('default 2, max 10'), which will confuse an agent reasoning about cost; that internal inconsistency undercuts the transparency gain.

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

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

Four sentences, front-loaded with purpose, then feature surface, then required workflow, then cost and auth. Given a 33-parameter tool this is tight; the only soft spot is the vague clause 'lays music and places overlays, a logo and a look', which gestures rather than names.

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 tool this large, the description covers the four things an agent needs before calling: where the source comes from, the probe-first ordering, the plan-before-render loop, and the write scope. Return values need no explanation because an output schema exists, and nothing structural is missing — only the cost statement needs reconciling with budgetUsd.

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, but the description goes slightly further by naming the three mutually exclusive selection paths (keep_text as transcript beats vs keep_ranges/remove_ranges as seconds) in the header rather than leaving that discovery to a 33-param scan. It still adds no syntax or format detail beyond what the schema already carries.

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') plus the outcome ('get a new media key'), and enumerates the source kinds (upload, generated, found clip, render). It also distinguishes itself from siblings by making probe_media the input supplier and assets_list/find_footage the key sources, so an agent can separate it from generate_footage or clone_reel without opening a schema.

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

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

Gives an explicit ordering rule ('Run probe_media first') and a two-step workflow ('plan: true reads the paper edit back before rendering' then repeat to render). It also states the access prerequisite ('Needs the write scope'). What it omits is when to prefer alternatives or when not to use this call at all — no mention of the other editing/render 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description adds the write-scope requirement and a rights caveat that the import does not itself grant republishing rights. The statement 'Free: nothing is charged' sits awkwardly against the budgetUsd parameter (default 2, max 10), which implies a spend cap, creating mild ambiguity about cost behavior.

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 that front-load what the tool does, then the rights caveat, then cost and auth. Nothing is padded, though the 'Free: nothing is charged' line is potentially misleading given the budgetUsd parameter and would be better clarified or dropped.

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 still covers the artifact produced (a media key), the auth scope, the cost posture, and the rights caveat. For a three-parameter import tool that is sufficient for an agent to call it correctly.

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

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

Schema description coverage is 100%, so url, purpose, and budgetUsd are already documented, including the enum meaning. The description reinforces the 'media key' output but adds no new syntax, defaults, or format detail beyond the schema, so the baseline of 3 applies.

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

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

The description opens with 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') and names the accepted file types plus the resulting artifact. It does not explicitly distinguish itself from near-neighbours such as find_photo, generate_image, or references_add, so an agent must infer the difference from the wording alone.

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 real guidance on the consequences of importing, and 'Needs the write scope' sets a precondition. However, there is no explicit when-to-use versus alternatives guidance (e.g., fetch an existing URL vs. generate or search for media), leaving selection between siblings 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?

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?

With annotations supplying the safety profile, the description still adds real value: it discloses the side effect (a clip is deposited into the media library under a media key), the licensing status, and the required write scope. The one flaw is "Free: nothing is charged," which sits awkwardly against the budgetUsd parameter (default 2, max 10), leaving the agent unsure whether a spend can occur.

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

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

Front-loaded with the action and cardinality, then constraints, then cost, then auth. Every sentence carries information; no filler. It is a dense block rather than a structured list, which makes the exclusions and scope requirement slightly easy to skim past.

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

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

For a five-parameter, open-world fetch with an output schema and full annotation coverage, the description is nearly complete: action, constraints, licensing, side effect, and auth are all present. What is missing is behavior on empty results and clarification of the cost story given budgetUsd.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: it enumerates the shelves behind the source enum and translates them into content types (stock, archival, NASA, reaction GIFs), and it reinforces the two-to-four-word constraint on query. The free-vs-budgetUsd tension is the only ambiguity introduced.

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: "Fetch one licensed real video clip ... into the media library as a media key." It names the source shelves and, critically, the cardinality ("one"), which separates it from generate_footage, edit_footage and find_photo 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?

Clear context for use: B-roll only, two-to-four-word queries, no recognizable faces/logos/branded property, free, write scope required. It does not explicitly name the alternatives (e.g. generate_footage for synthetic clips or find_photo for stills) or state when-not-to-use beyond the content exclusion, so routing still requires inference from sibling names.

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 annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) the description discloses that a write scope is required, that every result carries a licence, and that attribution is mandatory when attributionRequired is true — exactly the kind of context annotations cannot express. Minor gap: 'Free: nothing is charged' sits awkwardly beside a budgetUsd parameter with a $2 default, leaving the agent unsure whether spending can occur.

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

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

Four short sentences, front-loaded with what is fetched and where it lands, followed by the licence/attribution obligation, cost, and auth scope. No filler and nothing 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile; the description fills in licensing, attribution, cost and scope. The only unresolved point is the apparent conflict between 'nothing is charged' and the budgetUsd parameter.

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

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

Schema description coverage is 100%, so the schema already explains query, source, variant, budgetUsd and orientation, and the description adds no syntax or selection detail for any of them. 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?

Specific verb ('Fetch') plus resource ('one licensed real photograph (stock or Pixabay) or a blank meme template') and a stated outcome ('into the media library as a media key'). The emphasis on 'real photograph' implicitly separates it from generate_image/find_footage, so an agent can route correctly 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?

Usage context is implied rather than stated: the 'real photograph' framing and the licence/attribution note tell the agent this is for licensed real imagery, but no alternative tool is named and no when-not condition is given. 'Needs the write scope' is the only explicit precondition.

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?

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), yet the description still adds real behavior: the call is free, it requires the read scope, and paid plans are billed at 3x versus 1x on the free plan. It also explains that already-held coverage means only gaps are paid for, which is genuinely non-obvious. No rate limits or cache lifetimes are mentioned, keeping it off a 5.

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

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

Purpose is front-loaded, but the body is a single comma-spliced run-on that stacks five output concepts and a pricing multiplier into one sentence. Every clause is substantive, yet the lack of separation makes it slow to parse.

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 did not need spelling out, but the description covers them anyway and adds the auth requirement plus the pricing multiplier. For an 8-parameter estimator with a sibling dependency, that is sufficient 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%, so the baseline is 3. The description nevertheless adds interpretation: capUsd is 'the most it can spend at these settings', which ties budgetUsd to the returned cap, and it flags that posts estimates report coveredFrom/coveredTo so the agent understands range versus gaps. It does not walk the remaining parameters (force, sinceMonths, maxItems) beyond what the schema already says.

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 the exact role: it prices what identity_expand would cost before it runs, which separates it cleanly from the sibling it estimates for. The noun set (estimateUsd, capUsd, alreadyHeld, sources) makes clear it is a read-only estimator rather than a puller.

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 phrase 'before it runs' tells the agent this is the pre-flight step for identity_expand, and 'Free' removes any cost hesitation about calling it. It never states when not to bother (e.g. if a recent estimate exists) or names any other alternative, so it falls short of a full when/when-not treatment.

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 a destructive, non-read-only, open-world write. The description adds substantial context beyond them: it spends credit, holds budgetUsd on the wallet first, charges only actual pull cost, gives fresh expansions cost 0 unless force, and states the write scope requirement. That is rich disclosure of cost, side effects, and auth preconditions for a destructive tool.

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

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

The cost warning is front-loaded ('SPENDS CREDIT.') and most sentences are dense with useful distinctions. The freshness-window parenthetical is somewhat compressed, but every sentence carries operational information and 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 destructive, credit-spending expansion tool with an output schema already defined, the description covers the critical unknowns: cost behavior, budget reservation, force semantics, auth scope, and expansion meanings. No essential calling information is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by explaining that fresh expansions cost 0 unless force, how the budget hold works, and that creators are ordered 'cheapest evidence first' – meaningful semantics not fully captured by the per-parameter descriptions.

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

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

States a specific verb and resource ('Grow one node by one expansion') and enumerates the seven expansion types, so an agent knows exactly what this tool produces. It also names the related pricing sibling (identity_estimate), distinguishing it from estimate/preview tools 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?

Explicitly says 'Price it first with identity_estimate' and 'Needs the write scope,' giving a clear precondition and alternative. It also implies the force/freshness condition for when a re-pull is needed, though it does not state explicit cases when this tool should not be used.

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, non-destructive, and closed-world behavior. The description adds meaningful context beyond annotations: authentication requirement ('Needs the read scope'), cost ('Free'), and the meaning of the multiplier sort. Return format is covered by 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?

The description is two tightly packed sentences with no wasted words. Scope and sorting are front-loaded, followed by cost, expansion alternative, and auth requirement.

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, full parameter descriptions, and annotations covering safety, the description supplies the remaining key context: auth scope, cost, sorting semantics, and pagination alternative. A minor gap is that it mentions topic faceting without a corresponding topic parameter, and it does not state its relationship to posts_list.

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 parameters are already documented. The description adds value by defining multiplier as 'views against the account's own median,' which the schema enum alone does not explain. It also clarifies the platform/topic faceting context.

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

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

The description clearly states it reads every post held for a person or account, with sorting and platform/topic facets. It distinguishes the expansion path via identity_expand, but does not explicitly differentiate from siblings like posts_list that may also return posts.

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 useful context: the tool is free, requires the read scope, and points to identity_expand for pulling more. It does not explicitly say when to choose this over posts_list or other identity siblings, so the guidance is helpful but not complete.

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, non-destructive, closed-world, so the bar is lower. The description still adds genuine value: it says the call is free and requires read scope, and it enumerates what the response contains (evidence attached to edges, vendor/cost/timestamp of pulls, last-pulled times, held date ranges, metric history). That's more than the annotations or the output schema's existence alone conveys.

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

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

It's front-loaded with "One node in full" and then spends its words on the return contents. The long enumerated clause is dense but each item earns its place, and the two trailing sentences ("Free. Needs the read scope.") are clipped and 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 one required param, full schema coverage, an output schema, and read-only annotations, the description fills the remaining gaps an agent would care about: cost, required scope, and the kinds of data returned. It stops short of covering error behavior or what happens for a missing id, but nothing essential to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single id parameter is documented in detail, including the person:/account:/organization:/asset: formats. The description itself says nothing about the id, so baseline 3 is right – the schema does the work here.

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?

"One node in full" states a specific verb and resource, and the list of contents (fields, edges with evidence, pulls, expansions, date ranges, metric history) makes the scope concrete. It doesn't explicitly distinguish itself from siblings like identity_search or identity_expand, though the schema description mentions identity_search finds ids.

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

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

"Free. Needs the read scope" gives cost and auth context, which implies it's safe to use liberally. But there's no explicit statement of when to use this versus identity_expand, identity_similar, or identity_search – the agent has to infer that from the name.

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, so safety is covered; the description adds two things annotations cannot express: it is free of cost and it requires the read scope. That auth/cost disclosure is genuinely useful. It does not mention pagination behaviour or result ordering beyond the sort parameter, keeping it out of the top band.

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

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

It is short and front-loads the resource, which is good, but the single run-on sentence spliced with semicolons and the 'Free.' fragment make it harder to parse than necessary. The scope explanation is buried mid-sentence rather than given its own clause.

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

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

With an output schema present the description needn't document return shape, and annotations cover the safety profile. What remains — cost, required scope, the meaning of scope=mine, and the filter/sort model — is all present, so an agent can call this correctly without guessing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: it explains that scope=mine narrows to what the account tracks plus first-degree neighbours, which is far more informative than the schema's bare 'global (default) or mine'. The phrase 'sorted and filtered' also signals that q, sort and the label filters combine.

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 (every person the graph holds) and what each record carries (labels, accounts, counts), which is enough to distinguish it from identity_search or identity_node on inspection. It stops short of explicitly naming which sibling to use for query-type lookups, so differentiation is implicit rather than stated.

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?

'scope mine is what this account tracks and the people one edge from them' is real guidance about which scope to pick, but it only addresses one of six parameters. There is no statement of when to prefer this over identity_search, identity_library, or identity_tracked, leaving the list-vs-search decision 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: warns it 'SPENDS CREDIT', explains the hold-then-charge model (budget held first, only actual cost charged, `holdUsd` reports the hold), and states the write scope requirement. It does not say what happens to existing graph data when a node is re-resolved with `force`, which matters given destructiveHint=true.

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

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

The cost warning is front-loaded in the first two words, then purpose, then mechanics, then outputs. Dense but 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?

An output schema exists, yet the description still sketches the return shape (anchor node, costUsd, pulls, visited nodes), plus cost, auth scope and idempotency behavior. For a credit-spending, destructive, open-world 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 coverage is 100%, so all four parameters are already documented, and the description largely restates them (budget range/default, force, seed types). The only added meaning is the interplay that `force` is what makes a known seed cost money. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Find who a seed is and land them in the identity graph') and enumerates the seed shapes it accepts (handle, profile URL, personal site, LinkedIn company URL, bare domain). This is clearly distinguishable from siblings like identity_search or identity_estimate, which read rather than resolve.

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

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

Gives a concrete cost-driven usage condition: a known seed costs $0 unless `force` is set, which is exactly the decision an agent needs before calling. It does not name alternatives (e.g. identity_estimate for a cost preview, or identity_search for lookup without graph writes), so the routing guidance is implicit rather than explicit.

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

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

Annotations already declare readOnly/non-destructive, so the description is free to add operational context instead. It does: 'Free' discloses cost, and 'Needs the read scope' discloses the auth prerequisite — both beyond annotations. No return-shape detail, which is fine given an output schema exists.

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

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

Three short sentences, front-loaded with the verb and resource, then cost, then routing advice. No filler and no repetition of the title.

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

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

Covers purpose, cost model, ordering relative to resolution, and auth scope for a two-parameter read tool with an output schema. Only the result-volume controls (limit range/default) are left entirely to 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 description coverage is 100%, so the baseline is 3. 'By name or handle' in the description merely restates what the q parameter description already says; nothing is added about limit or the default of 12.

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 ('find people, accounts and organizations the identity graph already knows') and narrows scope with 'by name or handle, with their labels'. An agent can distinguish it from identity_resolve and identity_expand without opening the schema.

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

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

Explicitly prescribes ordering against a named sibling: 'Use it before identity_resolve' with a cost rationale. It gives no when-not-to-use case or mention of other search-like siblings (concept_search, find_evidence), but the primary routing decision is covered.

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

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

The annotations already cover read-only and non-destructive behavior. The description adds meaningful extra context: the operation is free, requires read scope, and falls back to label-based similarity with a note when no embedding exists.

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

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

The description is short and front-loads the core purpose. The clause 'basis embedding, or labels with a note...' is slightly awkward but still compact and informative.

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

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

Given the rich schema, output schema, and annotations, the description is mostly complete for correct invocation. It covers prerequisites and fallback behavior, with only minor gaps around sibling differentiation and parameter details.

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 anchor, limit, and scope. The description reinforces that the anchor is one person and explains the embedding/label basis, but adds little about limit or scope beyond the schema.

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

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

The description clearly states that this finds people similar to one person, with shared niches/organizations and reasons. It is specific about the resource, but does not explicitly differentiate itself from sibling identity tools such as identity_search or identity_people.

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 useful usage context: the read scope is required and identity_expand with labels should be run first if the person lacks an embedding. These are explicit prerequisites and an alternative path, though it does not compare against sibling search/listing 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 and openWorldHint=false; the description adds genuinely new context beyond them: cost ('Free') and required scopes (read to list, write to change). It also discloses the side effect that resolve/expand auto-create watch entries, which is behavior an agent could not infer from the annotations. It stops short of saying what happens when untracking a node that isn't tracked.

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?

Five short clauses, all load-bearing: mode semantics, sibling side effect, cost, and scopes. Slightly telegraphic phrasing ('it stops', 'by itself') costs a little readability but nothing is wasted 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?

With an output schema covering return values and 100% schema coverage on four optional parameters, the description supplies everything else an agent needs: mode selection, side effects from sibling tools, authorization requirements, and cost.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds combinatorial semantics the flat schema cannot express – which pairs of parameters activate which mode, and that remove is the inverse of tracking. The note parameter ('why, up to 500 characters') is left 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?

It states the resource (the tracked-node list scoped to this account) and the three roles, plus the mutation modes via node+role and node+remove. The opening clause is a noun phrase rather than a verb, so the fact that a bare call returns a list is only confirmed later by 'Needs the read scope to list'. Sibling differentiation is present through the explicit mention of resolve and expand.

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?

Clear argument combinations are given: node+role changes role, node+remove stops tracking, and a bare call lists. It also flags an important interaction with siblings – identity_resolve and identity_expand implicitly add their node as watch – which tells an agent when this tool is unnecessary. No explicit 'do not use when' beyond that, keeping it at 4.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description usefully adds an auth requirement ('Needs the write scope'). However, 'Free: nothing is charged' conflicts with the schema's budgetUsd parameter (default 2, max 10), which is actively misleading about cost behavior, and the tension with readOnlyHint/write scope is left unexplained.

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

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

Two tight sentences, front-loaded with the returned tokens rather than preamble. The only wasted (and harmful) clause is 'Free: nothing is charged', which occupies space and misinforms.

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 detail is unnecessary, and all three params are documented in-schema. What's missing is the sibling-routing guidance an agent needs to choose between this and the many page/asset/render tools, plus an accurate statement about billing and 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 description coverage is 100%, so the baseline is 3; the description adds no meaning for 'url' or 'viewport' beyond the schema and does not touch the budget parameter. Worse, its 'Free: nothing is charged' line gives a false signal about budgetUsd, so it subtracts rather than adds for parameter interpretation.

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 output set — typefaces, palette by role as hex, button radius, logo — so an agent knows this returns design tokens for a page's visual identity, distinct from screenshot_page or read_page. It lacks an explicit verb (the action is only implied by 'measured as a visitor sees it'), and it never contrasts itself with the visual-capture siblings.

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

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

There is no when-to-use guidance: nothing says when to prefer this over screenshot_page, read_page, brand_mark, or identity_library. The phrase 'measured as a visitor sees it' faintly implies rendered-page extraction, but no alternative or exclusion is 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?

Beyond the readOnly/openWorld annotations, it discloses meaningful behavior: a 409 with a connect link when the account isn't connected via Facebook Login, the required read scope, and that the sound is attached by Instagram and never burned into the video. Those are practical, non-obvious facts an agent needs before calling.

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

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

It is a dense, front-loaded paragraph with little waste; the caveats, usage hints, and prerequisites each carry information. The run-on packing of several ideas into one paragraph slightly reduces readability.

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

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

With an output schema present, return values need not be explained. The description covers auth requirements, the 409 failure mode, scope, downstream id usage, and catalogue caveats, so 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%, so the baseline is 3. The description adds real value by explaining that a returned id is passed to posts_create audio.audioId, but it also references isAdsEligible which is not in the schema, which could confuse. Net it stays at the baseline.

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

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

The description names a specific resource and scope: music or original sounds from Meta's Audio API that an Instagram account may attach to a Reel, with the caveat that the in-app catalogue differs. It clearly conveys a search over Instagram's sound catalogue. It stops short of naming a sibling for direct differentiation (e.g., plan_music), so it falls just 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 concrete conditions: empty query returns trending, prefer isAdsEligible: true for a business promoting itself, and pass a result's id as posts_create audio.audioId. Prerequisites (Facebook Login connection, read scope) are spelled out too. It does not explicitly state when NOT to use it or name an alternative tool, so a 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, 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 declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true; the description adds the auth requirement (write scope) and clarifies that this appends a message and resumes with full history rather than starting over. It does not cover rate limits, approval/pausing behavior, or what happens to an in-flight run.

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 plus a short dashed clause; the resume capability and auth requirement are packed in without any filler or redundancy.

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

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

Annotations supply the safety profile and an output schema exists, so return values need no explanation. The description covers purpose, resume semantics, and auth, but leaves the interaction between continuing and run-state (autoRun, pending approvals, budget on resume) to 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 description coverage is 100%, so all six parameters including model, autoRun, budgetUsd, and mediaKeys are already documented. The description only echoes the optional file attachment (mediaKeys) and adds no format or constraint detail beyond the schema, making the baseline 3 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?

States a specific verb and resource ("send another message to a job") and adds the distinct capability ("resume a stuck or failed run with full history"), which separates it from siblings like jobs_create, jobs_run, and jobs_stop. An agent can pick this tool without opening the schema.

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

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

Gives one explicit when-to-use case (resuming a stuck or failed run with history preserving) plus a prerequisite ("Needs the write scope"). It stops short of naming alternatives or stating exclusions, so an agent must infer when to prefer jobs_run or 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 readOnlyHint=false, destructiveHint=false and openWorldHint=true, so safety is covered; the description adds the important non-obvious traits: the run is durable and continues server-side after the call returns, and the caller needs the write scope. It stops short of describing cost/budget implications or what a failed start returns.

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

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

Three short sentences, front-loaded with the action and resource, then the async consequence, then the auth prerequisite. No redundant restatement of the title, no filler, and the opening clause is the one an agent needs 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?

For an 11-parameter, open-world mutation with an output schema, the description covers purpose, async lifecycle, and auth requirement without needing to re-document returns. It does not mention the autoRun/approval pause that the schema exposes, nor relative cost or rate implications, which keeps it just short of complete.

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

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

Schema description coverage is 100% and the field docs are unusually rich (idempotencyKey, mode, characters), so the schema carries the burden. The description only gestures at mediaKeys via "optionally with files attached" and adds no meaning for goal, mode, model, budgetUsd, or idempotency semantics — the 3 baseline is appropriate.

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

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

States a specific verb and resource — "Start a durable job from a goal" — and flags the optional file attachment path. It is clearly distinguishable from siblings like jobs_continue (resume) and jobs_get (poll) implicitly through the "returns the job id and its web url" phrasing, though it never names those siblings 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?

"returns the job id and its web url to poll or continue" implies the follow-on tools without naming jobs_get, jobs_tail, jobs_continue or jobs_run, leaving the agent to infer which to call next. There are no explicit when-not-to-use conditions, and the "Needs the write scope" prerequisite is the only gating guidance given.

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