Bardiyah

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

Annotations already cover openWorldHint=false and readOnlyHint=false, and the description reinforces those with 'fetches nothing from YouTube... and publishes nothing' and 'Bardiyah stores the number you send and never works one out itself'. It also discloses workspace scoping ('a script the signed-in user can edit') and deterministic storage of the rating, which annotations cannot express.

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

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

The critical constraints (append, no external calls, mandatory final section) are front-loaded and the format spec is precise. It is somewhat verbose and repeats the 'stores the number, never computes one' idea in two separate sentences, which costs a point.

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 6-param mutation tool with no output schema, the description covers purpose, side effects, dialect, and the non-obvious mandatory formatting rule. The only gap is that it never says what is returned (section id, updated script, etc.), which the agent cannot infer without an output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real constraints beyond it: the exact section title 'Viral Score', the required body structure (bold 'N / 10' line, dialect-specific header, 3-5 bullets, weakness line), and the requirement that the sent rating match the section. That is substantive value over the schema's field-level docs.

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 (add), resource (a section — defined inline as 'a titled piece of the script'), and target (the end of a specific script). This is clearly separable from update-script, which edits existing content rather than appending sections.

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 to draft or extend a script one section at a time' gives a clear usage context, and the mandatory final 'Viral Score' section rule is unambiguous. It doesn't explicitly say when to prefer this over update-script, but the append-only framing makes the split obvious.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive, closed-world mutation. The description adds genuinely new behavior: all-or-nothing semantics (if any file is missing, nothing is added and the missing one is reported) and append-after-existing-media ordering. It does not discuss retry safety despite idempotentHint=false, 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?

Purpose is front-loaded in the first clause, and each subsequent sentence carries distinct information: ordering, append position, atomic failure, and reporting to the user. The final reporting sentence is slightly verbose but earns its place given there is no output schema.

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

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

For a 2-parameter mutation with no output schema, the description covers prerequisites, ordering, atomicity, and what to report back (count, order, cover file). The remaining gap is that the upstream preparation tool is referred to only as 'the preparation' rather than by name or ID-passing mechanics.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, which sets the baseline at 3. The description reinforces the ordering requirement for 'uploads' and the post-scoping for 'id' but adds no format or syntax detail beyond the schema.

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

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

States a specific verb and resource — finishing the addition of media files to a post on the content calendar — and clarifies it is the terminal step after preparation commands have run. It implicitly separates itself from prepare-post-media-upload but never names that sibling explicitly, so the pairing is inferred rather than stated.

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

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

Gives a clear precondition: call only after every command from the preparation has run, and send uploads in the same order. It stops short of explicit when-not-to-use guidance or naming the alternative tool, but the sequencing context is strong enough for correct invocation.

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?

Given that the annotations are minimal and generic, the description bears the full burden of behavioral disclosure. It provides crucial traits like the structure for carousel slides (one entry per slide) and the dependency on the `prepare-post-media-upload` process for file-based media.

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 tool is inherently complex, leading to a very long description. While well-structured and not repetitive, its length sacrifices ultimate conciseness, though the detailed categorization helps organization.

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 definition is extremely complete for this complexity. It covers all edge cases mentioned in the schema, from platform defaults to the specific process of adding computer files, ensuring an agent has all necessary context to invoke 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?

Although schema coverage is 100%, the description adds high semantic value by explaining how parameters interact. For instance, it specifies that `is_primary` is restricted to 'main video' or 'short clip,' and that the `title` parameter is only needed when the post has no script.

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 immediately identifies its core function as adding a post to the content calendar, specifying the breadth of supported media types (video, image, carousel, text). It is highly specific and clearly defines its scope within the content management system.

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 acts as a comprehensive functional guide, providing explicit rules for complex logic, such as when to use a script title versus a custom title. It also dictates clear operational procedures, such as how to handle media uploads (prepare/run/confirm) and when to save as a draft vs. schedule.

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 non-read-only, non-destructive, closed-world profile; the description goes further and discloses exactly what will and will not happen -- 'creates no playlist, publishes nothing, and fetches nothing from YouTube or any other outside service'. That is genuine value beyond the flags. It omits any note on return value or whether the record is immediately visible/editable, keeping it at a 4.

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

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

Front-loaded with the definition, then usage, then scope boundaries -- a good ordering. Four sentences with little waste, though 'in their own Bardiyah workspace' and the final sentence about scripts and ideas are slightly redundant with what precedes them.

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 create tool with full annotations, complete schema coverage, and no output schema, the description covers what is created, where it lives, and what side effects are avoided. The remaining gap is whether `project` or `project_id` is expected and what happens if neither is supplied -- an agent could still be unsure about project placement.

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

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

Schema description coverage is 100% and every property is documented, so the baseline is 3. The description adds a small amount ('only records the title, kind and description you provide', loosely mapping 'kind' to the `type` parameter), but it says nothing about `project` vs `project_id` precedence or that only `title` is required, so it does not meaningfully out-perform 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 ('Create a content series') and immediately defines the resource as 'a planning record inside a project ... in their own Bardiyah workspace'. This distinguishes it from list-content-series and get-content-series, which read rather than create, and from create-project/create-script, which target different record types.

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

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

Gives an explicit triggering condition: 'Use this when several planned videos belong together as a season or a recurring format.' That is a clear context for selection. It stops short of naming an alternative (e.g. create-project for non-series groupings) or a when-not-to-use case, so it falls short of a 5.

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

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

Annotations already cover the safety profile (not read-only, not destructive, not idempotent). The description adds real value with the authorization constraint ('a project the signed-in user can add to'), but says nothing about duplicate handling, what is returned, or what happens when project and project_id disagree.

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

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

Three short sentences, front-loaded with the action and scope, no filler. Every sentence carries information.

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

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

For an 8-parameter mutation tool with no output schema, the description leaves the agent unsure what is returned (an item id?) and how the optional status/quantity/assigned_to fields behave. Adequate but with clear gaps around return values and creation semantics.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters including the Arabic guidance on project vs project_id. The description only restates that name and category are required, adding nothing beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Add a piece of equipment') plus the container ('to a project'), which is enough to tell it apart from get-/list-/update-equipment-item. It stops short of naming a sibling or contrasting with update-equipment-item, so it is clear but not maximally differentiated.

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 to build out a kit list for a shoot' gives an implied scenario, and the permission clause hints at a prerequisite. But it never says when NOT to use it (e.g. to modify an existing item, use update-equipment-item) and names no alternative.

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

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

Annotations already establish write, non-destructive, non-idempotent, closed-world behavior, so the bar is lower. The description adds that title derivation happens server-side and that the target is the signed-in user's scope, but it never warns that repeated calls will create duplicates (relevant given idempotentHint=false) or what permissions project attachment requires.

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 action, then the required input, then the optional ones. No filler and no restatement of name or title.

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

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

