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

No annotations are provided, so the description carries the full behavioral burden, and it discloses only the role default. It does not say whether attaching is idempotent, whether the same media can be attached twice, what happens to existing sort_order values, or what permissions are required for this mutation.

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

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

Two tight sentences with zero filler, leading with the action and following with the default behavior. Every clause earns its place.

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

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

A mutation tool with no annotations, no output schema, and two undocumented required parameters needs more than two sentences. Nothing covers idempotency, duplicate handling, ordering semantics, or the return value, so an agent cannot reliably predict the effect of a call.

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

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

Schema coverage is only 25% (just the role field), so the description must compensate; it does explain role and its 'gallery' default and mentions sort_order. However, the two required UUID parameters (item_id, media_id) are entirely undocumented and the description never explains what sort_order actually orders, leaving a real gap.

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

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

Clear verb+resource: 'Attach an existing media row to a gallery item', naming both the media-side and gallery-side entities. It implicitly distinguishes itself from detach_gallery_media and set_gallery_cover via the 'attach' verb and generic role handling, though it never states the distinction 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as set_gallery_cover (which sets the cover role) or how this relates to list_gallery_media/detach_gallery_media. Usage is only inferable from the verb.

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

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

With no annotations, the description carries the full burden and does well: it discloses the always-draft status, that agents cannot publish, that Studio review is required, and that a specific CLI performs the conversion. It omits auth/permission needs and what happens on a duplicate slug or conversion failure, but the critical behavioral constraint is surfaced.

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 tightly written sentences with the primary action front-loaded and the draft constraint immediately after. No filler; each sentence contributes a distinct fact.

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

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

For a 12-parameter mutation tool with no annotations and no output schema, the description covers the essential behavioral constraint and the conversion mechanism. The notable gap is that it never says what is returned (e.g. the new post id), which matters more given the absence of an output schema.

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

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

Schema description coverage is 100%, so all 12 parameters are already documented in the schema. The description only restates two of them (markdown_body conversion, category_slug linking), adding no syntax, format, or default details beyond what the schema provides. 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 chain (convert Markdown → PlateJS JSON) and a specific resource (draft blog post), which cleanly distinguishes it from update_blog_post and create_content. An agent can tell what this does without opening the schema.

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

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

Clearly conveys the usage context: use it to insert a Markdown body as a draft, with category linking by slug. The draft-only constraint is spelled out, but it never names a sibling (e.g. update_blog_post for edits, create_content for non-blog content) to route the agent between alternatives.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that slide ids are auto-generated and must not be supplied, but says nothing about permissions, whether creation is reversible, or what the call returns. Partial disclosure only.

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

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

Three compact sentences, front-loaded with the core action, then the required slide contract, then the structural convention. No filler and every sentence carries information an agent needs.

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

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

For a creation tool with no output schema and no annotations, the description omits what is returned (e.g. the new carousel id) and any cross-tool linking guidance, even though create_variant/format=carousel and variant_id are relevant. The slide contract is covered, but the post-call picture is not.

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 value beyond the schema by enumerating the required per-slide fields (templateId, category, label, content) and warning that ids are auto-generated. It does not clarify caption or variant_id semantics, but the added slide-shape guidance is meaningful.

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 (Create) and resource (carousel) and immediately scopes it with 'with the given slides,' which cleanly separates it from get_carousel, update_carousel, and list_carousels. An agent knows exactly what the tool produces without opening the schema.

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

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

It offers structural guidance ('1 cover slide + several body slides + 1 cta slide') that implies how a carousel is typically composed, but never says when to choose this over siblings like create_content or create_variant. No alternatives or preconditions are named, leaving usage 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?

With no annotations, the description carries the full burden, and it does disclose one important trait: status is always forced to 'draft'. However it says nothing about what happens on a duplicate slug despite declaring uniqueness, whether the operation is idempotent, or what identifier is returned for chaining to create_variant.

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

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

Three compact sentences, front-loaded with the pipeline step and the core action, followed by the exclusion and the next step. No filler or redundancy.

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

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

Covers purpose, alternative routing, forced draft status, and pipeline sequencing for a 12-parameter creation tool. The remaining gap is the return value (the new content ID needed to call create_variant) and slug-collision behavior, which matter more here since there is 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% across all 12 properties, so the schema already documents every parameter. The description adds no syntax, format, or constraint detail beyond what the schema fields provide, which is the baseline 3 case.

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 master content item') and immediately scopes it ('directly, without an Idea'), which separates it from the sibling promote_idea. An agent can distinguish this from create_idea, promote_idea, and create_variant without opening any schema.

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

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

Explicitly names the alternative tool (promote_idea) and the condition that selects it (content came from an idea, keeps provenance). It also places the tool in the pipeline and names the next step (create_variant, step 4), leaving nothing to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden for a 15-parameter mutation tool. The defaults it cites (status=draft, visibility=public) and the kinds[0]-is-primary rule are already stated verbatim in the schema property descriptions, so the sentence adds no new disclosure. Nothing is said about permission requirements, duplicate-slug handling, side effects, or what is returned.

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 the key array semantic, then the defaults, then the follow-up pointer. No filler, no restating of the tool name beyond the opening clause.

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

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

For a 15-parameter creation tool with no annotations, no output schema, and less than half of the parameters documented in the schema, the description is underspecified: it omits most optional fields, error/duplicate behavior, and any mention of what a successful call produces. The one workflow pointer it offers does not close the gap.

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

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

Schema description coverage is only 47%, so the description would need to compensate for the many undocumented optional fields (author, summary, subtitle, source_id, published_at, source_table, duration_minutes), and it does not. The two facts it does give — ordering of kinds and the status/visibility defaults — duplicate what the schema already says 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?

The description states a specific verb and resource ("Create a Gallery item") and clarifies the core payload semantic that kinds is an ordered array with kinds[0] as primary. It does not explicitly differentiate itself from siblings like update_gallery_item or delete_gallery_item, though the create verb makes the intent unambiguous.

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

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

There is one concrete workflow hint — "Use set_gallery_featured afterwards to pin to the landing carousel" — which tells the agent what to do next for a common goal. However, it gives no guidance on when this tool is preferred over alternatives (e.g., update_gallery_item, create_content) or any prerequisites such as slug uniqueness or permissions.

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

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

With no annotations, the description carries the full behavioral burden. It discloses pipeline position, the topic-linking requirement, and the downstream transition, which is useful context. It does not state whether the call is idempotent, what happens on a bad/missing topic_id, what permissions are needed, 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?

Four short sentences, each doing distinct work: pipeline position, trigger, prerequisite, and next step. Front-loaded with the step label and action verb, and no sentence is redundant 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?

There is no output schema, and the description implies an idea identity (id passed to promote_idea) without saying what the call returns. Apart from that, everything an agent needs to invoke a 5-parameter create tool correctly — trigger, prerequisite, and follow-up — is present.

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

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

Schema description coverage is 100%, so every parameter including angle, source, raw_text, topic_id, and target_audience is already documented in the schema with examples and defaults. The description only reiterates the topic_id sourcing hint (list_topics) that the schema already gives, so it adds little beyond the baseline.

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

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

States a specific verb (Register) and resource (a new content idea) and scopes it under a Topic. The "[Pipeline step 2 — Discover]" tag and the next-step pointer to promote_idea distinguish it cleanly from siblings like create_content, list_ideas, and update_idea.

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

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

