Shuffll Engage

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing what is deliberately withheld from the response (private storage references, upload capabilities), which is information the annotations do not 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?

Two short sentences with zero filler, and the operation and its most surprising constraint (what is never returned) are front-loaded.

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

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

An output schema exists, so return-shape explanation is unnecessary, and annotations cover safety. The description is nearly complete for a one-parameter read; only error/not-found behavior or ownership failure handling is 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 description coverage is 0%, but the single parameter's UUID regex pattern fully constrains the accepted format, so an agent knows what to supply. The description adds nothing about the id's semantics (e.g. asset id vs. a nested reference), leaving a minor gap.

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 plus resource ('Read safe owned asset metadata'), which is clearly distinct from the sibling list tool assets_list. It doesn't explicitly name the sibling to differentiate, but the singular 'asset' framed as an ownership-scoped read makes the intent unambiguous.

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

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

No guidance on when to call this versus assets_list or uploads_get, and no note on what happens if the caller doesn't own the asset. Usage must be inferred from the word 'owned' alone.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description's one added fact is that results are limited to assets 'owned' by the current tenant, which is meaningful scoping information not in the annotations. It says nothing about pagination behavior 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?

A single front-loaded sentence with no filler, and the scope qualifier sits before any alternative discussion. It is efficient but arguably too thin rather than padded.

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

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

An output schema exists, so return shape needs no explanation. However, for a paginated list tool the description omits any hint that results are cursored and may be truncated, which is the main thing an agent needs beyond 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 0%, so the description must carry the burden and does not: it never mentions 'limit', its default of 50 / cap of 100, or that 'cursor' is a pagination token with a UUID format. The parameter names and schema constraints are all an agent has to go on.

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 ('owned asset metadata') plus the tenant scope, which is enough to tell it apart from assets_get by operation type. It stops short of explicitly naming the sibling, but the list-vs-fetch distinction is clear.

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 statement of when to use this versus assets_get, and no mention of paging through results or what to do when the listing is large. The agent must infer all usage context 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=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond that — it does not say what happens if no brand profile is configured, whether defaults are returned, or any access constraints. It essentially restates the title.

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

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

One short, front-loaded sentence with zero waste, but it is terse to the point of under-specification rather than genuinely efficient — it leaves no room for the disambiguating detail 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, so return values need not be explained, but for a tool with an undocumented required identifier and a close sibling (organizations_get) the description should clarify the id's referent and the relationship between brand and organization. It does neither.

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

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

Schema description coverage is 0%: the single required 'id' parameter has only a UUID pattern and no description. The description implies the id identifies the organization whose brand is read, but never states this explicitly, so an agent cannot be sure whether it is an organization id or a brand id.

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

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

States a specific verb ('Read') and resource ('organization brand profile'), which is clear enough to distinguish from list-oriented siblings like organizations_list or templates_list. It does not, however, differentiate itself from organizations_get or explain how a 'brand profile' relates to the organization record, leaving some ambiguity.

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 guidance on when to call this versus organizations_get, nor any prerequisite or exclusion stated. The agent must infer usage entirely 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 readOnly, idempotent, and non-destructive, so safety is covered. The description adds genuine interpretive context beyond the annotations: fixed-video generation doesn't deliver messages, and no engagement/delivery event is inferred from an export, warning the agent not to over-read the counts.

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

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

Two sentences with no filler; the core scope is front-loaded and the caveat follows. The second sentence is slightly dense and telegraphic but earns its place as interpretation guidance.

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

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

For a single-UUID read tool with a full output schema and complete safety annotations, the definition covers the essentials plus interpretive caveats. Minor gap: it never states explicitly that the ID is a campaign ID or links to sibling analytics tools.

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

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

Schema description coverage is 0% and the single `id` parameter is never mentioned in the description. However, the sole parameter is a required UUID whose pattern makes its shape obvious, and "Campaign-scoped" implies it's a campaign identifier, so the gap is modest.

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 the resource clearly: "Campaign-scoped counts of render attempts and recipients," which tells an agent this returns render/recipient counts rather than campaign config. It does not explicitly differentiate itself from neighbors like campaign_production_get or campaigns_get, but the resource is specific enough to act on.

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

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

There is no guidance on when to choose this tool over campaigns_get, campaign_production_get, or recipients_list. The second sentence offers interpretation caveats but no usage conditions or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description still adds genuine value by ruling out side effects beyond reading ('no rendering, export or delivery') and by noting the access requirement ('accessible campaign').

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 return contents, then usage and safety caveat. The enumeration of returned fields is slightly redundant given an output schema exists, but it is compact and readable.

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

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