With no output schema, the description should say what comes back — it hints that the reply names the default project but not that the created idea (and its id) is returned, which an agent needs for follow-up calls. Otherwise it is complete for a single-required-param create 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 100%, so the schema already documents every parameter, including the Markdown rules and project defaulting. The description only restates the statuses and the optional project in prose, adding no syntax or format detail beyond the schema; baseline 3 applies.

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

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

The first sentence names a specific verb and resource: "Capture a new content idea for the signed-in user." That clearly separates it from get-idea and update-idea by name alone, though it never explicitly names those siblings or states what it is not for.

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 tells the agent the body is required, the title is optional and auto-derived, and project attachment/status are optional extras — enough context to call it correctly. It does not state when to prefer update-idea (for an existing idea) or any exclusions, so no full 5.

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

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

Annotations already declare non-readOnly, non-destructive, non-idempotent, so safety is covered. The description adds a genuine behavioral fact beyond annotations – that ownership is automatically assigned to the signed-in user – but says nothing about what is returned (e.g. a new project ID) or what failure modes to expect.

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

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

Short and front-loaded with the core action. Minor waste: sentence one ('owned by the signed-in user') and sentence three ('the signed-in user becomes the project owner') duplicate the same point.

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 creation tool with full annotations and full schema coverage, the description covers action, required input, and ownership side effect. The only meaningful gap is that, with no output schema present, it never hints at what the call returns.

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

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

Schema description coverage is 100%, so both parameters are already fully documented with required/optional status. The description restates the same name/website facts without adding format constraints, length limits, or URL validation rules.

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

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

States a specific verb and resource ('Create a new project') with the scope of ownership made explicit. It doesn't need to distinguish from a sibling create-project tool since none exists, though it never distinguishes itself from update-project or list-projects.

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 by the verb 'Create'; there is no statement of prerequisites, when to prefer this over update-project, or what happens on duplicate names. The 'provide a name and, optionally, a website' line is minimal invocation guidance rather than selection 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?

Goes well beyond the annotations: the new script inherits the user's default status, an omitted project_id falls back to the default project and the reply names it, only reachable platform_ids are accepted, and viral_score is stored verbatim with 0 refused. These are exactly the non-obvious side effects an agent needs before writing.

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

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

Front-loads the create action and sequences the follow-up steps in order, so it is easy to scan. It is slightly padded — the "not a lesser one" reassurance appears here and again in the schema — and the ordering advice could be tighter.

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

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

Covers the full call sequence (create, add sections, close with the Viral Score section), all defaults, and even what the reply reports back despite there being no output schema. Nothing essential for a correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents every parameter, and most of the description's parameter talk (title required, project optional) restates it. It does add real meaning about viral_score being the agent's own rating that the server never computes, plus the in-call platform batching rule, but that is incremental over an already complete 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?

Opens with a specific verb and resource ("Create a script for the signed-in user") and implicitly scopes it against update-script and get-script by describing an initial-state creation. It also distinguishes the object itself (a script without a project is ordinary), so an agent knows exactly what is being produced.

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

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

Gives clear when-and-how guidance: project naming is optional and must not be guessed, platforms belong in this same call rather than a second write, and the create must be followed by add-script-content with a final "Viral Score" section. It never states the exclusion case (modifying an existing script belongs to update-script), so it stops short of full alternative routing.

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

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

Annotations already declare non-readOnly, non-destructive, non-idempotent, closed-world, so the description's job is the extra context; it does contribute the write-permission precondition and the required-field constraint. It says nothing about duplicate detection, what happens when a linked name is ambiguous (that is only in the schema), or what a successful call returns.

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

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

Three short sentences with the scope and the required fields front-loaded. The final sentence ('lay out the logistics for a day of filming') largely paraphrases the first, a small redundancy but not harmful.

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

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

For a 14-parameter creation tool with full schema coverage and no output schema, the description supplies the permission precondition and required inputs, which is most of what the schema does not. The linking-by-name matching behavior and its ambiguity failure mode live only in the schema, so the description is adequate rather than complete.

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

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

Schema description coverage is 100%, and the individual parameter descriptions already cover naming conventions, date format, name-vs-id fallback, and add-only linking semantics, so the schema carries the burden. The description only restates that title and date are required, which the schema's required array already declares.

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 pair ('Plan a shoot day') and scopes it to a project the user can write to. It never explicitly contrasts with update-shoot-day or get-shoot-day, so sibling differentiation is implied by the name rather than stated in the description.

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 to lay out the logistics for a day of filming' gives an implied usage context, and 'inside a project the signed-in user can add to' adds a permission precondition. There is no explicit when-not-to-use guidance and no named alternative for modifying an existing day rather than creating one.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and non-idempotent, so the safety profile is covered. The description adds genuinely non-obvious behavior the schema cannot express: an entitlement gate that rejects feature kinds the account lacks, and that the storyboard is created empty with cards/shots populated later in Bardiyah. It omits error shape and whether the new storyboard id is returned, which keeps it below 5.

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

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

Three short sentences, front-loaded with the action, then the parameter warning. No filler, though the closing clause about Bardiyah is terse enough to be slightly ambiguous about what it means for the caller.

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

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

With 5 flat parameters, no output schema and no nesting, the description covers the main risk (wrong feature kind) and the post-creation state. It could say more about what happens to script_id when omitted, but overall an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema, and the description adds only the refusal consequence of the type enum. No added meaning for title, script, script_id or status — baseline 3 applies.

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

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

Opens with a specific verb+resource: "Create a storyboard for a script." That distinguishes it from get-storyboard, list-storyboards and update-storyboard, but it never names those siblings or states scope explicitly, so the differentiation is inferred rather than declared.

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?

"Choose the kind carefully: basic, advanced and cinematic are separate features, and one the account does not have is refused" gives real guidance on how to pick the type parameter and what failure looks like. However there is no guidance on when to use this versus create-script or update-storyboard, so usage context is only implied.

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

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

Annotations already declare the write/non-destructive/non-idempotent/open-world profile, so the bar is lower. The description usefully adds the permission constraint ('a project the signed-in user can add to') and clarifies that only the title is mandatory while all other fields are free-form brief content. It does not say what happens on a duplicate or failed project match, nor what a repeated call produces despite idempotentHint=false.

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

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

Three short sentences, front-loaded with the action and scope, then the usage rationale, then the one structural fact about required fields. No filler, though the middle sentence is the weakest and could be merged.

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 12-parameter creation tool with no output schema, the description leaves the return value unstated (does it return the created brief or just confirmation?) and says nothing about project resolution failure or duplicate briefs. The permission note and the required-field note carry most of the load; annotations handle safety.

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

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