Gives an explicit trigger ("when the agent discovers a new angle from research, competitor scan, user feedback"), a prerequisite ("list_topics first"), and the follow-up action (promote_idea → draft Content). An agent knows both when to call it and what comes next.

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

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

With no annotations, the description must disclose behavioral traits, but it only implies a write operation. It omits permissions, side effects, idempotency, duplicate handling, and other mutation characteristics.

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 single sentence is front-loaded and free of waste, but it is too sparse to adequately convey the tool's scope, making it under-specified rather than genuinely concise.

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 mutation tool with 10 parameters, no annotations, and no output schema, the description is too minimal. It lacks behavioral details and usage context needed for correct invocation.

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

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

Schema description coverage is 100%, so all 10 parameters are documented in the schema. The description adds no additional meaning beyond the schema, making a baseline 3 appropriate.

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

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

The description states a specific verb ('Register') and resource ('media item') within the CMS, making the tool's purpose clear. However, it does not explicitly differentiate from sibling tools like list_media or probe_media, though no direct creation sibling exists.

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

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

No when-to-use guidance, prerequisites, or alternatives are provided. The description only restates the action, leaving the agent to infer context from the name and 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?

No annotations are provided, so the description carries the full burden. It usefully discloses sequencing (final step, follow-up tools) and the side benefit of variant_id for downstream tracing, but says nothing about whether records are immutable, whether duplicate publishes are allowed, required permissions, or what is returned on success.

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

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

Three dense sentences with the pipeline position front-loaded and no filler; the bracketed label is slightly redundant with the title-less name but still scannable.

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-parameter mutation tool with no annotations and no output schema, the description covers workflow position and follow-up tools but omits the success/return shape, idempotency, and error behavior an agent would want before invoking it.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, including variant_id's 'enables variant-level metric tracking' rationale. The description only adds the Content detail view tracing angle for variant_id, which is marginal beyond the schema baseline.

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

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

States a specific verb and resource ('Record a publication event') and qualifies it with the where/when scope, so the agent knows this is event logging rather than content creation (create_content) or variant creation (create_variant). It does not explicitly name a sibling it should be chosen over, so it falls short of a 5.

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

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

Explicitly places the tool as 'Pipeline step 6' and the 'Final pipeline step', and tells the agent exactly what to do next (get_metrics + get_activity_logs for the feedback loop). That is real routing guidance, though there is no explicit when-not-to-use condition.

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?

No annotations, so the description carries the full burden. It usefully discloses that topics are long-lived, rarely changed, and capped at ~3-5, which shapes agent behavior. However, it says nothing about permissions, duplicate-name handling, or what happens on repeated creation — meaningful gaps for a mutation tool with zero annotation coverage.

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

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

Three short sentences with the pipeline stage front-loaded and every clause carrying information (step, lifetime, frequency cap, usage condition). No filler.

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

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

With a fully documented schema and no output schema needed, the description supplies the pipeline role and usage discipline an agent needs to place this tool correctly. Missing only edge-case behavior (duplicates, permissions) for a mutation 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 all four parameters (name, intent, keywords, description). The description adds no syntax, format, or semantic detail beyond the schema, so the baseline 3 applies.

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

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

Uses a specific verb+resource ('Create a new topic') and situates it as pipeline step 1 (Strategy). The added scope notes (long-lived, 3~5 total, rarely changed) tell the agent this is not a routine creation tool, though it doesn't explicitly distinguish itself from siblings like create_idea or create_content.

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 add when a genuinely new content theme emerges' gives a clear gating condition for use, reinforced by the scarcity note (3~5 total). No explicit alternatives or when-not-to-use routing to sibling tools, but the condition is stated rather than 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?