For a single-parameter read with rich annotations and an output schema, the description covers purpose, the parameter's referent, side-effect boundaries, and when to call it. Nothing an agent needs to select or 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 0%, so the description carries the burden and does resolve the key ambiguity: the `id` is a campaign id, not a production id, which matters because the response contains both IDs. It does not repeat the UUID format, but that is fully specified by the schema pattern.

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 ('Read the saved production settings') plus the scoping qualifier ('accessible campaign by campaign id'). The phrase 'production settings' clearly distinguishes it from sibling reads like campaigns_get or templates_get.

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

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

'Use it to inspect the current edit before changing scenes' gives a concrete trigger context for invocation. It stops short of naming an alternative tool or an explicit when-not condition, so it falls just below the top mark.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the bar is lower; the description still adds real value by scoping results to the connected organization and explicitly disclaiming side effects. It doesn't cover error behavior (e.g. what happens for an inaccessible or archived id), which is the 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?

Two sentences, front-loaded with the action and scope, followed by a single negation sentence that earns its place by preventing misrouting. No filler or restatement of the tool name.

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

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

With an output schema present, the enumerated return fields are arguably redundant, but they cost little and confirm the metadata-only nature of the read. Combined with annotations and the schema, an agent has nearly 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?

Only one parameter and the schema supplies the UUID pattern but zero description coverage, so the description must carry the semantics. It identifies the argument as a campaign id but adds no format, lookup or source hint (e.g. where to obtain the id, whether archived campaigns are resolvable).

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 ('Read one accessible fixed-video campaign by campaign id in the connected organization') with a clear singular scope that separates it from campaigns_list. The returned field list (IDs, revision, archive state, workspace status, format) further pins down what kind of object this is.

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 'accessible ... in the connected organization' phrasing gives the eligibility condition, and the closing sentence rules out three neighboring behaviors (recipient contacts, media generation, sending). It doesn't explicitly point at a sibling like campaign_production_get or campaign_analytics_get for those adjacent needs, so routing is inferable 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 readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile needs no repetition. The description still adds real behavioral value: it specifies cursor-based pagination via limit and cursor and that the response carries a next cursor, and it pre-empts a common misread by stating the call does not create, generate media, or send anything. It does not discuss rate limits or permission/access-scope semantics, 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?

Three sentences, front-loaded with the operation and scope before pagination details and the negative-capability caveat. Slightly over-indexed on enumerating returned fields, which the output schema already covers, but nothing is truly wasteful.

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

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

An output schema exists, so the return-field enumeration is a bonus rather than a necessity. Scope, pagination mechanics and the read-only caveat are all present; the only gaps are what 'accessible' means in terms of permissions and the limit defaults, both minor for a two-parameter list call.

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

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

Schema description coverage is 0%, so the description bears the burden. It names both parameters and frames them as a pagination pair, and 'plus the next cursor' tells the agent how to continue iterating. It omits the limit default (50) and the 1–100 bounds, and never explains that cursor must be a UUID taken from a prior response.

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

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

Opens with a specific verb plus resource and scope ('List accessible fixed-video campaigns in the connected organization'), which cleanly separates it from the singular campaigns_get and from the other *_list siblings. An agent knows immediately this is the collection-listing endpoint for campaigns.

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

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

Usage is only implied: retrieving campaigns via pagination. The description does not say when to prefer this over campaigns_get, campaigns_validate, or campaign_production_get, nor any prerequisite (e.g., needing an organization context). The closing 'This read does not create campaigns, generate media or send messages' rules out write paths but is not genuine when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so safety is covered structurally. The description adds real behavioral signal beyond that: it lists the returned validation facets and explicitly disclaims side effects (no generation, export or delivery), and 'accessible campaign' hints at access scoping. It does not say what happens for an inaccessible/nonexistent id, which keeps it off a 5.

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

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

Three short sentences: what it checks, what it returns, and how to use it versus what it does not do. Front-loaded with the operation and scope, and every clause carries information an agent needs.

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

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

With an output schema present, the description needn't enumerate return structures — and it already names the key fields, plus annotations cover the read-only/idempotent profile. For a single-UUID read tool, nothing essential 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 schema documents the single 'id' parameter only via a UUID regex with 0% description coverage. The description clarifies it is a campaign id (not a job or asset id) and that it must reference an accessible campaign, which adds some meaning, but no format or lookup guidance beyond the pattern 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 ('Check the current fixed-video configuration of an accessible campaign by campaign id') and enumerates exactly what comes back: validation status, format, personalization support, generation availability and workspace readiness. It is clearly not a generic getter, but it never names the adjacent siblings (campaigns_get, campaign_production_get) that an agent might confuse it with.

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

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

'Use this read to identify whether setup permits generation' gives a concrete decision context, and 'it does not start generation, export or delivery' rules out misuse as an action trigger. It stops short of naming which sibling to call instead for mutation or for full campaign detail, so the alternative-selection 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only the qualifiers 'Current' and 'effective', which imply the result is computed at call time and scoped to the caller's entitlements — useful but thin; nothing is said about freshness, caching, or what happens if entitlements are missing.

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?