Schema description coverage is 100%, so the 12 parameters are already documented in the schema, including the project-vs-project_id fallback and the name-matching disambiguation behavior. The description only adds that brief_title is the sole required field and the rest constitutes the brief body — helpful framing but no new per-parameter meaning, so baseline 3 applies.

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

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

States a specific verb and resource ('Write a thumbnail brief') plus a scope condition ('inside a project the signed-in user can add to'). Creation versus the get/list/update-thumbnail-brief siblings is inferable from the name and verb, but the description never names an alternative, so it stops short of a 5.

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

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

'Use this to specify what a thumbnail has to communicate before anyone designs it' gives an implied workflow phase (pre-design), which is real but thin guidance. There is no when-not guidance, no mention of update-thumbnail-brief for revising an existing brief, and no prerequisites such as needing a project first.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuine behavioral value by enumerating what 'in full' means — title, type/role, platforms, publish timing, status, captions/CTA, parent script or project, and a media summary — which tells the agent how much payload to expect versus a list row. It does not cover not-found behavior, but with annotations carrying the risk profile this is a solid addition.

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 that spends its length on the field breakdown rather than preamble. The enumeration is long but each item earns its place by previewing the return shape; a slightly tighter grouping would read better.

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

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

With no output schema, the description carries the burden of describing the response and does so comprehensively, listing every category of returned data. Remaining gaps — error/not-found handling and any access constraints on the referenced project or script — are minor for a simple read-by-id 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?

One parameter with 100% schema description coverage; the schema already explains that the id comes from search results or the list view. The description adds no further semantics about the identifier, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Fetch one post on the content calendar') and signals single-record scope with 'one post', which implicitly contrasts with list-content-schedules. It does not name the sibling alternative explicitly, but an agent can tell this is a by-id detail fetch rather than a list operation.

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

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

Usage is only implied: an agent infers this is the detail call after search or list. There is no explicit 'use this when you have an id; use list-content-schedules or search to find one first' routing, and no note on what happens if the id does not exist.

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 structurally. The description adds value annotations don't: it describes the payload as a full record including its description, kind and parent project — the only return-shape information available, since there is no output schema. Not-found/error behavior is unmentioned, keeping it below a 5.

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

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

Two sentences, zero filler, with the scope ('one ... in full') front-loaded before the discovery guidance. Every clause earns its place by either defining the resource or routing to the right sibling.

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, read-only lookup with full schema coverage and rich annotations, the description supplies what structured data does not: the returned facets and the prerequisite discovery step. Only the failure mode for an unknown id is left implicit, a minor gap given the simplicity of the 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 100% and the single parameter 'id' is already documented in the schema as the record number from search or list results. The description reinforces that the id must come from a prior listing step but adds no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Fetch one content series in full') and immediately scopes it to a single record, distinguishing it from the list sibling by the word 'one'. It also enumerates the returned facets (description, kind, parent project), so an agent knows exactly what this call yields versus list-content-series.

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

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