With no annotations, the description carries the full burden and does add real value: it enumerates the allowed platform and format values (a validation constraint absent from the schema's enums) and tells the agent that variant.id is the handoff artefact. However, it says nothing about required permissions, whether creation fails on duplicate platform+format for the same content, or what the created record contains beyond an id.

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

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

Two dense sentences: the first front-loads the pipeline role and purpose, the second carries the enumerations and the downstream handoff. No filler, no restatement of the name, and every clause is actionable.

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 7-parameter write tool with a nested platform_settings object and no output schema, the definition covers purpose, allowed values and output handoff well, but the nested object is hand-waved ('Postiz DTO pattern') and there is no statement of what the call returns beyond an id hint. Adequate, with a clear gap around the structured settings parameter.

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

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

Schema coverage is 100% so the baseline is 3, but the schema defers enum values to the description ('see description for allowed values') and lists 0 enums — the description is the only place the closed sets for platform and format exist, making it load-bearing rather than redundant. It still leaves platform_settings ('Postiz DTO pattern') and hashtags/body_text usage unexplained.

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

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

States a specific verb and resource ('Create a platform/format-specific variant of a master Content') and scopes it to a pipeline position ('Pipeline step 4 — Adapt'), which cleanly separates it from create_content (the master) and update_variant (modification of an existing variant). An agent can route to it without opening sibling schemas.

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

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

Gives clear context: this is step 4 of a pipeline, its input is a master Content, and its output feeds explicitly named downstream tools (create_blog_post_from_markdown / create_carousel / send_newsletter / link_video_project_to_variant). It stops short of stating when NOT to use it (e.g. variant already exists → update_variant), so it is not a full when/when-not/alternatives treatment.

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

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

With no annotations, the description carries the full behavioral burden, yet says nothing about permissions, whether repeated calls duplicate projects, what 'save' implies for an existing project, or what the call returns. The nested clip structures are never explained either.

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

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

A single short sentence is front-loaded and waste-free, but the 'create or save' hedge introduces ambiguity rather than economy. It is under-specified more than it is concise.

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

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

For a tool with five parameters including nested clip and metadata objects, no annotations and no output schema, one sentence is insufficient. Nothing explains the shape or role of clips/bgmClips/clipMeta or what a successful creation yields.

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 (name, clips, bgmClips, clipMeta, orientation with enum). The description adds no additional meaning, which is the baseline 3 when the schema does the work.

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

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

States a specific verb+resource ('create...a video project') and is distinguishable from list_video_projects and get_video_project. However, the paired verb 'or save' muddies whether this creates a new project or persists an existing one, leaving a small ambiguity.

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

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

No when-to-use guidance, no prerequisites, and no pointer to alternatives such as link_video_project_to_variant or update-style siblings. The agent must infer the workflow context on its own.

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

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

With no annotations, the description carries the full behavioral burden and delivers the critical facts: it is a HARD delete (irreversible), gallery_item_media rows cascade, and underlying media rows and storage files survive because other items may reference them. That is exactly the blast-radius information an agent needs before a destructive call. It omits permission/auth requirements and behavior on a missing or referenced id.

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

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

Three short sentences, front-loaded with the destructive nature, and each sentence carries distinct information (operation, cascade, preserved data). No filler.

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

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

For a one-parameter delete with no annotations and no output schema, the description covers the destructive semantics and side effects that matter most. It stops short of stating authorization needs, error behavior for an unknown id, and whether a response is returned, which leaves minor gaps.

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

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

Schema coverage is 0% and the description never mentions the single 'id' parameter. The parameter is a required uuid named self-evidently, so there is little hidden meaning to add, but the description provides no clarification of which id is expected. Baseline 3 is appropriate for a trivially-named single parameter.

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

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

States a specific verb and resource ('Hard-delete a Gallery item') and the 'Hard-delete' qualifier immediately distinguishes it from soft-delete or detach-style siblings such as detach_gallery_media and update_gallery_item. An agent can tell what this does without opening the schema.

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

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

Usage is implied by the name and the destructive wording, but there is no explicit statement of when to use this versus update_gallery_item, detach_gallery_media, or a media-level delete. No prerequisites, no alternatives, no when-not 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?

With no annotations, the description carries the full burden, and it does disclose a key trait: the underlying media row is preserved, so this is a link-only removal rather than a data deletion. It omits auth requirements, idempotency, and error behavior.

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

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

Two tight sentences, front-loaded with the action and immediately followed by the preservation guarantee. No wasted words.

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

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

For a simple one-parameter detach tool with no output schema, the description covers the essentials of what it does and what survives. It lacks routing guidance versus sibling tools and any failure/idempotency context.

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

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

Schema description coverage is 0% for the single link_id parameter, but the description's phrasing ('gallery_item_media link') gives context that link_id identifies a join between a gallery item and media. It adds modest meaning without clarifying format or sourcing.

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 ('Remove') and resource ('gallery_item_media link'), which is clearly the inverse of the sibling attach_gallery_media. The scope is unambiguous, though it doesn't explicitly name the sibling it complements.

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

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

No when-to-use guidance, prerequisites, or differentiation from related siblings like delete_gallery_item or attach_gallery_media. The agent must infer the use case from the verb alone.

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

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

No annotations are provided, so the description carries the full behavioral burden and falls short: it never says whether this is a synchronous analysis or an async job (notable given get_render_status exists for a sibling), how expensive it is, or what it returns. Only the general purpose is 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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though the brevity reflects under-specification rather than maximal usefulness.

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 annotations and no output schema, the description must carry the load but doesn't: an agent cannot tell whether beats come back as timestamps or a file, whether the call is blocking, or whether the result feeds render_video directly. For a 3-parameter analysis tool this is thin.

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

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

Schema description coverage is 100% with all three parameters documented inline, including the mode enum and minGap units, so the baseline is 3. The description adds no meaning beyond the schema — it does not explain how 'impact' vs 'downbeat' affects results or how minGap interacts with mode.

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 (extract), resource (beats), and source (music file), plus the downstream purpose (syncing video cuts). No sibling tool performs beat analysis, so the operation is trivially distinguishable, though the description never explicitly names what it is not.

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 'for syncing video cuts' implies the workflow context (pairing with render_video), which is useful, but there is no explicit when-to-use, no prerequisites, and no guidance on which detection mode to pick or when to skip this tool.

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?

No annotations are provided, so the description must carry the full behavioral burden. It says 'List' (implying read-only), but does not disclose pagination behavior, default ordering, whether it returns all logs or is capped, or what the actor_type filter semantically means. For a tool with zero annotation coverage, this is a notable 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?

A single efficient sentence that front-loads the 'List activity logs' purpose and then enumerates filters compactly. No waste, though it could potentially include a default sort order or usage hint without fluff.

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

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

Given 4 optional params, 100% schema coverage, no output schema, and no annotations, the description is adequate but thin. It doesn't clarify return shape, pagination, or default ordering, which an agent would need to call this correctly against a likely long log stream.

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

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

Schema coverage is 100%, so both the schema and its embedded descriptions already document all four parameters with enums, limits, and defaults. The description merely names the same four filters without adding syntax, semantics, or examples. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a clear verb+resource: 'List activity logs'. It's not tautological and stands apart from siblings like list_contents or get_metrics. However, it doesn't differentiate itself from any specific sibling — there are no other activity-log tools, so the differentiation burden is light, but it also offers no explicit distinction.

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

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

There's no guidance on when to use this tool versus alternatives, and no exclusions or prerequisites mentioned. An agent knows it lists logs but has no context for when this is the right call versus, say, get_metrics or list_contents. No 'when not to use' guidance is provided.

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?

No annotations are provided, so the description carries the behavioral burden. It usefully discloses that the response includes full PlateJS content (not just metadata), but says nothing about behavior when the ID/slug is missing, whether drafts are returned, or auth requirements.

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 that front-loads the verb and resource, then adds the one detail (full content) most likely to affect tool choice. Nothing is wasted.

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

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

With no output schema and no annotations, the description is adequate for a simple getter and correctly flags the full-content payload. It still omits the most relevant behavioral detail for a by-ID getter: what happens on a not-found or invalid slug.

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

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

Schema description coverage is 100% for the single parameter, so the schema already documents 'Blog post UUID or slug'. The phrase 'by ID or slug' in the description simply mirrors that and adds no new syntax or format guidance. Baseline 3 applies.

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

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

The description names a specific verb and resource ('Get a single blog post') and pins down the retrieval key ('by ID or slug'), which implicitly separates it from list_blog_posts and update_blog_post. It stops short of explicitly naming those siblings as alternatives, 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?

There is no statement of when to use this tool versus list_blog_posts or update_blog_post, and no prerequisites or exclusions are given. The read semantics are inferable from 'Get', which is only implied 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?

No annotations are provided, so the description carries the full burden. It reveals that full slide data is included, which is useful, but says nothing about read-only nature, error behavior for missing ids, or pagination/size concerns. For a read tool without annotations this is thin.

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

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

A single tight sentence with the resource and the scoping qualifier front-loaded. No waste.

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?

Adequate for a simple by-id read tool with one fully-documented parameter. Missing is any indication of what the return looks like at a high level (beyond 'full slide data') or error semantics, but there is no output schema and the surface area is small.

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 fully documented in the schema with an example format. The description adds no additional 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 (Get) and resource (carousel) with scope qualifier (single, by id). Distinguishable from siblings like list_carousels and update_carousel by the 'single by id' framing, though it never explicitly names 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?

Implicit guidance: 'by id' and 'single' signal this is the retrieval tool versus list_carousels. However, no explicit when-to-use vs when-not, no mention of alternatives, and no 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?

No annotations are provided, so the description carries the burden. It discloses the useful payload fields (body/hook/cta) and that it is a read, but says nothing about behavior when the id/slug is not found, permission requirements, or whether the read is cached. Adequate but incomplete for a no-annotation tool.

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

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

Two tight sentences with the pipeline-step context front-loaded and no filler. Every clause carries information an agent can act on.

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 purpose, invocation, and the fields of interest, which is nearly enough. The only gap is the not-found / error behavior, which is a minor omission for this tool class.

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

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

Schema coverage is 100% with a single required parameter already documented as 'Content ID (UUID) or slug'. The description's 'by id or slug' merely repeats the schema, adding no format or resolution-order detail. 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 (Get) and resource (a single master content item) plus the lookup key (id or slug). The word 'master' and 'single' distinguish it from list_contents and from variant-level getters in the sibling set.

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 names the condition and the alternatives: 'Use before update_content or create_variant to read the current body/hook/cta.' An agent knows both when to reach for it and which sibling calls it feeds into.

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 are not provided, so the description carries full behavioral disclosure. It does not indicate whether the operation is read-only (implied by 'Get' but not stated), whether authentication is required, what happens if no feedback exists, or how the feedback is structured. For a read operation, missing these details is a significant 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?

A single sentence is appropriately sized and front-loaded with the main action. However, it is too short to add much value, and the lack of structure beyond a basic statement limits its usefulness.

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 annotations, no output schema, and a terse description, the definition is incomplete. It does not explain what 'human feedback' entails, how it differs from system revisions, or what the agent should expect in return. Given the complexity of feedback retrieval, the description should provide more context to be adequate.

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% (the only parameter `content_id` is fully documented), so the baseline is 3. The description adds no additional meaning beyond 'for a content item', which essentially repeats the schema.

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

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

The description states a specific verb ('Get') and resource ('human-authored revision feedback for a content item'), but the purpose is somewhat vague. It is not immediately clear whether this returns a feedback object, a list of comments, or something else. Compared to siblings like `get_revisions` (likely system-generated revisions), the differentiation is weak. However, the core action is understandable.

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

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

No guidance on when to use this tool versus alternatives such as `get_revisions` or `get_content`. There is no mention of prerequisites or typical workflow context. An agent would have to infer that 'human feedback' is distinct from general revision history, but nothing confirms this.

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?

No annotations are provided, so the description carries the burden. 'Get' clearly implies a read-only, non-destructive operation, but the description says nothing about behavior on a missing/invalid id, permissions, or what an 'idea' contains. Adequate but not rich.

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 pipeline stage and the core action, with the usage hint trailing. No wasted words, though the bracketed stage tag is slightly decorative.

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 tool with no output schema, this covers the essentials. It omits any note on error handling or return content, but annotations and schema richness are minimal, so the gap is small.

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

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

Schema coverage is 100% with a single required 'id' parameter already documented as 'Idea UUID' with format uuid. The description only restates 'by id', adding no new syntax or format guidance, so the baseline 3 applies.

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

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

States a specific verb+resource ('Get a single idea by id'), which clearly distinguishes it from list_ideas and the mutating siblings update_idea/promote_idea. The pipeline-step label adds workflow context but not further disambiguation.

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

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

Gives a concrete scenario: use it when promote_idea or update_idea needs full context first. This routes the agent to the tool at the right moment, though it doesn't state when NOT to use it or exclusivity conditions.

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

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

No annotations are provided, so the description carries the full disclosure burden. It usefully scopes the output ('all publish events across channels'), but says nothing about auth requirements, result format, or whether the data is real-time or delayed beyond what the schema states.

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

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

Two tight sentences with the purpose front-loaded ahead of the usage guidance, and the '[Feedback loop]' tag signals its role. No wasted wording, though the bracketed label is slightly informal.

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 no output schema, the description covers purpose, scope, and workflow context. Return-value detail is only described at a high level, but that is largely sufficient here.

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

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

Schema coverage is 100% for the single content_id parameter, so the schema already documents it. The description adds no format or constraint detail beyond what the schema provides; 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: 'Get publication metrics for a content item', with scope clarified as 'all publish events across channels'. An agent can distinguish it from get_human_feedback or get_activity_logs, though no sibling 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?

Explicit when-to-use: 'Use to learn which variants performed best before creating the next round of variants', which ties it to the sibling workflow (create_variant). It gives clear context but names no alternative or exclusion.

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?

No annotations are provided, so the description carries the full burden. It omits what the status values are, whether it polls a queue, whether it needs a job identifier, and whether it's side-effect free. For a status-check tool with zero annotations that is a real 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?

One short, front-loaded sentence with no filler. Appropriately sized for a zero-param status 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?

Simple tool with an empty schema and no output schema, so the description needn't explain parameters or returns. But lacking annotations, it should at least hint at what is being reported on and any prerequisite, which it doesn't.

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?

Parameter count is 0, so baseline 4 applies. The description adds nothing param-related, but there is nothing to document.

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 ('Check') and resource ('rendering status'), so the purpose is clear. It doesn't differentiate from sibling 'render_video' (the trigger) or explain whether it reports on a specific render job, which leaves minor ambiguity.

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

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

No guidance on when to call this versus waiting on 'render_video' or other status sources. With 50+ siblings, the agent gets no routing signal.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Get' implies a safe read, but nothing is said about ordering (newest first?), pagination, history depth limits, or whether revisions are immutable snapshots. For a no-annotation tool this is a notable 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?

A single front-loaded sentence with zero filler. It is efficient, though its brevity comes at the cost of useful content rather than from trimming redundancy.

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

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

With no annotations and no output schema, the description should hint at what a revision record contains (author, timestamp, version id) or how the list is scoped/ordered. As written, an agent cannot anticipate the response shape or size.

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 there is only one parameter, fully documented in the schema. The description adds no format or semantic detail beyond it, 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 ('Get') and resource ('revision history for a content item'), so the operation is unambiguous. It does not differentiate from the sibling 'revert_to_revision', which operates on the same resource, so it falls short of a 5.

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

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

No guidance on when to use this versus alternatives such as revert_to_revision, and no prerequisites or context stated. The agent must infer the use case entirely from the name.

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

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

With no annotations provided, the description carries the full behavioral burden. It says nothing about read-only nature, side effects, authentication, rate limits, or response format. Even for a simple read, it omits basic safety context an agent would need.

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 extraneous words. It is appropriately sized, though 'specific' is slightly redundant with 'a video project'.

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 read tool with one fully documented parameter and no output schema, the description is minimally adequate. However, the absence of any behavioral details (e.g., read-only status) leaves a small gap that a complete definition should fill.

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 fully documented in the schema as 'Project ID'. The description adds no additional meaning, so the baseline of 3 applies.

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

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

The description states a clear verb ('Get') and resource ('details of a specific video project'), making the tool's purpose immediately understandable. It implicitly distinguishes from sibling list_video_projects by saying 'specific', but does not explicitly name alternatives or differentiate further.

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

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

There is no guidance on when to use this tool versus alternatives like list_video_projects, nor any prerequisites or conditions. The description only implies usage by the presence of the required ID parameter.

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?

No annotations provided, so the description must carry the behavioral burden. It discloses the 1:1 constraint and the unlink behavior, which is important. However, it doesn't state whether this is idempotent, what happens if the variant is already linked to another video_project, or the return shape. Some but not full disclosure.

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

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

Two compact sentences front-load the action and constraint, then explain the rationale and unlink option. No wasted words, though the brxce-editor detail is niche but relevant.

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

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

For a 2-param mutation tool with no output schema and full schema coverage, the description covers the special creation workflow and unlink semantics. Missing explicit collision handling (e.g., existing 1:1 link) 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 schema already documents both parameters including the null-to-unlink semantics. The description reinforces but does not add syntax or format details beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (link/unlink), specific resources (video_project to variant), and the cardinality (1:1). Clearly distinguishes itself from siblings like create_video_project and update_variant by explaining it fills a FK gap.

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

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

Explains the exact scenario it exists for: video_projects created via brxce-editor API lack variant_id, so this tool fills the FK. Also explicitly states how to unlink. No explicit exclusions or alternatives, but the context is clear enough.

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?

No annotations are provided, so the description carries the full burden, but for a trivial no-argument list operation the burden is low. It discloses the shape of the return (name, slug, description), which is the useful behavioral detail; it does not discuss pagination, auth, or whether the list is filtered or complete.

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

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

Two short clauses, front-loaded with the resource and followed by the action-relevant guidance. Every word earns its place with no redundancy 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?

With no output schema, the description compensates by listing the returned fields, and with zero params there is no schema gap to fill. It is essentially complete for this simple lookup tool, missing only minor operational context such as ordering or pagination behavior.

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

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

The tool takes zero parameters, so there is nothing to document beyond what the empty schema already conveys; the baseline of 4 applies. The description correctly describes the returned field set instead of inventing parameter semantics.

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

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

States a specific verb and resource ('List all blog post categories') and enumerates the returned fields (name, slug, description). It is clearly distinguishable from siblings like list_blog_posts or get_blog_post without opening any schema.

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

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

Explicitly states when to use it: 'to find the correct category slug before creating a post,' which correctly routes the agent to precede create_blog_post_from_markdown. It stops short of naming sibling alternatives or exclusion conditions, so it is clear context rather than full when/when-not guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that results are summary fields and not full PlateJS content, but says nothing about pagination behavior, ordering, or how the default limit of 50 truncates results. Useful but incomplete for a tool with zero annotation coverage.

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

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

Two short sentences, front-loaded with purpose and followed by the one non-obvious fact an agent needs (summary fields, not full content). Nothing is wasted and nothing is buried.

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

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

With no annotations and no output schema, the description should more fully explain what is returned and how results are bounded. It covers the summary-vs-content distinction well but omits ordering, pagination, and the practical consequence of the limit cap, leaving the definition 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%, so all three parameters (limit, status, category_slug) are already documented in the schema, including the default and the category_slug example. The description adds only the generic phrase "optional filters" and no new meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ("List blog posts") plus scope ("with optional filters"), which lets an agent distinguish it from the singular get_blog_post and from list_blog_categories. It does not, however, explicitly name or contrast with any sibling tool, 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?

The listing intent and the availability of filters imply the use case, but the description gives no explicit when-to-use guidance, no exclusions, and never points to get_blog_post for full content or to the create/update siblings. Usage is inferable from the name rather than stated.

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

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

No annotations are provided, so the description carries the full burden. It discloses the return payload shape (id, title, caption, slide_count, timestamps), which is genuinely useful, but says nothing about read-only nature, auth needs, or pagination behavior — though 'List' plus the pagination params imply a safe read.

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

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

Three short sentences, zero filler, with the core action front-loaded and the routing hint last. Every sentence earns its place.

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

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

With no output schema, the description usefully enumerates the returned summary fields and points to the sibling for deeper data, covering what an agent needs to call and interpret it. Minor gaps: no pagination guidance beyond the schema and no mention that results may be truncated.

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

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

Schema description coverage is 100% for both limit and offset, so the schema already documents them fully (defaults, bounds). The description adds nothing about parameter behavior; baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource ('List carousels') and immediately differentiates scope from the sibling get_carousel ('Use get_carousel for full slide data'). The only shortfall is that it doesn't state scope/filtering constraints, but the core purpose is unambiguous.

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

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

Explicitly names the alternative (get_carousel) and the condition that selects it (need full slide data), which is real routing guidance. It stops short of stating when-not to use list_carousels or how it relates to other content-listing siblings, so no exclusions 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?

No annotations are provided, so the description must carry the full behavioral burden. It implies a read/filter operation but never states that it is non-mutating, what it returns, or how pagination/default limit behaves, leaving key behavior to inference.

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

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

Two short sentences with the pipeline position front-loaded and no filler. Minor redundancy between the bracket tag and "master content items" keeps it from 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?

A read/list tool with 5 optional params and no output schema or annotations; the description covers intent and workflow but not return shape or pagination behavior. Adequate against full schema coverage, but not richly 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%, so all five parameters are already documented. The description only gestures at filtering ("Use filters") without adding format or semantics, so the 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+resource ("List master content items") and situates it in a pipeline step, which helps separate it from sibling listers like list_ideas and list_blog_posts. It never names an alternative explicitly, so differentiation is implied 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 clear workflow context — "typically reach this after promote_idea (step 2→3)" — and a positive trigger ("find drafts pending derivation"). It does not say when-not to use it or contrast with the many other list_* 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?

With no annotations, the description carries the full burden. It usefully discloses sort order (featured first, featured_rank asc, then published_at desc) and the OR-match semantics of kinds, which are genuine behavioral facts. However it says nothing about pagination behavior, result shape, or permission/visibility requirements for reading internal items.

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: resource, then filters, then ordering semantics. Front-loaded and zero 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 six-parameter, no-annotation, no-output-schema list tool, the description covers filtering and ordering but omits the returned item shape, pagination/default behavior confirmation, and access constraints. 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 description coverage is 100% and each of the six parameters is documented inline, so the baseline is 3. The description's restatement of the kinds OR-match rule duplicates the schema's own text 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 ("List AWC Gallery items") and enumerates the filterable dimensions. It does not differentiate itself from the nearby sibling list_gallery_media, nor explain the relationship between 'items' and 'media', so an agent must infer the distinction.

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

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

Filterable facets (status/kinds/featured/visibility) imply the listing use case, but there is no explicit when-to-use guidance, no mention of when to prefer list_gallery_media or a single-item getter, 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?

No annotations are provided, so the description carries the full burden. It usefully discloses the ordering guarantee ('ordered by sort_order asc') and implies a read-only listing, but says nothing about permissions, pagination, or behavior when an item has no media attached.

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

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

A single front-loaded sentence with no filler; the resource and ordering are stated up front. It earns its space, though the jargon 'gallery_item_media rows' leans on internal naming rather than user-facing language.

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 1-param read tool with no output schema, the definition is minimally sufficient, but the crowded sibling set (attach/detach_gallery_media, list_media, list_gallery_items) makes the missing disambiguation a real gap for correct tool selection.

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

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

Schema description coverage is 0% for the single item_id parameter, so the description must compensate. It clarifies that the identifier refers to a gallery item being listed for, which is meaningful, but never states the expected format (UUID) or whether it is a gallery_item id or some other entity id.

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

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

States a specific verb (List) and resource (gallery_item_media rows) scoped to 'an item', which is more precise than the ambiguous sibling names like list_media. It doesn't explicitly differentiate itself from list_media or list_gallery_items, 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?

There is no when-to-use or when-not-to-use guidance, and no alternative is named. With siblings such as list_media, list_gallery_items, and attach_gallery_media in the toolset, an agent gets no help deciding which to call; usage is only loosely implied by the phrase 'for an item'.

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?

No annotations are provided, so the description carries the burden. It implies a safe read operation and mentions the filter semantics, but says nothing about permissions, pagination behavior beyond the limit param, result ordering, or what an empty result means. Adequate but with clear gaps.

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

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

Front-loads the action and the 'use this first' guidance, and the filter and next-step sentences are short and purposeful. Slightly dense with three separate clauses but no waste.

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

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

For a zero-required-param list tool with full schema coverage and no output schema, the description covers purpose, filter usage, and follow-on routing. It lacks only a note about return shape/ordering, which is minor here.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description restates topic_id and promoted semantics rather than adding syntax or format detail beyond the schema; baseline 3 applies.

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

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

States a specific verb+resource ('List content ideas') plus the pipeline stage and available filters. It clearly distinguishes itself from siblings create_idea, promote_idea, and get_idea by scope (list vs. single vs. create).

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

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

Explicitly tells the agent to use it 'first to see what ideas already exist before creating new ones' and names alternatives (create_idea, promote_idea) as typical next steps. There is no explicit 'when not to use' statement, which keeps it short of a 5.

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

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

No annotations, so the description carries the full burden. It states ordering but omits safety profile, pagination behavior, and return shape – far below what an unannotated read tool needs.

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

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

One short sentence, front-loaded with the verb and resource and an added ordering detail. Efficient, though arguably thin rather than concise given the information it omits.

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 unannotated, no-output-schema listing tool, the description says almost nothing beyond ordering. It lacks return format, pagination, and usage context that an agent would need to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already fully documents the single limit parameter (default 50, max 100). The description adds nothing to parameter semantics; 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 (list) and resource (media items), and adds ordering. It is distinguishable from siblings like list_gallery_media by the generic 'media' resource, though no explicit sibling differentiation is given.

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

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

No guidance on when to use this tool versus alternatives such as list_gallery_media, probe_media, or create_media. The ordering note is a behavioral trait, not usage 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?

No annotations are provided, so the description carries the full burden. It discloses that this is a read/listing operation and what each returned channel contains, which is useful. It omits auth requirements (a Postiz connection must exist) and does not say what an empty result looks like, but for a zero-parameter read-only list the risk surface is small.

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

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

Two sentences with zero waste; the purpose and the return shape come first, and the usage instruction follows. The pipeline tag is compact and informative rather than filler.

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

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

There is no output schema, so the description's mention of returned fields (id, platform, display name) is the only source of return-value information, and it provides it. Minor gaps remain around error/empty states and authentication prerequisites, but nothing an agent needs to invoke the tool correctly is missing.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description adds no parameter detail, nor does it need to, since the input schema is empty and fully covered.

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

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

Specific verb (List) plus resource (connected social integrations in Postiz), and it goes further to state the return shape (id + platform + display name per channel). It also positions itself in the pipeline ('[Pipeline step 6 — Publish]'), so an agent can distinguish it from the read/write siblings without opening schemas.

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

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

Explicitly states when to use it: 'Use this first to get the integration_id before calling send_to_postiz.' This names the sibling it feeds and the ordering constraint, which is exactly the routing information an agent needs.

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?

No annotations are provided, so the description carries the full burden. 'List all' implies a non-mutating read and the description adds useful workflow context, but it says nothing about ordering, pagination, empty-result behavior, or auth requirements. Adequate but with clear gaps for a tool whose safety profile is undeclared.

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 zero waste; the pipeline position is front-loaded and the follow-on step is stated last, matching the order an agent would reason in.

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

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

For a zero-parameter read tool with no output schema, the description covers purpose and workflow routing well. Its one gap is that it never says what a topic record contains (e.g. the identifier the agent will need to pass to create_idea), which the absent output schema leaves undocumented.

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

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

The tool takes zero parameters, so there is no parameter semantics to convey and the baseline is 4. The description correctly adds no redundant parameter chatter.

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 all topics') and immediately defines the domain concept ('long-lived content themes'), so the agent knows exactly what is returned. The pipeline framing ('step 1 — Strategy') further distinguishes it from the sibling list_* and create_topic tools.

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 invocation context ('Start here: the agent picks which topic an idea belongs to') and routes forward to the next step, create_idea (step 2). It lacks any when-not or fallback guidance, so it falls short of the 5 tier.

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?

No annotations are provided, so the description carries the burden; it does imply a read of child records under a master, which is useful, but says nothing about pagination, result limits, ordering, or permissions. The pipeline-step label adds workflow context but not behavioral detail.

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

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

Two short sentences with no filler; purpose and the dedup instruction are both front-loaded. The leading bracketed pipeline label is slightly noisy but still informative.

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

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

For a one-parameter read-only listing tool with no output schema, purpose and usage are adequately covered. Return shape and pagination remain unspecified, which is the only real gap.

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

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

Schema description coverage is 100% and the single parameter content_id is fully documented in the schema, so the baseline is 3. The description does not add format, scope, or edge-case meaning beyond it.

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

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

States a specific verb ('List') and resource ('variants derived from a master Content'), and relates itself to the sibling create_variant, so an agent can tell what it returns versus what its siblings do.

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?

'Check here before create_variant to avoid duplicates' gives an explicit usage trigger and names the alternative. It lacks a when-not clause (e.g., use list_contents for masters), but the routing intent is clear.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state that this is a read-only operation, how results are paginated or ordered, or what a returned project contains, leaving key behavioral traits undisclosed.

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

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

A single short sentence that is front-loaded with the action and resource. It is efficient, though it errs toward under-specification rather than being verbose.

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 annotations and no output schema, the description should explain the read-only nature, pagination behavior, and what a 'video project' is. It provides none of this, leaving an agent with only the title-level claim.

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 limit and offset documented in the schema itself. The description adds no parameter meaning beyond that, 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 video projects), which is clearer than a tautology. However, 'from the editor' is vague and the description does not distinguish this tool from siblings like get_video_project or create_video_project.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as get_video_project for fetching a single project. The agent must infer usage entirely from the name.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing. It does not say whether results are paginated, whether 'available' implies filtering by processing state, or what fields come back; a read-only list is low risk, but the disclosure gap is still substantial.

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

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