Seven words with zero waste, but the economy comes at the cost of completeness — it is a sentence fragment rather than a front-loaded statement of action. Brevity here reads as under-specification rather than discipline.

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

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

The tool is simple (no params, output schema present, rich annotations), so the description does not need to explain return values or safety. What is missing is the one thing only prose can supply: why an agent would call this and how to use the result, which the terse fragment does not address.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The empty schema with additionalProperties=false is consistent with the description, which correctly implies no input 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?

The phrase 'Current safe operations and effective entitlements' expands the name 'capabilities' into what the payload contains, so it is not a pure tautology, but it is a noun fragment with no verb and no statement of what the tool actually does (return? compute? list?). An agent can guess it reports what the caller is permitted to do, but the purpose remains vague relative to siblings like organizations_get or templates_get.

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 indication of when to call this versus any alternative — no mention of prerequisites, no reference to sibling tools, no note that it should be checked before attempting operations. The agent is left to infer the use case entirely from the phrase 'safe operations'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description still adds real context: catalog entries do not confer generation authority, and pagination is stable-ID cursor based with a default of 50 and max of 100 — details not present 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 short sentences, each earning its place: purpose, a scope caveat, and pagination mechanics. No filler and no repeated schema/annotation content.

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 both parameters plus the read-only semantic are covered. An agent has enough to call it correctly, though the absence of guidance on using the returned cursor/IDs is a minor gap.

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

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

Schema description coverage is 0%, so the description must carry the load — and it does, explaining that cursor is a stable-ID cursor, that limit defaults to 50, and that the maximum is 100. It does not describe cursor opacity or how to obtain the first cursor, keeping it below 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 specific verb and resource: 'Read configured fonts available to this tenant', which is unambiguous and distinguishes it from sibling catalog tools by resource name alone. It stops short of explicitly contrasting with siblings like catalogs_models or catalogs_voices, so not a 5.

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

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

Usage is implied (a read listing of tenant-configured fonts), and the caveat that catalog entries do not grant generation authority hints at what this list is not for. However, there is no explicit statement of when to use this versus looking up a font elsewhere or what to do with the results.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real value beyond that: the authorization caveat that catalog presence does not grant generation authority, plus the pagination model ('stable ID cursor') and its 50/100 bounds. It stops short of describing ordering or what a stable ID cursor looks like in practice.

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 resource and scope, then the semantic caveat, then pagination mechanics. No filler and nothing repeated for its own sake.

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 spelled out, and the two optional params are covered. What remains thin is ordering guarantees and whether the tenant's configured set can be narrowed; for a simple read-only catalog list this is close to 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 0%, so the description must carry this load, and it does explain both params: limit defaults to 50 with a 100 max, and cursor is a stable-ID-based cursor rather than an offset. It does not say what the cursor string is obtained from (presumably the previous response's next-cursor), which is a minor gap.

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?

Uses a specific verb+resource ('Read configured languages available to this tenant') that unambiguously distinguishes it from the other catalogs_* siblings (fonts, models, music, transitions, voices). The scope qualifier 'available to this tenant' further pins down what set is returned.

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?

'Catalog entries do not grant generation authority' hints at how to interpret results but is a caveat, not usage guidance. Nothing states when to call this versus catalogs_models/catalogs_voices, nor any prerequisite or exclusion. Usage is only implied by the resource 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 readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description still adds real context beyond them: the pagination contract (stable ID cursor, default 50, max 100) and the important permission caveat that catalog entries do not confer generation authority. It doesn't say whether an empty catalog or invalid cursor errors, but that is a minor omission given the annotation coverage.

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 resource and its scope, then the authorization caveat, then the pagination contract. Nothing is redundant; the caveat sentence earns its place for an AI agent that might otherwise assume catalogs imply capability.

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 described, and both parameters are optional. For a simple paginated read, the definition is functionally complete; only cursor continuation semantics remain implicit.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does explain both: limit's default and maximum, and that cursor is a stable ID. It still omits how to obtain and round-trip the cursor and the minimum of 1, so it only partially compensates for the documentation gap.

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

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

Specific verb+resource: "Read configured models available to this tenant." The resource (models) is distinct from the sibling catalogs_* tools (fonts, languages, music, transitions, voices), though the description never names that distinction explicitly. An agent can tell what it returns, just not why it would pick this over another catalog call.

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, prerequisites, or named alternatives. "Catalog entries do not grant generation authority" is a semantic caveat about the results, not guidance on selecting this tool, and nothing tells the agent how to continue when the cursor runs out or which sibling to consult for generation-capable data.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds material context beyond annotations: the generation-authority caveat and cursor pagination defaults/maximum. Return shape 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 short sentences, front-loaded with the core purpose followed by the usage caveat and pagination constraints. Every sentence adds information 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?