Explicitly routes the agent to 'list-content-series or search' to obtain the identifier before calling, which is the main prerequisite for a get-by-id tool. It gives clear context but stops short of stating exclusions (e.g., don't use this when you need many items at once), leaving that to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered and not contradicted. The description adds value by disclosing what the record contains (category, quantity, status, carrier, notes), which tells the agent what it will actually get 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?

One sentence, front-loaded with the action and scope, with zero filler. Every clause (single item, full record, field list) carries information.

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

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

No output schema exists, so the description's field enumeration is what tells the agent the shape of the response — appropriate for a simple one-parameter read. It could still note behavior for an unknown id, but that is a minor gap for a read-only getter.

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?

Single parameter with 100% schema description coverage, where the schema already explains the id as the record number from search results or the list. The description adds no further syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb ('Fetch') and resource ('one equipment item in full') and enumerates the fields returned, which clearly separates it from list-equipment-items. It does not explicitly name the list sibling, but 'one ... in full' vs. listing is unambiguous to an agent.

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: fetch a single item when you already have its id. There is no statement of when to prefer list-equipment-items or search to locate an id, and no exclusion or prerequisite guidance beyond the required id.

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, closed-world operation, so the description does not need to repeat that. It adds useful content categories (map link, best time to shoot, parking/safety/sound notes), but does not disclose missing-record behavior or field optionality.

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 front-loaded sentence with no wasted words. It immediately states the action, scope, and the kind of content returned.

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 single-record retrieval tool with rich annotations and 100% schema coverage, the description is nearly sufficient, and it usefully names several returned fields despite there being no output schema. It could be fuller about the complete shape of the returned record, but it covers the core use case.

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 only one parameter, and the schema already documents it at 100% coverage with a clear Arabic description explaining that the ID comes from search results or a list. The main description does not add any further semantics for the 'id' parameter, so the schema is doing the work.

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

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

The description states a specific verb ('Fetch') and resource ('one filming location') and clarifies that it returns the full record rather than a list. This implicitly distinguishes it from list-filming-locations and update-filming-location, but it does not explicitly name those siblings.

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

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

The phrase 'Fetch one filming location in full' implies this is the detail-retrieval tool to use when a single record is needed. However, it gives no explicit guidance on when to use list-filming-locations or search first, nor when to use update-filming-location instead.

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

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

Annotations already declare read-only, idempotent, non-destructive, so the description isn't burdened with safety disclosure. It still adds genuine context beyond them: the ownership scoping rule and the failure mode (error when the idea is missing or owned by someone else), which an agent needs to anticipate error responses. It doesn't describe response shape in detail, but no output schema exists and the key returned fields are listed.

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

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

Three tight sentences: what it returns first, the edit workflow second, the error condition last. No filler, and the most important content is front-loaded.

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

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

For a one-parameter read with no output schema, the description covers the return contents, the ownership constraint, the error case, and the follow-on tool. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the single id parameter is already documented as 'taken from a search or a listing'. The description adds no syntax, range, or lookup guidance beyond that, so it earns the baseline rather than more.

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

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

States a specific verb+resource+scope: fetch a single content idea owned by the signed-in user, returning full text, status and project. The singular 'one idea' plus the ownership restriction cleanly separates it from list-ideas and from the sibling get_* tools for other resources.

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?

Presents a concrete workflow: read the text, revise it, then hand the revision to update-idea — an explicit named alternative for the write path. It stops short of stating when to prefer it over list-ideas or search, but the 'fetch one' framing implies that.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered; the description adds real value by disclosing the failure modes (error if the project is missing or inaccessible) and enumerating what the response includes. It stops short of describing pagination or formatting, but that is minor for a single-item getter.

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

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

Two sentences, front-loaded with the core action, then the error behavior. The field enumeration is dense but each clause adds decision-relevant information; nothing is filler.

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

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

With no output schema, the description carries the return-value burden and does so adequately by naming the included fields and the error case. Slightly more precision about the returned shape would be ideal, but an agent has enough to call it correctly.

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

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

Schema coverage is 100% and the single 'id' parameter is documented there ('taken from a search or a listing'); the description adds no format, range, or sourcing details beyond that. Baseline 3 applies.

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

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

Specific verb+resource: 'Fetch a single project the signed-in user can access', plus a breakdown of what the payload contains (counts, goal, brief with audience/tone/language/instructions). The singular 'single project' implicitly separates it from list-projects, but no sibling is named outright.

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 access scoping and the error condition, but there is no explicit guidance on when to call this versus list-projects or search, nor any mention that the id comes from a prior listing (that hint lives only in the schema).

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description adds real context: sections returned in order, text returned in an editable form, and an error on missing or inaccessible scripts. Return format detail is helpful but still thin on ordering guarantees or section shape.

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

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

Three short sentences with the core behavior front-loaded and the error condition last. Every sentence contributes, though the middle sentence is slightly awkwardly phrased relative to how crisp the rest is.

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

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

With no output schema, the description carries the burden of describing return values and does so (sections in order, editable text). It is complete enough to call correctly, with only minor gaps like whether ordering is guaranteed across all section types.

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

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

Schema coverage is 100% and the single parameter is already documented as an id sourced from search or listing. The description adds no syntax, format, or validity detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ('Fetch one script') plus scope ('all of its sections in order'), which cleanly separates it from list-scripts and the get-* family. An agent can identify the operation without opening the schema.

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

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

The line about editing the returned text and sending the revision 'back the same way' signals the retrieve-then-update workflow, and the error condition for unreachable/absent scripts is stated. It stops short of naming the sibling (update-script) explicitly, so the alternative is implied rather than spelled out.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value by enumerating the returned payload (weather, transport, permits, backup plan), but says nothing about failure behavior for a missing id or the record's language/format.

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

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

A single sentence, front-loaded with the verb and resource, followed by the payload enumeration. Every clause carries information; nothing is redundant.

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

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

With no output schema, the description usefully enumerates what comes back so the agent knows one call suffices for date, call time, weather, transport and permits. The only gap is what happens when the id does not resolve to a record.

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 only one parameter and schema description coverage is 100%, with the schema itself explaining that the id comes from search results or the list. The description adds no syntax, range, or cross-reference detail beyond that, so the baseline 3 applies.

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

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

A specific verb ("Fetch") plus resource ("shoot day") with scope made explicit by "one ... in full", which implicitly contrasts with the sibling list-shoot-days. It stops short of naming the sibling outright, so differentiation requires slight inference.

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: an agent can infer this is the detail lookup for a single record after list-shoot-days or search. There is no explicit when-to-use statement, no mention of alternatives like list-shoot-days, and no guidance on what to do if the id is unknown.

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. Beyond that, the description adds valuable scope information: it returns only title, kind, and workflow status, and nested storyboard content is not handled here.

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

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

Two sentences, front-loaded with the core action and immediately followed by the important scope limitation. No unnecessary repetition or 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 one-parameter read tool with rich safety annotations and no output schema, the description supplies the key return fields and the important exclusion about nested editing. An agent has enough information to call it correctly.

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

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

Schema coverage is 100%, and the id parameter is fully documented in the schema as coming from search results or a list. The description does not add any additional meaning about the parameter, so the baseline 3 applies.

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

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

The description states a specific read verb and resource: fetch one storyboard. It clarifies the returned scope (title, kind, workflow status) and explicitly excludes nested cards/shots/scenes, which distinguishes it from list/update/create siblings and from tools that would edit storyboard internals.

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 'fetch one' and the schema's required id, and the description gives one useful exclusion: nested cards/shots/scenes are edited in Bardiyah rather than through this server. However, it does not explicitly say to use list-storyboards first to find the id or otherwise contrast this with sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only the notion of completeness ("in full"), and stays silent on behavior when the id is missing or invalid and on whether absent fields can appear. Useful but thin on top of 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?

One front-loaded sentence with no filler; the outcome is stated before the field enumeration. The dash-list of fields is long but each item is substantive information, not padding.

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

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

With no output schema, enumerating the returned content (concept, subject placement, emotion, text direction, background, palette, focal object) is exactly the right compensation and tells the agent whether it needs this tool at all. Missing only error/not-found behavior and the discovery path for ids.

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

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

Schema description coverage is 100% and the sole parameter's schema text explains where the record number comes from (search results or the list). The description adds nothing about the id itself, so baseline 3 applies since the schema carries the burden.

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

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

States a specific verb (fetch) and resource (one thumbnail brief) plus the exact payload fields returned, so an agent knows precisely what comes back. It does not name the sibling list-thumbnail-briefs, so the single-vs-list distinction is implied by "one" rather than stated.

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

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

"Fetch one thumbnail brief in full" implies a single-record lookup keyed by an existing id, and the schema hint ties the id to prior search/list results. There is no explicit when-to-use guidance, no statement that this is the wrong choice for browsing, and no pointer to list-thumbnail-briefs or search for obtaining ids.

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 is free to add what they cannot: that results are scoped to the signed-in user and that entries are short summaries rather than full records. It also enumerates the fields returned (title, type, episode vs. supporting, platforms, publish date, status, media summary), which meaningfully tells the agent what to expect.

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

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

Three sentences, front-loaded with the core list operation and followed by the escalation path to get-content-schedule. The middle field enumeration is long but earns its place since there is no output schema; nothing is redundant.

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

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

With no output schema, the description carries the burden of describing return shape and does so adequately, including the summary-vs-full distinction. Minor gap: it does not mention pagination defaults or result ordering despite page/per_page parameters existing.

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

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

Schema description coverage is 100%, so all five parameters including page, per_page, search, script, and script_id are already documented. The description only gestures at the script filter ('narrowed to a single script by name') and adds nothing about pagination or search, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List the posts on the signed-in user's content calendar') plus the scope modifier (with or without a script). It also explicitly separates this from get-content-schedule, so an agent can distinguish the list operation from the single-item fetch without opening either schema.

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

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

Explicitly routes the agent to get-content-schedule when a full record is needed, and names the narrowing condition ('by script name'). It stops short of stating when not to use this tool (e.g., when the user wants series or ideas rather than calendar posts), so it is clear context without full 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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new behavioral facts: results are short summaries rather than full records, and the result set is bounded by what the signed-in user can reach. Pagination behavior is left to the 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?

Four short sentences, front-loaded with the action and scope, then the concept definition, then the result shape, then filter options. No wasted clauses and nothing buried at the end.

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

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

With no output schema, the description compensates by stating the return shape (short summaries) and pointing to the detail tool. Five fully documented, all-optional parameters plus read-only annotations mean nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and each parameter is described (page, search, project, per_page, project_id), so the baseline is 3. The description only restates the project-narrowing and title-search modes in prose without adding format or interaction semantics beyond the schema.

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

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