A single short sentence with the resource front-loaded and no filler. It is appropriately sized for the tool's simplicity, though it is too terse to be considered exemplary.

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 zero parameters and no output schema, the structural surface is minimal, so the description does not need to explain arguments or return shape. It is adequate but not complete, since it omits any scoping, filtering, or sibling-routing context that would matter in this crowded toolset.

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

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

The tool takes zero parameters, so there is no parameter semantics for the description to add. Baseline of 4 applies; no compensating detail is required or expected.

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 clear verb (List) and resource (available video source files), so an agent immediately knows this enumerates video assets. It does not, however, distinguish itself from close siblings such as list_video_projects or list_media, leaving the routing decision to 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. With several sibling list tools (list_video_projects, list_media, list_gallery_media) in the same namespace, the description offers nothing to help an agent choose this 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?

With no annotations provided, the description carries the full behavioral burden. 'Get' implies a read-only inspection, but it omits any disclosure of error behavior for missing/unsupported files, whether the file is fetched or must be local, or latency/cost of probing.

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 compact sentence with the returned fields front-loaded in parentheses. It wastes nothing, though it is so terse that it sacrifices some needed context.

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

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

For a simple one-parameter read tool with no output schema, the description usefully lists the metadata returned (duration, resolution, codec), partially compensating for the absent output schema. Missing usage/prerequisite detail keeps it from being fully complete.

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

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