For a simple two-parameter read-only catalog tool with full annotations and an output schema, the description covers tenant scope, the authority caveat, and pagination constraints. Little else is needed for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains that pagination is by stable ID cursor and restates the limit default of 50 and maximum of 100, partially compensating, but does not explain cursor construction or traversal beyond 'stable ID'.

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

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

States a specific verb (Read) and resource (configured music available to this tenant), and the resource distinguishes it from sibling catalogs such as catalogs_fonts and catalogs_voices. An agent can identify this as the music-catalog reader 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?

Clear context for when to use: discovering music configured for the tenant. The caveat that catalog entries do not grant generation authority is a useful usage constraint, though no explicit alternatives are named (none appear to duplicate this resource).

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the description correctly spends its words elsewhere: the parity/scene-restriction quality guarantee, the exclusion of generated clips and fallbacks, and pagination behavior. It adds real information beyond the structured fields rather than restating the safety profile.

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

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

Three tight sentences with no filler, and the actionable routing ('use journey_preview_generate.finishing') is placed early. Leading with an adjective-heavy qualifier rather than the action is mildly suboptimal front-loading, 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile; what remains for the description is scope, exclusions, and pagination, all of which are present. The only shortfall is that the tool's core action (enumerate styles) is implied rather than stated.

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

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

Schema description coverage is 0%, so the description must carry both parameters, and it does: 'Stable ID cursor pagination defaults to 50 entries, maximum 100' covers the limit default/ceiling and characterizes the cursor as a stable-ID cursor. It doesn't state what happens on an invalid or expired cursor, but the gap is small for a read-only catalog.

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 identifies the resource precisely (native transition styles with verified playback/export parity and scene restrictions) and rules out a confusing near-miss category ('Generated transition clips and fallbacks are never offered'). It never uses an explicit verb like 'list' or 'returns', so the agent infers from the catalogs_* naming that this is an enumeration tool rather than a lookup.

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

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

'Use journey_preview_generate.finishing to apply an available style' hands the agent the downstream consumer, clearly splitting discovery from application. There is no guidance on when this catalog is the wrong choice versus other catalogs_* siblings, but the exclusion sentence narrows what the agent should expect to find here.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the safety profile is covered. The description adds real context beyond that: entries are tenant-scoped, they do not confer generation rights, and pagination is stable-ID cursor with a default of 50 and cap of 100. It does not say what happens on an expired or invalid cursor, or the sort order.

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

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

Three tight sentences with the resource scope front-loaded, then the authority caveat, then pagination limits. No filler, and the most decision-relevant information (what this returns and what it does not authorize) comes first.

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

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

An output schema exists, so return shape needn't be described, and pagination mechanics are covered. For a simple read-only two-parameter list tool this is nearly complete; only ordering and cursor-expiry behavior are left 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 description coverage is 0%, so the description must compensate. It does explain that the cursor is a stable ID cursor (adding semantics beyond the UUID pattern) and restates the limit default/maximum, but it does not say the cursor comes from a prior response, that it is opaque, or how to detect the last page. Partial compensation for two undocumented parameters.

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

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

Specific verb plus resource: 'Read configured voices available to this tenant.' The resource name distinguishes it from sibling catalogs (fonts, languages, models, music, transitions) without needing the schema. It stops short of explicitly contrasting with any sibling, so it lands at 4 rather than 5.

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

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

Usage is implied by the resource (browse voices provisioned for the tenant), but there is no explicit when-to-use/when-not statement and no named alternative. The line 'Catalog entries do not grant generation authority' is a semantic caveat about what the data means, not a selection 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?

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds meaningful context beyond that by distinguishing inherited partner settings from exact workspace settings and mentioning approved parent origins, which tells the agent what kind of configuration data it is reading. It stops short of explaining authorization requirements or level-dependent behavior in detail.

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

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

The description is a single compact sentence with no wasted clauses, and the core action and scope are front-loaded. It is appropriately sized for a simple read tool, though 'approved parent origins' could be slightly clearer as a returned concept.

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 has an output schema and annotations, so the description does not need to explain return values or safety. However, with three parameters and zero schema descriptions, the missing explanation of campaignId and workspaceId and their relationship to level leaves an agent without enough context to choose parameters confidently.

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

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

Schema description coverage is 0%, so the description must carry the burden of explaining parameters. It hints at the level enum through 'partner' and 'workspace', but it does not explain campaignId or workspaceId, nor does it say which ID is required or relevant for which level. That leaves two of three parameters unexplained.

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 ('Read') and resource ('embed settings'), and it distinguishes the two scopes ('inherited partner' vs 'exact workspace'). It does not explicitly contrast itself with sibling tools such as embed_events_list, but the resource is distinct enough for an agent to recognize 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 is only implied through the 'inherited partner or exact workspace' phrasing and the required level enum. There is no explicit instruction on when to choose this over sibling tools or when-not to use it, and the conditions tying workspaceId or campaignId to a given level are not 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds that events are 'server-observed' (authoritative, not client-reported) and 'bounded', which is genuinely useful context, but it says nothing about ordering, pagination behavior, or result bounds beyond the word 'bounded'.

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 with no filler; scope and subject come first. It is perhaps too terse given the undocumented parameters, 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?