States a specific verb and resource ("List the content series") plus the access scope ("the signed-in user can reach"), and defines the domain concept ("A series groups related videos — a season, a recurring format, a themed run"). It also names the sibling get-content-series, so the agent can distinguish a list call from a detail call without opening either schema.

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

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

Gives clear routing guidance: use this for short summaries, call get-content-series for one in full. Also notes the two narrowing modes (project, title search). It stops short of any explicit when-not condition or prerequisite, so it is a strong 4 rather than a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description still adds real behavior beyond them: results are permission-scoped to what the signed-in user can reach, and the payload is deliberately summary-level rather than full records. It does not mention pagination behavior or total counts, which keeps it from a 5.

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

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

Three short sentences with no filler, front-loaded with what is returned and immediately followed by the sibling hand-off. Every clause carries information the agent needs to choose or call the tool.

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

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

For a read-only, zero-required-parameter list tool with full schema coverage and no output schema, the description covers scope, result shape, and the escalation path to the detail tool. Pagination defaults and total-count behavior are left entirely to the schema, which is a minor gap rather than a blocking one.

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

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

Schema description coverage is 100%, so the five parameters are already documented, and this is the baseline case. The description only reinforces the project-name narrowing and the fact that availability is returned; it says nothing about search, page, or per_page, and does not clarify project vs project_id beyond what the schema says.

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

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

States a specific verb and resource ("List the equipment"), plus the scope ("the signed-in user can reach") and what each result carries (category, availability). It also names the sibling get-equipment-item as the detail-view counterpart, so an agent can distinguish the two without opening a schema.

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

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

"Returns short summaries; call get-equipment-item for one in full" gives an explicit alternative and the condition that selects it, and "can be narrowed to one project by name" gives a usage cue for filtering. It stops short of saying when not to use this tool or how the two project filters differ, so it is clear context rather than a full routing rule.

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

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

Annotations already declare readOnlyHint, idempotentHint and closed-world, so safety is covered. The description adds real behavioral context beyond them: results are permission-scoped to what the signed-in user can reach, and records come back as short summaries rather than full objects.

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, zero filler. The scope and returned fields come first, and the hand-off to the detail tool is front-loaded where an agent will act on it.

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

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

With no output schema, the description carries the burden of explaining return values and does so (summaries with kind and name). Access scoping and the detail-tool hand-off are covered; only paging/filtering behavior is left entirely to the schema, which is acceptable.

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

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

Schema description coverage is 100%, so page, per_page and search are already documented, which sets the baseline at 3. The description adds nothing about filtering or paging semantics, and the schema descriptions are in a different language than the description, so there is no extra clarification.

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 (filming locations), adds the access scope (locations the signed-in user can reach), and names the fields returned (kind, name). It also explicitly distinguishes itself from get-filming-location, so an agent can route between the two without opening either schema.

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

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

Names the alternative get-filming-location and the exact condition that selects it (need one in full rather than a summary). No exclusions or guidance about pagination/search usage, but the primary use/alternative split is explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: results are truncated summaries, not full documents, and the scope is limited to the signed-in user's own ideas. It stops short of stating anything about ordering or empty-result behavior, which is why it isn't 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 purpose, then the return-shape caveat, then filters, then routing. The final routing sentence slightly duplicates intent already implied earlier, but every sentence still carries weight.

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

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

With no output schema, the description usefully characterizes the return value as truncated summaries and points to the tool that returns full text. It covers search, status, and paging adequately, but omits the project_id scoping option, leaving one of five parameters unaddressed outside the schema.

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

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

Schema coverage is 100%, so baseline is 3. The description restates what the schema already documents — free-text search over title and body, the three status values, paging — without adding format, matching semantics, or combinability rules, and it never mentions the project_id filter at all.

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 ("List the signed-in user's content ideas") and immediately distinguishes itself from get-idea by declaring it returns only short summaries. An agent can separate it from the ~15 other list-* siblings because the resource is named explicitly.

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

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

"Use this to find ideas before reading or editing one" gives the trigger, and "fetch the full text with get-idea" names the alternative and the condition that selects it. Nothing is left to inference about when this tool is the right entry point.

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 safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the description is not burdened with that. It adds useful behavioral context beyond annotations: the exact filter scope (owned + active member), the shape of the returned summaries (name, website, counts of scripts and ideas), and support for free-text search and paging. It does not contradict annotations.

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

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

The description is three tightly written sentences that front-load the scope, then describe return shape and alternatives, then note search and paging. Every sentence earns its place with no redundancy.

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

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

For a read-only list tool with no output schema, the description covers scope, returned fields, alternatives, search, and paging—enough for an agent to call it correctly. A minor gap is that it does not explicitly mention whether a project identifier is returned, which an agent might need to chain into 'get-project'.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters in detail. The description mentions free-text search over the project name and paging, which merely restates the schema's own explanations without adding syntax, defaults, or additional meaning.

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

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

The description states a specific verb and resource ('List the projects') and immediately clarifies the scope (owned plus active member). It explicitly distinguishes the tool from 'get-project' and 'search', which return detailed content, so an agent can tell this apart without opening any sibling schema.

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

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

It names the alternative tools explicitly ('call get-project for one project, or search to find content across all of them') and gives the condition that selects each one. It also states what the tool does not return ('not what is inside them'), providing clear when-to-use and when-not-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 readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real value by disclosing the return shape (title, project, status, rating) and that pagination applies. It stops short of saying what happens on an out-of-range page or how results are ordered, which is the only 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 compact sentences, each load-bearing: the first defines scope and exclusions, the second routes to alternatives and lists the narrowing options. The return-shape caveat is front-loaded before the alternatives, which is the right order for a browsing tool.

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

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

With no output schema, the description carries the burden and does it well by naming the four summary fields and confirming the writing body is excluded, while annotations cover the safety profile. Ordering and empty-result behavior are the only omissions, which is minor for a simple paged list.

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

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

Schema description coverage is 100%, so every parameter's meaning is already documented with defaults and ranges. The description's 'narrowed to one project, and searched by title' restates the schema rather than adding syntax or matching-behavior detail, so baseline 3 applies.

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

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

States a specific verb and resource plus the scope ('the scripts the signed-in user can reach') and explicitly names what it does NOT return ('never the writing itself'). It distinguishes itself from get-script and search by name, so an agent can separate the three without opening any schema.

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

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

Gives explicit routing: use get-script for the sections of one script, use search when hunting a phrase rather than browsing, use this when browsing. It also states the two narrowing modes (one project, title search), leaving no ambiguity about which sibling to pick.

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 bar is lower; the description still adds real value by disclosing the permission scoping ("the signed-in user can reach") and the return shape ("short summaries," full record via get-shoot-day). It omits ordering and pagination behavior, which the schema partly covers via page/per_page.

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 purpose, then return shape, then filtering options. Nothing is redundant and every sentence carries a distinct decision-relevant fact.

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

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