The single parameter is fully documented in the schema ('Filename to probe', 100% coverage), and the description adds no syntax, path-format, or identifier details beyond it. Baseline 3 is appropriate when the schema does all the work.

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

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

States a specific verb (Get/probe) and resource (metadata for a media file), and enumerates the concrete fields returned (duration, resolution, codec). It clearly differs from list_media/create_media, but it never explicitly names or contrasts any sibling tool, so differentiation must be inferred.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g. the file must already exist or be a supported format), and no alternatives named. An agent must guess when probing is appropriate versus other media 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?

With no annotations at all, the description carries the full burden and does well: it discloses the always-draft status constraint ('agents cannot publish directly') and the side effect of linking the original idea via ideas.promoted_to. It omits what happens if the idea was already promoted, whether the idea is consumed/archived, or what identifier is returned.

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

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

Three dense sentences, zero filler, with the identity and the draft-only constraint front-loaded before the forward workflow pointers. Every sentence earns its place.

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

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

Covers a mutation tool's lifecycle well: what it creates, the status it lands in, the link it establishes, and where it sits in the pipeline. With no output schema and no annotations, it could still say what is returned (e.g., the new content ID) so an agent can chain update_content, but overall this is close to complete.

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

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

Schema description coverage is 100% across all 11 parameters, so the schema already documents hook, cta, core_message, funnel_stage, etc. The description adds no syntax, format, or constraint details beyond the schema baseline, so a 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 — 'Promote an idea to a draft Content item' — and places it in a named pipeline step (2→3, Discover → Create). An agent can distinguish this from the sibling create_content and create_idea without opening any schema.

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

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