An output schema exists, so return values need not be explained, but with 0% schema description coverage on both parameters the description leaves an agent guessing about limit semantics and campaignId format. For a read tool this simple, one clause about limit/paging would have made it 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 0%, so the description should compensate, yet it only implies that a campaign identifier is needed via 'for an authorized campaign'. It never mentions the 'limit' parameter, its default of 50, or its cap of 100, nor the required UUID format of campaignId.

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') plus a precise resource ('server-observed session and media request audit events') scoped to a campaign. This distinguishes it clearly from sibling config/list tools such as embed_config_get or campaign_analytics_get, though the phrasing 'embed events' vs. audit events is slightly indirect.

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 words 'bounded' and 'authorized campaign' imply the read is limited to a campaign the caller may access, giving implied usage context. However, there is no explicit when-to-use/when-not guidance and no pointer to an alternative tool for broader or different event queries.

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, idempotent, non-destructive, closed-world), so the description should add something else; instead it introduces ambiguity about whether the tool itself verifies 'workflow authority' or merely requires the caller to have done so. No mention of error behavior, authorization failures, or job lifecycle states.

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 short sentence with no filler is good, but the brevity comes at the cost of clarity rather than being earned concision. The most important information (what resource, what precondition) is expressed in abstract nouns.

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 safety. But for a parameterized lookup tied to an authorization concept, the description omits what the id is and what the authority check implies — the two things an agent actually needs before calling.

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 required parameter with 0% schema description coverage — the schema only supplies a UUID regex, not a name — so the description bears the burden of explaining what the id refers to. It says nothing, leaving the agent to guess whether it is a job id, workflow id, or operation id.

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

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

The verb 'Read' is specific, but the resource is described obliquely as an 'initiated operation' rather than a job, leaving the agent to infer that jobs_get returns job status/details. It also fails to distinguish this tool from the nearby operations_resolve sibling, so the agent has no basis for choosing between them.

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

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

The clause 'after checking its underlying workflow authority' hints at a precondition but never states who performs that check or what to do when it fails. No when-to-use, when-not-to-use, or alternative tool is named despite many plausible siblings (operations_resolve, campaigns_get, uploads_get).

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered structurally. The description still adds genuine context: the document is owned and persisted, historical snapshots remain inspectable (no purging), and current state is elsewhere — useful expectations about what comes back.

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

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

Two short sentences, front-loaded with the action, and the historical-vs-current caveat follows. Phrasing like 'with actual options, scenes and scripts' is slightly awkward but carries information rather than filler.

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

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

An output schema exists, so return values need not be explained, and annotations cover safety behavior. The remaining gap is identifier semantics relative to a crowded family of *_get siblings, which an agent needs in order to pass the right id.

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 0% for the single 'id' parameter, so the description carries the burden, yet it never says whether 'id' is the document id, a journey id, or a version id despite many sibling tools also taking ids. Only the vague 'owned saved concept/storyboard document' phrasing hints at the referent.

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 a specific resource (an owned saved concept/storyboard document), and enumerates the payload (options, scenes, scripts). It is distinguishable from journeys_get-type siblings via the 'owned saved document' framing, though no sibling is named.

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 second sentence implies when to use it: historical documents remain retrievable here, while current selections live in 'the journey artifacts'. That is implied routing rather than an explicit 'use X instead', and 'journey artifacts' is not a tool name an agent can act on directly.

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

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

Annotations already establish read-only, idempotent, non-destructive, and closed-world behavior, so the description does not need to repeat safety semantics. It adds useful scope context beyond annotations: historical versions remain readable, the current source is tied to the journey artifact, and the result does not certify downstream video/placement readiness.

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 read purpose in the first sentence. The remaining sentences add versioning and non-certification caveats without excessive length, though the wording is occasionally cryptic.

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

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

With an output schema and annotations present, the description does not need to explain return values or safety traits. However, it leaves important gaps for an agent: no when-to-use guidance versus siblings and no clarification of the required `id` parameter's meaning.

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

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

Schema description coverage is 0% for the single required `id` parameter, and the description does not explain what that ID represents. The UUID pattern in the schema indicates format only, leaving ambiguity about whether `id` is an overlay draft ID, journey artifact ID, or something else.

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

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