For a read-only, closed-world list tool with a fully documented 6-parameter schema and no output schema, the description covers purpose, scope, return granularity, and the escalation path to get-shoot-day. Only ordering/pagination expectations are unstated, a minor gap given the schema's page/per_page docs.

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

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

Schema description coverage is 100%, and the parameter descriptions already explain page, per_page, script, project, project_id, and search. The description's "narrowed to one project, or to the days filming a particular script, by name" restates the schema rather than adding new semantics, so the baseline 3 applies.

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

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

"List the days of filming the signed-in user can reach, with their dates and what each one is for" names a specific verb (list), the resource (shoot days), the scope (user-accessible), and the returned fields. It is immediately distinguishable from get-shoot-day and create-shoot-day in the sibling list.

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

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

It explicitly routes the agent to the alternative: "call get-shoot-day for one in full," which tells the agent when this tool is insufficient. It also states the two narrowing modes (project, script). It does not address when to prefer this over the generic `search` sibling, so it stops just short of a full when/when-not map.

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 context beyond that: results are permission-scoped to what the signed-in user can reach, returns are short summaries rather than full records, and filtering by script is possible.

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 list operation, then return shape, then the alternative and filtering hint. No sentence is wasted.

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

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

The description covers purpose, scope, return shape, and the key sibling alternative, while annotations and the fully described schema handle safety and parameter details. It could be slightly richer about filtering behavior, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents all five parameters including pagination, search, script, and script_id. The description only reinforces narrowing by script name and does not clarify the distinction between script and script_id or add syntax beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('List the storyboards') and narrows the scope to those the signed-in user can reach. It also explicitly distinguishes itself from get-storyboard by saying it returns short summaries while the sibling returns one in full.

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

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

Gives a clear routing rule for detail retrieval: call get-storyboard for a full record. It also notes narrowing by script name, but does not explicitly discuss when to use this versus search or list-scripts, so it falls just short of full alternative coverage.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds two things beyond them — that results are only the briefs the signed-in user can reach (permission scoping) and that the payload is short summaries rather than full records. It stops short of describing pagination behavior or what a summary 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 tight sentences, front-loaded with what is listed and what is returned, then the sibling redirect, then the narrowing options. 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 read-only list tool with four safety annotations, full schema coverage, and no output schema, the description covers purpose, output granularity (summaries), scope, and narrowing. Only default page size / result-volume expectations are left implicit.

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

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

Schema coverage is 100%, so all six parameters are already documented in the schema at a baseline 3. The description reinforces only two of them (project and script-by-name narrowing) and says nothing about search, page, per_page, or how project vs project_id interact.

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 ("List the thumbnail briefs") plus the access scope ("the signed-in user can reach"), and explicitly contrasts the result with the full-record sibling get-thumbnail-brief. An agent can tell it apart from create-thumbnail-brief/update-thumbnail-brief/get-thumbnail-brief without opening any schema.

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

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

"call get-thumbnail-brief for one in full" gives a clear alternative-and-condition, and the last sentence explains when to narrow by project or script name. What is missing is a note on when not to use it (e.g., the general `search` sibling for cross-entity lookup).

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

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

Annotations declare a non-read-only, non-idempotent, closed-world mutation but say nothing about the operation's shape. The description adds genuinely non-obvious behavior: the call yields one shell command per file to execute where the file lives, followed by a separate confirmation, and it imposes a secrecy constraint ('Never show the commands or their links to the person'). It does not disclose command expiry, failure behavior, or repeated-call semantics, so it is not a 5.

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

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

Three sentences, front-loaded with the supported media shapes, followed by the workflow and then the secrecy rule. No filler, though the critical 'Never show the commands' instruction sits at the very end where it is easiest to miss.

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

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

With no output schema, the description carries the burden of explaining what comes back and does so adequately: per-file commands plus a confirmation step. Remaining gaps — what happens on a failed or expired command, whether re-invoking replaces prior preparation, and the maximum of 20 files — are minor but real.

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

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

Schema description coverage is 100%, so the id and files fields (name, mime_type, size_bytes, ordering, cover semantics) are already documented. The description restates ordering and cover ('the first one is the cover') and the local-file origin but adds no new syntax or constraints. The phrase 'Name the post' is also slightly misleading, since no name parameter exists 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?

The description names a specific action and resource: preparing media files from the local computer for a post on the content calendar, and enumerates the supported shapes (single image, ordered carousel, or video). It does not explicitly name or contrast the sibling it pairs with (confirm-post-media-upload), but the preparation step is clearly distinct from the confirmation step.

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 establishes the context of use (adding local media, naming the post, ordering files with the first as cover) and describes the follow-on step ('then you confirm the upload'), which implicitly points the agent at confirm-post-media-upload. There is no explicit statement of when not to use it or how it differs from other content-schedule tools, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is free; the description instead spends its budget on behavior the agent could not otherwise know — lenient Arabic matching ('قصه' finds 'قصة', '٥' finds '5') so no manual spelling variants are needed, and that results are short summaries requiring a follow-up get-* call. That is exactly the value-add expected alongside annotations.

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

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

Front-loaded with the core verb and scope, then routing rule, then matching behavior, then return-value guidance, then exclusions — a sensible priority order. Slightly long, and the opening kind-enumeration is both partial and redundant with the `types` parameter, which costs a point.

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?

Complete for a search tool: what it covers, what it excludes, how matching behaves, what comes back (summaries) and which sibling to call next. With no output schema, the sentence about short summaries and follow-up get-* calls is precisely the missing piece an agent would otherwise have to guess.

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

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

Schema coverage is 100%, so the baseline is 3; the description rises above it by telling the agent how to form the required `query` (lenient normalization, no need to try variants) and by stating that the matched fields are titles and bodies. It adds nothing about `limit`, `cursor` or `project_id`, but those are fully documented 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 scope ('Search across everything the signed-in user has ... projects, scripts, the sections inside scripts, and ideas') and explicitly contrasts itself with the list tools. The only weakness is that its enumeration of searchable kinds is incomplete — the schema's `types` parameter also lists content series, scheduled items, storyboards, filming locations, equipment, shoot days and thumbnail briefs, so an agent reading only the description would under-estimate coverage.

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

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