Explicitly gives the workflow context ('Pipeline step 2→3') and names the follow-on tools in order: update_content then create_variant (step 4). This is actionable routing guidance rather than passive description.

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

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

With no annotations, the description carries the entire behavioral burden and falls well short. 'Start' hints at an async/long-running operation, but it never says whether a job ID is returned, whether the project must be persisted first, whether prior render output is overwritten, or what permissions/limits apply.

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

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

One short, front-loaded sentence with no filler. It is efficient, though the extreme brevity borders on under-specification for an action 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 an action tool with no annotations, no output schema, and an opaque nested object parameter, the description is far too thin. An agent cannot tell what the call returns, how to supply project data, or how progress is tracked.

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 there is a single parameter, so the baseline is 3. The description adds nothing beyond the schema text 'Project data to render', which is especially weak because 'project' is an opaque nested object with additionalProperties {} and no documented shape.

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 clear verb+resource ('start rendering a video project'), which is enough to separate it from a plain status reader like get_render_status. It does not, however, explicitly name or contrast itself with that sibling, 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?

There is no guidance on when to use this tool versus alternatives (e.g., get_render_status for checking progress, create_video_project for setup). Usage is only implied by the word 'render'. No preconditions or 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?

With no annotations, the description carries the full burden and does disclose useful behavior: a NEW revision is created (so history is preserved, not overwritten) and the revert is logged. However, it omits permission requirements, reversibility of the revert, and side effects on related content.

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

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