The description gives a specific verb and resource: "Read an owned ... overlay draft, scene identities and sample/default values." It is clear enough to identify the tool's purpose, but it does not explicitly differentiate it from siblings such as journey_authoring_get, and the phrase "immutable editable overlay draft" is internally confusing.

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 provides no explicit guidance on when to use this tool versus journey_authoring_get or journeys_get. The caveat about alpha video, MP4 readiness, and placement tracking is a limitation, not a usage rule or alternative-selection criterion.

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 state readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the useful detail that it surfaces artifacts and checkpoint state, but says nothing about behavior on unknown ids, errors, or freshness of the returned state.

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 with no filler; the key content (read a saved journey) comes first. It is terse to the point of omitting scope details, 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?

For a one-parameter getter with an output schema that documents the return shape, the definition covers what the tool returns (artifacts, checkpoint state) and that it is a read. Missing only edge-case behavior such as not-found handling, which is minor here.

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

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

Schema coverage is 0% and the single `id` parameter is undocumented, so the description would need to compensate. It only indirectly implies the id identifies a journey via "a saved video creation journey"; it never states the id format or that it must be an existing journey UUID (the schema only encodes this as a regex).

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 ("Read") plus a specific resource ("saved video creation journey") and an indication of what is returned ("current artifacts and checkpoint state"). It reads clearly as the single-journey getter versus journeys_list, though it never explicitly distinguishes itself from journey_authoring_get or journey_overlays_get.

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 name and by "saved" (a persisted journey that already exists, keyed by id), but there is no explicit statement of when to call this versus journeys_list or the other journey_* siblings, and no prerequisites are given.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine value with the scope exclusion (no full briefs, no contact data), but says nothing about pagination behavior despite cursor/limit parameters.

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

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

Two short sentences, front-loaded with the action and immediately followed by the scope exclusion. No filler or repetition.

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 output schema covers return values, so omitting them is fine, and annotations cover safety. But for a paginated list tool with 0% schema description coverage, the absence of any paging or org-context guidance leaves the definition thin.

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

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

Schema description coverage is 0% and the description documents none of the three parameters — limit, cursor, or the required organization_id — beyond a vague 'authorized organization' phrase. With the schema providing only types/patterns, the description should have explained the cursor-based paging model and org scoping.

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 (saved video creation summaries) scoped to an organization, which distinguishes it from journeys_get by list-vs-fetch semantics. However, it never maps 'journeys' to 'video creation summaries' or differentiates from the adjacent journey_authoring_get / journey_overlays_get 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?

Usage is implied only: 'List ... summaries' suggests enumeration, and the exclusion 'Does not return full briefs or contact data' implicitly points an agent to journeys_get when full detail is needed. There is no explicit when-to-use/when-not-to-use statement.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context by stating that missing receipts remain unresolved and that no request input, job payload, or new work is returned, clarifying output boundaries and edge-case 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?

The description is three tight sentences with no filler, and the core constraint is front-loaded. Its brevity is appropriate, though the cryptic phrasing limits usefulness more than it preserves conciseness.

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 fully explained. But for a tool with three required identifiers and a large command enum, the description leaves input semantics and usage conditions under-specified, making it incomplete for reliable invocation.

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

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

The schema has 0% description coverage for three required parameters, including a 30-value command enum, so the description must compensate. It does not explain what id, target_id, or command individually mean or how they relate to the 'original campaign command' and 'workflow authority.'

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 says it resolves 'the outcome of your original campaign command under its current workflow authority,' but 'resolve' and 'workflow authority' are obscure and the tool's exact purpose is not concrete. It does not clearly distinguish itself from siblings such as jobs_get or campaigns_get.

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 limited implied usage: it applies to the original campaign command and notes that missing receipts remain unresolved. However, it gives no explicit when-to-use guidance or named alternatives, and an agent would need to infer when this is preferable to jobs_get or campaigns_get.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that the returned data is 'safe' metadata plus a revision, which is mild extra context, but it says nothing about failure behavior for a missing id or the shape/scope of the revision field.

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

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

One short sentence with no filler, and the action+resource is front-loaded. It is efficient, though arguably under-specified rather than concise for a tool that has an undocumented parameter.

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

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

An output schema exists, so return values needn't be explained, and annotations cover safety. But the required id parameter is undocumented in both schema and description, and the description gives no signal about lookup failure behavior — leaving a real gap for a simple fetch tool.

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

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

Schema description coverage is 0% and the single required parameter 'id' is documented only by a UUID regex pattern. The description never mentions the id at all — not that it is the organization's UUID, not what happens with a malformed or unknown id — so it does not compensate for the coverage gap.

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 verb (read) and resource (organization) plus the fields returned (metadata and revision), which separates it loosely from the organizations_list sibling. However, 'safe organization metadata and revision' is vague — 'safe' and 'revision' are unexplained, and an agent cannot tell what 'revision' means (a version number? a changelog?) without opening the output 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?