Gives an explicit rule for choosing this over siblings ('Prefer this over the list tools whenever you are looking for something specific rather than browsing — the list tools page through everything, this matches text') plus explicit exclusions ('Does not search tasks, habits, personal subscriptions, or anything about billing'). Both the when and the when-not are covered.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description earns credit by explaining the real damage model: omitted fields are preserved, and "Sending slides replaces the whole list" warns that the one list-valued field is wholesale replacement rather than a merge. It adds scope and replacement semantics without contradicting the destructive hint.

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 and full field list, then three short constraint sentences. Slightly dense enumeration in sentence one, but every subsequent sentence adds a non-obvious rule rather than restating the schema.

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

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

For a 15-parameter mutation with no output schema, the description covers the essentials an agent needs: partial-update preservation, list replacement semantics, the primary-post rule, and the redirection of local file uploads. It says nothing about what the call returns or about permission/validation failures beyond the project-name ambiguity already noted in the schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes beyond it in two places: it prescribes that per-slide text belongs in slides and "never in the publishing notes," and it defines what is_primary means in workflow terms (the one post that advances its script). Those are routing decisions the enum and types alone do not convey.

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

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

The opening sentence names the verb and resource precisely ("Change a post on the content calendar") and enumerates the mutable surface: timing, type, title, platforms, primary flag, status, captions, slides, media links. It is clearly the mutation counterpart to create-content-schedule, though it never names a sibling explicitly.

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

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

The partial-update contract is stated plainly ("Anything you leave out stays as it is"), and media-from-disk work is explicitly routed away to the prepare/confirm upload flow instead of being attempted here. It lacks an explicit when-not statement such as preferring get-content-schedule to read current values first.

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

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

Annotations declare destructiveHint=true, which on its own could read as a full replacement; the description corrects that by stating 'Only the fields you pass are changed.' It also discloses a validation rule (an update that would empty the description is refused), which is behavior an agent cannot infer from the schema or annotations.

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

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

Two short sentences, front-loaded with the action and scope, followed by the two behavioral rules. Every clause carries information an agent needs; nothing is padding.

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

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

For a 4-parameter partial-update tool with full schema coverage and rich annotations, the description covers permission scope, patch semantics, and one validation rule. It does not mention failure behavior for a nonexistent id or what the call returns, but with no output schema and a small surface this 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema for the description field: passing an empty value is rejected. That is genuine constraint information the schema does not express.

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 ('Update') plus specific resource ('content series'), with an added authorization scope ('the signed-in user can edit'). It is clearly distinguishable by verb from create-content-series, get-content-series, and list-content-series, though it does not name them explicitly.

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

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