Two tight sentences, front-loaded with the core action, and the second sentence adds genuine behavioral value rather than filler. No wasted words.

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

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

For a two-parameter tool with full schema coverage, no output schema, and no annotations, the description is largely sufficient and even explains the side effect (new revision created). It could have noted the need for a valid existing revision or where revision_id originates.

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

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

Schema coverage is 100% and both required params (content_id, revision_id) are documented in the schema, so the description is not expected to add much. It adds no syntax or sourcing detail (e.g., where revision_id comes from) 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 (revert) and resource (content item to a specific revision), which is more precise than the bare name. It does not explicitly differentiate from siblings like get_revisions or update_content, but the operation is unambiguous.

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

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

The description implies usage (revert to a target revision) but never states when to prefer this over get_revisions (to find a revision) or update_content (to edit manually). No prerequisites or alternatives are given, leaving the agent to infer the workflow.

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

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

With no annotations, the description carries the burden and does well: it discloses the required dashboard runtime dependency, the side effect of recording variant linkage that surfaces on the Content detail page, and the existence of a duplicate-send check (echoed by the force param). It does not state that a real send to subscribers is effectively irreversible/outward-facing, which is the main missing trait.

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 action, followed by the optional linking effect and prerequisites. No filler, though the middle sentence is somewhat verbose for the value it adds.

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-param, no-annotation, no-output-schema tool, the description covers the action, the runtime prerequisite, the side effect, and the duplicate-check escape hatch. Return values and failure modes are not addressed, but schema documentation is complete enough that little is missing.

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

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

Schema description coverage is 100%, so all four parameters (post_id, variant_id, preview, force) are already documented in the schema, including defaults like auto-resolving variant_id. The description only restates the variant-linking behavior, adding little beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb (send) and resource (a blog post as a newsletter to subscribers) and adds mechanism (via the dashboard send pipeline), so an agent knows exactly what it does. It does not explicitly differentiate itself from send-adjacent siblings like send_to_postiz, which keeps it just short of a 5.

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

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

Usage is implied rather than spelled out: the prerequisites sentence (dashboard app must be running, DASHBOARD_API_URL) gives the operative condition, but there is no explicit when-to-use/when-not guidance or named alternative for other send targets. Adequate but with a clear gap.

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?

No annotations provided, so the description carries full transparency burden and delivers: success state mutations (variant.status, platform_settings, publications row), the double-post prevention behavior, and the raw_payload override mechanism. Rich behavioral context for a mutation tool.

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

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

Front-loaded with pipeline step designation and purpose, then flows into the typical flow, success effects, and the raw_payload caveat. Efficient but slightly dense with pipeline step numbering that partly restates the workflow.

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 mutation tool: names required prerequisites via the pipeline flow, discloses success side effects, documents the raw_payload escape hatch, and no output schema exists to explain. All an agent needs to call this correctly is present.

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

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

Schema coverage is 100% so parameters are already documented, and the description reinforces the raw_payload bypass behavior. Adds context on how variant.body_text is used and where integration_id comes from, though doesn't add syntax 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+resource ('Send a variant to Postiz') with scope ('immediate or scheduled publication'). Explicitly positioned as pipeline step 6 and distinguished from siblings like create_variant, update_variant, and list_postiz_integrations.

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 names the preceding pipeline steps (create_variant → update_variant → list_postiz_integrations → send_to_postiz) and states when to use raw_payload as an alternative to the default DTO builder. Nothing left to inference.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the data-model effect on gallery_items.cover_media_id and the distinction from attach_gallery_media, but does not state overwrite semantics, required permissions, or error behavior for a mutation tool.

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

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

Two sentences, zero waste, and the core operation is front-loaded before the sibling-tool caveat. Every sentence carries useful 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 simple two-parameter setter with no annotations and no output schema, the description establishes scope and the key sibling distinction. However, with 0% schema description coverage, it should do more to define the required parameters and mutation side effects.

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

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

Schema description coverage is 0% for two required UUID parameters. The description names cover_media_id and implies media_id, but does not explain item_id, what entity each UUID references, or any constraints, so it only partially compensates for the schema gap.

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

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

States a specific verb ('Set') and exact target ('gallery_items.cover_media_id'), and explicitly distinguishes itself from the sibling attach_gallery_media by describing the extra row that sibling creates.

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

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

Provides clear routing guidance: use attach_gallery_media separately if a gallery_item_media row with role=cover is also needed. It does not spell out when this tool should not be used, but the alternative condition 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?

With no annotations, the description carries the full behavioral burden, and it does disclose the concrete effect: it writes is_featured and featured_rank, and that lower rank sorts earlier. It omits anything about permissions, whether reordering affects existing featured items, or reversibility beyond the implied unpin.

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

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

Two sentences, front-loaded with the action and destination, no filler. The rank-ordering rule is placed immediately after the primary action, which is the right emphasis order.

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 mutation tool with no annotations and no output schema, the description is adequate but thin: it never states permission needs, how it interacts with already-featured items, or what the caller gets back. The essential fields are covered, but an agent could act incorrectly on ordering assumptions.

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, and the baseline is 3. The description adds a modest clarification on rank semantics (lower = earlier) that slightly refines the schema's 'Sort key' wording but nothing beyond that.

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

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

Names a specific paired verb (pin/unpin), the resource (Gallery item), and the destination (landing featured carousel), which is concrete enough for an agent to act on. It does not explicitly differentiate itself from the nearby sibling set_gallery_cover, which is the main gap keeping it from a 5.

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

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