There is no explicit when-to-use guidance, no mention of prerequisites, and no named alternative. The get/list naming convention implies retrieving a single organization by id versus listing all, but that inference is left entirely 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the tenant-scoping constraint, which is genuinely useful context, but says nothing about pagination behavior 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?

A single economical sentence with no filler and the scope constraint front-loaded. It is efficient, though so terse that it omits needed paging detail rather than wasting words.

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 needn't be explained, and annotations cover safety. However, for a paginated list tool with undocumented limit/cursor parameters, the description should say how to page through results and how the tenant scope is determined.

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

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

Both parameters (limit with default 50/max 100, and UUID-patterned cursor) have 0% schema description coverage, and the description does not explain either. The agent gets no prose guidance on paging or result caps beyond what the bare schema types imply.

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 (organizations), plus a scoping constraint ('within the current tenant context'). It is distinguishable from the sibling organizations_get, though the phrase 'only' is slightly ambiguous about what is being excluded.

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 guidance on when to use this versus organizations_get, no prerequisites, and no mention of when pagination should be followed. The tenant-scope clause hints at a boundary but does not state an alternative or exclusion explicitly.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the concrete auth requirement ('Requires recipients:read in the connected organization') and the scoping qualifier 'authorized,' which tells the agent that permission failures are a real outcome. Return field list is largely redundant 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?

Front-loaded with the verb, resource and key requirement, followed by permissions and exclusions — a sensible order. The enumerated return-field sentence partly duplicates the output schema and is the one element that does not fully earn 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?

For a two-parameter read with an output schema and full annotations, the description covers purpose, required permission, and negative scope (no update, no generation, no delivery). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 0% and the two parameter names are ambiguous on their own, but the description disambiguates the critical one by clarifying that 'id' is the campaign id paired with recipient_id. It adds no format or constraint detail beyond that, and the UUID pattern lives only 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 ('Read one authorized campaign recipient') plus the exact key pair required, which immediately separates it from the sibling list tool recipients_list. An agent knows this is a single-record fetch, not a query or enumeration.

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

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

'Use it to inspect an existing contact' gives a clear usage context, and 'it does not update the recipient or perform generation or delivery' rules out the mutation and production paths. It stops short of naming recipients_list as the alternative for enumeration, 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 cover read-only, idempotent, non-destructive, and closed-world behavior, so the description adds useful context beyond them: required authorization scope, pagination behavior, returned counts and next cursor, and explicit negative capabilities. This gives the agent a clear operational picture.

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

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

The description is front-loaded with the core action and scope, then adds return fields, authorization, and exclusions in three efficient sentences. There is no filler, and each sentence contributes relevant information.

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

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

With annotations covering safety and an output schema available, the description is largely complete for a read-list tool: it covers scope, auth, pagination, and side-effect exclusions. The remaining gaps are explicit sibling routing and fuller parameter semantics, but neither prevents correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It does identify that `id` is a campaign id and that `limit` and `cursor` drive pagination, but it does not explain `limit`'s default/range or the cursor token's origin/format, leaving those details to the schema constraints.

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

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

The first sentence gives a specific verb and resource: list authorized recipient records for a campaign id with pagination. It is clearly not a get-one or mutation tool, but it does not explicitly name the sibling `recipients_get` or otherwise differentiate from it beyond the list/get naming convention.

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

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

It provides clear context: use it for recipient records for a supplied campaign id, with required `recipients:read` scope, and it explicitly excludes editing contacts, generating videos, and sending messages. However, it does not name alternatives such as `recipients_get` or state when to prefer one over the other.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds useful semantics about 'safe projection' and render-readiness of frozen versions, but 'safe projection only' is vague and it says nothing about authorization failure modes or what a non-render-ready response contains.

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 with no filler, and the availability constraint is front-loaded. However, it is dense with internal jargon ('frozen flat-video-v1', 'safe projection') that costs the reader parsing effort for limited added clarity.

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

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

An output schema exists, so return values needn't be explained, and the tool is a simple single-parameter lookup. The main remaining gap is identifying what the id refers to and how this differs from its list/version siblings, which the description leaves 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?

There is one required parameter (id) with 0% schema description coverage, and the description never mentions it, its UUID format, or whether it refers to a template id versus a version id. With no schema prose to lean on, the description should have compensated and does not.

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

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

The description indicates retrieval of template metadata ('Discover authorized published template metadata'), but the verb 'Discover' is vague for a by-ID getter and it never states that it fetches a single template by id. It also doesn't distinguish itself from templates_list or template_versions_get, leaving the agent to infer the difference from the name 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?

It supplies availability context (only frozen flat-video-v1 versions are render-ready, legacy versions unavailable), but gives no explicit guidance on when to call this versus templates_list or template_versions_get. The agent must work out the selection logic itself.

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

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