The precondition 'the signed-in user can edit' tells the agent this only applies to editable series, which is real usage context. However, there is no explicit guidance on when to update versus create or fetch, and no exclusions or alternatives are named.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and, importantly, destructiveHint=true; the description adds the patch semantics (only supplied fields change), which is genuine value the annotations don't express. However, it never addresses the destructive flag — no warning that existing values for supplied fields are overwritten, and nothing about permission-denied behavior. With annotations covering the safety profile, a 3 is fair.

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 scope, followed by the one behavioral rule that matters (partial update). 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 patch tool with full schema coverage and annotations, the description covers purpose, permission scope and patch semantics. It does not explain what is returned (no output schema, so the agent can't know if the updated record comes back) or acknowledge the destructive overwrite implied by destructiveHint=true, leaving meaningful gaps.

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

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

Schema description coverage is 100%, so all 7 parameters are documented in the schema and baseline is 3. The description enumerates four of the six updatable fields but silently omits name and category, so it adds partial rather than complete semantic value on top of 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 (update) and resource (equipment item) and even names the mutable fields (status, quantity, assigned_to, notes). The resource name clearly separates it from the many update-* siblings (update-project, update-script, etc.), though it doesn't explicitly route to create-equipment-item or get-equipment-item.

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 signed-in user can edit" hints at a permission precondition, and "Only the fields you pass are changed" tells the agent this is a partial update, which is real usage guidance. But there is no explicit when-to-use/when-not or comparison to siblings such as update-filming-location or create-equipment-item; the agent must infer that usage.

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

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

Annotations declare destructiveHint=true, so the agent needs to know that existing values are overwritten and are not recoverable — the description never says this and 'Only the fields you pass are changed' can be read as reassuring. Nothing is said about what happens on a bad id or whether the edit is reversible. The trailing Bardiyah sentence consumes space without adding behavioral context.

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

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

The first two sentences are tight and front-loaded with the key partial-update rule. The third sentence about new locations and country lists is irrelevant to this tool and creates noise an agent has to discard.

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

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

With no output schema, the description should carry return/error behavior, and it does not — no mention of validation failures, backup_location name-matching behavior, or confirmation of what changed. It does cover the permission precondition and the partial-update semantics, which are the two most important facts, so it is adequate but 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?

Schema coverage is 100%, so the schema already documents all nine parameters, making 3 the baseline. The description only mentions the four note-style fields (timing, parking, safety, sound) and omits location_name, location_type, map_link and backup_location, so it slightly under-represents the editable surface rather than adding meaning.

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

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

States a specific verb and resource ('Update a filming location') and adds a scope qualifier ('the signed-in user can edit') along with which kinds of content are typically refined. It is clearly distinguishable from get-filming-location and list-filming-locations, though it doesn't name a sibling explicitly.

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

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

'Only the fields you pass are changed' gives useful partial-update guidance, and 'the signed-in user can edit' implies a permission precondition. However there is no explicit when-to-use vs. alternatives, and the closing sentence about new locations in Bardiyah describes a creation scenario this tool does not perform, which muddies rather than guides.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered; the description adds the non-obvious behavioral facts: patch semantics, per-user ownership enforcement, and the specific error case for missing or foreign ideas. It does not explain what "destructive" means here (e.g. that idea_text is overwritten wholesale), which is left to the 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 action and scope, then the mutation semantics, then the failure condition. No sentence is redundant with the title or schema.

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

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

For a 5-parameter mutation tool with no output schema and destructiveHint=true, the description covers ownership, patch behavior and error cases adequately. It omits what a successful call returns, which an agent might reasonably want given no output schema.

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

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

Schema description coverage is 100%, so baseline is 3, and the description earns an increment by clarifying the semantics of the optional parameters as a group — omitted fields are left untouched rather than cleared. The per-field meaning of id, status and idea_text is fully carried by 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 ("Partially update a content idea") with ownership scope, which cleanly separates it from create-idea, get-idea and the update-* siblings for other resources. It stops short of naming a sibling or contrast alternative explicitly.

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

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

"Only the fields you pass are changed" implies when this is the right call (incremental edits rather than full replacement), and the ownership error clause sets a precondition. But there is no explicit guidance on when to use this versus create-idea or get-idea first, and no stated prerequisites.

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

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

Adds real behavior beyond the annotations: patch semantics (only supplied fields mutate) and the two failure modes (missing project, insufficient permission). However, the destructiveHint=true annotation is never elaborated — nothing says what is lost or whether changes can be reverted — so it falls short of a 5.

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

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

Three short sentences, front-loaded with the action and scope, zero redundancy. Every sentence carries a distinct fact: scope, patch behavior, failure modes.

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

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

No output schema exists, yet the description covers the mutation's effect and error conditions; only the success return shape is unstated, which is a minor gap for a three-field update 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 100%, so the baseline is 3; all three params (id, name, website) are documented in the schema with sourcing guidance for id. The description only adds the general patch rule, not parameter-specific meaning.

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

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

States a specific verb (update) and resource (project) plus an authorization scope ('the signed-in user owns or manages'), which separates it from get-project and create-project implicitly. It does not name any sibling explicitly, so it stops short of a 5.

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

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

'Only the fields you pass are changed' implies a partial-patch use case and the error sentence implies preconditions, but no explicit guidance on when to choose this over update-* siblings or get-project, and no exclusions are stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=false, so the description is not the sole carrier. It still adds real behavior: partial updates leave unsent fields untouched, the score is stored verbatim and never computed server-side, and specific failure conditions are named. The one gap is that destructiveHint is never addressed — overwriting an existing title or video type is not called out as irreversible.

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, front-loaded with the action and scope, then the update semantics, then failure modes. No filler, no restatement of the title.

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

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

Covers scope, partial-update contract, score storage rules and error conditions for a 5-parameter mutation whose schema is fully documented and whose annotations carry the safety profile. The residual gap is the return value: with no output schema, the description says nothing about what a successful call yields (e.g. whether the updated script is echoed back).

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

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

With 100% schema coverage the baseline is 3, but the description adds cross-parameter semantics the per-field descriptions cannot: omission means "leave alone" for every optional field, not just viral_score. The out-of-ten score rule is reiterated from the schema, so some overlap, but the partial-payload contract is genuinely new.

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

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

States a specific verb and resource ("Update a script") plus a scope qualifier (scripts the signed-in user can edit), which is enough to separate it from get-script/list-scripts/create-script. It doesn't explicitly name any sibling, so sibling differentiation is implied by the resource rather than stated.

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

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

"Only what you send is changed" communicates partial-update intent, and the error conditions (missing script, no edit permission) tell the agent when the call fails. But there is no explicit when-to-use guidance, no mention of alternatives such as update-thumbnail-brief or update-storyboard, and the dependency on obtaining `id` only appears indirectly in the schema.

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

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

The description does add value beyond the annotations: weather is user-supplied, no transport is booked, no permits filed, nothing fetched externally, and updates are partial. Yet annotations declare destructiveHint=true, and the description never warns that passing a text field overwrites its prior content (it only notes that list linking is additive via the schema). That is the one behavioral trait an agent most needs disclosed.

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

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

The purpose is front-loaded in the first clause, and the sentences are tight with no filler. The negative enumeration ('books no transport, applies for no permit, nothing fetched') is slightly repetitive but each clause carries distinct behavioral information.

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

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

For a 13-parameter tool with a fully documented schema and no output schema, the description covers the operation, the partial-update contract, and the no-external-effects guarantee. The notable gap is failure behavior (invalid id, permission denial) and the destructive overwrite semantics implied by annotations.

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

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

Schema description coverage is 100%, with all 13 parameters documented in the schema, so the baseline is 3. The description reinforces a handful of fields (date, call time, weather, transport, permits, backup plan) but adds no syntax or format guidance beyond what the schema already states.

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

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

The description names a specific verb and resource ('Update a shoot day') and enumerates the kinds of edits (date, call time, notes on weather/transport/permits/backup plan). That distinguishes it from get-shoot-day or list-shoot-days by role, but it never names a sibling explicitly (e.g., create-shoot-day for new days), so it stops short of a 5.

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

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

It scopes usage by permission ('the signed-in user can edit in their own Bardiyah workspace') and by semantics ('Only the fields you pass are changed'), which implies partial update rather than full replacement. However, it gives no explicit when-to-use/when-not guidance or pointer to alternatives like create-shoot-day or get-shoot-day for read-only inspection.

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 mutation, non-open-world, idempotent and destructive, so the description only needs to add context — and it does: an authorization requirement (the record must be editable by the signed-in user) and the precise blast radius ("Only the fields you pass are changed"), which meaningfully softens the destructiveHint framing. It does not say whether status transitions are reversible or what the 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?

Two short sentences, front-loaded with the action, zero filler. The inline enumeration of the editable fields costs a few words while being incomplete, which slightly dilutes value density.

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

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

For a 4-parameter mutation with rich annotations and full schema descriptions, the description covers the essentials but omits the `type` field, the feature-gating refusal condition, and any hint of what the call returns (there is no output schema to fall back on). Adequate, but with clear gaps.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds only the partial-update rule. It is arguably misleading on parameters: it frames the editable surface as title and status while the schema also exposes an enum-constrained `type` that the description never mentions, so an agent skimming prose could miss a mutable field.

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

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

States a specific verb+resource ("Update a storyboard") and narrows scope to the two edits it supports (retitle, workflow status), which separates it from create-storyboard/get-storyboard/list-storyboards by name convention. It never explicitly names a sibling, but the operation is unmistakable.

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

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

"The signed-in user can edit" gives a real permission precondition, and "Only the fields you pass are changed" signals partial-update behavior. Beyond that there is no when-to-use/when-not guidance and no pointer to get-storyboard or the create-* siblings for the cases where this tool is the wrong choice.

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

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

Beyond annotations, it discloses that the tool only records supplied text, generates/fetches no image, uploads nothing to external services, changes only passed fields, and refuses updates that would empty a section. It also states the permission scope ('signed-in user can edit in their own workspace'), and these details are consistent with 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?

It is front-loaded with purpose and scope, and the sentences about no external service and partial-update safeguards earn their place. The first sentence is long and clause-heavy, preventing a 5.

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

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

For an 11-parameter mutation with rich annotations and 100% schema coverage, the description supplies the key scope, safety, and partial-update constraints. It does not describe the return value or error shape, and no output schema exists, leaving 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 coverage is 100%, so the schema already documents all 11 parameters and the baseline is 3. The description adds global parameter behavior not present in the schema: only supplied fields are changed and empty-section updates are refused, which is meaningful for an optional-field update tool. It does not cover the script/scheduled_item matching rules, but those are in schema descriptions.

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

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

The description opens with a specific verb and resource ('Update a thumbnail brief') and defines it as the written plan for a thumbnail. It scopes the operation to the signed-in user's own Bardiyah workspace and names editable areas, making it distinguishable from create/get/list thumbnail-brief 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?

It establishes that this tool is for updating an existing editable thumbnail brief and notes partial-update behavior, giving clear context for when to use it. It does not explicitly name create-thumbnail-brief or get-thumbnail-brief as alternatives, nor state when not to use it, so it falls short of a 5.

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