The pin/unpin framing and the is_featured flag imply when the tool applies, but there is no explicit statement of when to choose this over set_gallery_cover or update_gallery_item, and no prerequisites. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full burden, and it discloses two useful traits: markdown_body is converted to PlateJS and replaces content, and publishing is blocked. It omits permissions/auth needs, whether unspecified fields are preserved (partial-update semantics), and failure behavior, leaving notable gaps for a mutation tool.

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

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

Two tight sentences with the core behavior front-loaded; the markdown conversion note and publishing restriction follow logically. No wasted words, though the meta/thumbnail fields are bundled without detail.

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 tool with no annotations and no output schema, the description covers the headline behaviors but omits return/response shape and partial-update semantics, so an agent still lacks pieces needed to call it confidently.

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

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

Schema coverage is only 36% across 11 params, and the description adds detail for markdown_body replacement and the status restriction, but variant_id's 1:1 link/unlink semantics, reading_time bounds, meta_keywords, and meta_description go unmentioned in the description (some are covered in the schema itself). It partially compensates for the coverage gap but not fully.

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 (existing blog post) and enumerates the field groups affected (title, excerpt, meta, thumbnail, body), which cleanly separates it from create_blog_post_from_markdown and update_content siblings.

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

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

Gives a concrete when-not rule and an alternative: status cannot be set to 'published' here, use Studio instead. It does not, however, explain when to prefer this tool over update_content or create_blog_post_from_markdown, so it stops short of full routing 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?

With no annotations, the description carries the full behavioral burden, and it does disclose two meaningful traits: slides REPLACE rather than merge, and new slides get auto-generated ids unless one is passed. However, it omits permissions, reversibility, error behavior, and what happens to fields not supplied.

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 core action, then the replacement rule and the id behavior. Every sentence adds information and there is no filler.

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

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

For a mutation tool with no annotations and no output schema, the description covers the critical replace semantics and id generation well, and the schema is fully documented. It would be stronger with permission or error context, but nothing essential to calling it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: the destructive replace-not-merge behavior of the slides array and the auto-generated id rule for each slide. It says nothing about variant_id, which is left entirely to the schema.

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

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

States a specific verb and resource ('Update an existing carousel') and enumerates the mutable fields (title, caption, slides). It does not explicitly contrast itself with create_carousel or get_carousel, but the name plus the field list make the operation unambiguous.

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

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

There is no when-to-use vs when-not-to-use guidance, no prerequisites, and no pointer to siblings like create_carousel for new decks or list_carousels for discovery. Usage is only implied by 'existing carousel'.

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

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

With no annotations, the description carries the full burden; it discloses the pipeline position and the human-gated publish constraint, which is useful. However, it says nothing about merge vs. replace semantics for the 14 optional fields, permission requirements, or failure behavior on a mutation. Note the published restriction is already implied by the status enum in 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 dense sentences plus a bracketed pipeline tag; each sentence carries distinct information (scope, sequencing, constraint, next step). No filler and the scope 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 14-parameter mutation with full schema coverage and no output schema, the description supplies the workflow context an agent needs (pipeline step, precondition, successor tool, hard limit). It stops short of describing update semantics or partial-update behavior, but nothing essential to selecting the tool is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 14 parameters and the enum constraint. The description names a subset of fields (hook/body/cta/core_message/tags) but 'body' does not exactly match the schema's 'body_md', adding no new semantics. 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 (Edit) and resource (master content fields) and enumerates the fields it touches. The 'master' qualifier, plus the explicit next step to create_variant, cleanly separates it from update_variant and other update_* siblings.

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

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

Gives explicit ordering: use after promote_idea to fill in the draft body, then create_variant once the body is solid. It also states a hard boundary (cannot set status=published; requires human), so an agent knows both when to call it and what it cannot accomplish.

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

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

With no annotations, the description carries the full burden and does meaningfully disclose side effects: published_at/featured_at are auto-set when status becomes published or is_featured becomes true, and kinds[0] is treated as primary. These are non-obvious behaviors an agent must know. It omits auth/permission requirements and whether omitted fields are preserved (patch semantics).

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

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

Front-loads the core action and field list, then adds conditional side-effects. Two dense sentences with little waste. The long field enumeration is somewhat bulky but justified given 0% schema coverage.

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 mutation tool with no annotations and no output schema, the description covers the field set and key side effects but is thin on permission requirements, patch semantics for null/omitted values, and confirmation of what is returned. 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 description coverage is 0%, so the description must compensate. It lists the 13 patchable fields, giving scope, and adds the kinds[0]=primary rule plus timestamp auto-set behavior. However, it provides no per-parameter meaning for the enum values or null semantics (e.g., setting summary to null), which the bare schema cannot 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?

States a specific verb ('Patch') and resource ('Gallery item'), and enumerates the exact mutable fields, which clearly distinguishes it from siblings like create_gallery_item, delete_gallery_item, and set_gallery_featured. It stops short of explicitly naming those siblings or stating the patch-vs-replace semantic (implicit in 'any subset').

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

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

No when-to-use versus when-not-to-use guidance is given. It does not direct the agent to set_gallery_featured for featured toggling or set_gallery_cover for covers, both of which overlap with fields listed here, leaving potential ambiguity unaddressed.

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?

No annotations are provided, so the description carries the full burden. It discloses useful behavior beyond the name: pipeline stage semantics and the un-link effect of topic_id=null. However, it says nothing about permissions, reversibility, or whether unspecified fields are preserved on a partial update, which matters for a mutation tool with zero annotation coverage.

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

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

Three tight sentences, front-loaded with the pipeline stage and the action, then the trigger, then the edge-case instruction. 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 six-parameter mutation with no annotations and no output schema, the description supplies the pipeline context and one tricky parameter behavior but leaves `source` undefined and says nothing about what an update returns or whether omitted fields are cleared.

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 only 17% (just `id`), so the description has to compensate. It names the three refinable fields (angle / target_audience / raw_text) and explains topic_id=null as an explicit un-link, which the schema's bare anyOf does not. It omits the `source` parameter entirely, leaving one of six params undocumented in both places.

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 ('Refine an idea') plus the exact fields it touches and its pipeline slot (Discover, step 2). It implicitly separates itself from promote_idea ('before promoting') and create_idea, though it doesn't name those siblings 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?

Gives a clear triggering condition ('when the agent learns more context before promoting the idea to Content') and a concrete usage rule (topic_id=null to un-link). No explicit when-not-to-use or named alternatives, 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?

No annotations are provided, so the description carries the full behavioral burden for a mutation tool. It confirms a write ('Update') but says nothing about whether omitted fields are cleared, permission requirements, reversibility, or how nested platform_settings are merged.

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

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

A single short sentence with no wasted words and the operation front-loaded, but it is terse to the point of under-specification rather than genuinely efficient.

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

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

For a mutation tool with no annotations, no output schema, five parameters, and a nested object, the description is far too thin. It never explains what the update affects or returns, leaving the agent to reconstruct behavior from the schema alone.

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 (id, status, hashtags, body_text, platform_settings) are already documented in the schema. The description adds no parameter meaning beyond that, which lands at the baseline for high-coverage schemas.

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 clear verb and resource ('Update an existing variant'), so an agent knows the operation targets a variant record. However, it gives no indication of what is updatable or how it differs in scope from create_variant/list_variants, leaving the purpose at the minimum viable level.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as create_variant or the broader update_content. The agent must infer everything about appropriate invocation from the name alone.

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