Annotations already declare the read-only, idempotent, non-destructive profile, so the description is not required to restate safety. It adds useful behavioral context beyond annotations: only explicitly frozen flat-video-v1 versions are render-ready, they contain fixed video clips without personalization, and legacy/unsupported versions are unavailable.

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 purpose in the first sentence before adding availability constraints. A little of the phrasing is dense and jargon-heavy, but there is no wasted verbiage.

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

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

Because an output schema exists, the description need not explain return values. However, it leaves out pagination guidance for limit/cursor and does not clarify how this list relates to templates_get or template_versions_list, leaving notable gaps for an agent selecting and invoking the 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?

The schema has 0% description coverage for the two parameters limit and cursor, and the description does not mention either. It does not explain pagination, cursor semantics, default page size, or maximum limit, so the description fails to compensate for the low schema coverage.

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

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

The description states it discovers 'authorized published template metadata,' which gives a resource and an action, but the verb 'discover' and jargon like 'safe projection' make the core list operation less immediate than a plain 'list templates'. It does not explicitly contrast with siblings such as templates_get or template_versions_list, so an agent must infer 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?

The description says legacy and unsupported versions remain unavailable and only frozen flat-video-v1 versions are render-ready, but that is availability context rather than when-to-use guidance. There is no explicit instruction on when to choose this tool over templates_get or template_versions_list.

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

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

Beyond the annotations, it discloses authorization scoping, safe projection, render readiness, lack of personalization, and unavailability of legacy versions. This is useful behavioral context, though it does not describe output shape, which 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 short and front-loads the main purpose before adding constraints. The semicolon-heavy wording is somewhat dense, but every sentence adds relevant context.

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

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

For a two-parameter get operation, the description omits the central parameter semantics and does not clearly differentiate it from sibling lookup/list tools. The annotations and output schema cover safety and return values, but the input-side context remains incomplete.

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

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

There are two required parameters, id and version_id, with 0% schema description coverage, and the description does not mention either parameter or explain their UUID format or relationship. The schema's UUID pattern is the only parameter guidance.

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 says it discovers authorized published template metadata, but it never explicitly states that it retrieves a single template version by id and version_id. It is distinguishable from template_versions_list only implicitly, so the core operation is vague.

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 availability constraints, such as only frozen flat-video-v1 versions being render-ready and legacy versions being unavailable, but it does not say when to use this tool rather than templates_get or template_versions_list.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, yet the description still adds substantive context: results are a safe projection only, only explicitly frozen flat-video-v1 versions are render-ready, and legacy/unsupported versions are excluded. That is real behavioral information beyond the annotation profile, though it stops short of describing ordering or how the cursor behaves.

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

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

Three compact sentences with the scoping facts front-loaded, but the phrasing is dense and jargon-heavy ('safe projection', 'explicitly frozen flat-video-v1') and the opening 'Discover' is vague enough to waste the prime slot.

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, but for a paginated, id-scoped list tool with zero parameter documentation and no mention of the alternative template_versions_get, the description leaves important gaps for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does not. Neither the required UUID 'id' (presumably the parent template) nor 'limit' nor 'cursor' is mentioned, leaving pagination and scoping entirely undocumented.

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 it surfaces published template metadata and hints at version-level state ('frozen flat-video-v1 versions'), but it never uses a clear verb+resource like 'list versions of a template' and never mentions the required template id that drives the operation. It also does not distinguish itself from siblings template_versions_get or templates_list, so an agent must infer the resource from the name 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?

There is no explicit when-to-use guidance and no reference to alternatives. The closest thing is a partial exclusion ('legacy and unsupported versions remain unavailable'), which describes filtering behavior rather than a decision rule for choosing this tool over template_versions_get or templates_list.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds meaningful behavioral context beyond that: revocation or expiry blocks finalization but does not revoke an already issued 2-hour storage capability. This nuance is not available from the annotations and helps an agent reason about edge cases, though auth and error behavior remain unspecified.

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 written sentences with no wasted words. The primary purpose is front-loaded in the first sentence, and the second sentence adds a relevant behavioral caveat without diluting the core message.

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 already cover the safety profile. The description supplies the key operational nuance about finalization and storage capabilities. The remaining gap is the meaning of the 'id' parameter, but that is primary a parameter-semantics issue for a simple single-identifier read 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 input schema has one required parameter, 'id', but provides no description for it (0% schema description coverage). The tool description does not explain what the ID refers to or how it should be sourced, leaving the agent to infer that it is an upload identifier. For a low-coverage schema, the description should compensate but does not.

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

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

The description uses a specific verb and resource: 'Read upload status and finalization deadline.' This clearly identifies the operation and the upload resource, making it distinguishable from sibling tools like assets_get or templates_get. It does not explicitly name or contrast with any alternative, which keeps it just below a 5.

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

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

The description states what the tool reads but gives no guidance on when to call it versus alternatives. There is no mention of prerequisites, workflow position, or conditions under which this tool should be preferred over another sibling.

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