Kamaan

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

With no annotations, the description must carry behavioral load. It usefully discloses the default implicit filtering (blog-only) that governs the whole result set, but says nothing about read-only safety, result size/pagination, or the limit cap behavior beyond what the schema already 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 zero filler; the default-scope constraint is front-loaded before the content_kind escape hatch, which is exactly the ordering 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 listing tool with no output schema, the description never characterizes what comes back (item shape, ordering, pagination) and drops the collection_id filter that exists in the schema. Filtering scope is well covered, but the return-side picture 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 67% and the description restates the content_kind semantics already documented in the schema, adding no new syntax or interaction detail. It does mention language/status and content_kind but omits collection_id and limit semantics entirely.

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 (articles in a site), plus the key scope detail that the default is BLOG-only content. However, it never distinguishes itself from the closest sibling, Search_Articles, which an agent must choose between for the same resource.

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 on how to drive the tool's main branch point: default blog listing, content_kind='help' for KB articles, 'all' for both. It does not state when to prefer this over Search_Articles or Read_Article, so it stops short of full alternative 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 states the return value ('Returns the created collection') but omits permissions, side effects, constraints, or what happens on slug collision. The default behavior for content_kind is noted but that's already 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?

Two concise sentences, front-loaded with purpose and an important constraint, then return value. Zero 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 creation tool with no annotations and no output schema, the description covers purpose and the key content_kind constraint but omits required permissions, potential errors (e.g., duplicate slug), and side effects. 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 88%, so the schema already documents nearly all parameters. The description only emphasizes content_kind default and requirement, which is already stated in the schema enum description. Baseline 3 is appropriate.

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

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

Clear verb+resource: 'Create a help-center collection (section) to group KB articles.' It explains the domain concept, but doesn't differentiate from siblings like Update_Collection beyond the obvious verb.

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 explicit when-to-use or when-not-to-use guidance. The note about content_kind='help' is a constraint, not a usage guideline. No alternatives named.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the most critical trait — permanence and irreversibility — which is genuinely valuable, but says nothing about permission requirements, cascading effects on child content, or what a successful response contains.

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

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

Two tight sentences with the destructive action front-loaded and the irreversibility caveat immediately after. No filler, no repetition of the title, and each sentence carries distinct information.

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

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

For a destructive, irreversible mutation with zero annotations, 0% schema coverage, and no output schema, the description is too thin. It should at minimum explain the required site_id scoping and any auth or permission expectations that an agent must satisfy before calling.

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

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

Schema description coverage is 0% for both parameters. The description only implies 'article_id' via 'by its ID' and never mentions 'site_id' at all, despite it being required, leaving the second parameter completely undocumented in both schema and prose.

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 ('delete an article (blog or help) by its ID') and clarifies the two content types it applies to. The verb 'Delete' naturally distinguishes it from Edit_Article and Write_Article, but the description never names a sibling explicitly, so it stops short of a 5.

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

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

There is no when-to-use guidance, no routing to Edit_Article for non-destructive changes, and no statement of prerequisites such as required permissions or article state. The only hint at selection criteria is the irreversibility warning, which is a consequence rather than a usage rule.

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

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

With no annotations, the description carries the full behavioral burden and does well: it explicitly discloses the non-obvious side effects (articles detached, collection cleared, children promoted to top level) and, crucially, that the delete does NOT cascade. It omits auth/permission requirements and reversibility, keeping it just short of a 5.

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

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

Three tight sentences: purpose first, then consequences, then the crucial non-cascade clarification. Every sentence earns its place with no redundancy.

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

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

For a low-complexity two-parameter mutation with no annotations and no output schema, the description covers the operation and its side effects well enough to call it safely. The only gaps are permissions and confirmability, which are minor for this tool's scope.

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

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

Schema description coverage is 100%, so the schema already documents site_id and collection_id. The description adds no parameter-level detail, which is acceptable given the schema does the heavy lifting, 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 ('Delete a collection') that is immediately distinguishable from Delete_Article and the other sibling operations. The first sentence alone tells an agent exactly what this tool does.

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 there are no alternative collection-deletion tools to route against, so no explicit when-to-use is needed. However, it offers no preconditions (e.g. ownership/permission requirements) or caution guidance, leaving the agent to infer readiness.

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 33-parameter mutation, and it discloses almost nothing. It does not say whether the update is a merge/partial patch (only implied by "fields"), whether omitted fields are preserved, what permissions are required, or whether edits are reversible. For a write tool with zero annotation coverage this is a substantial 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 — the verb and resource come first. It is efficient, though the brevity here reflects under-specification rather than disciplined conciseness.

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

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

For a 33-parameter mutation with no annotations, no output schema, and 27% schema coverage, this one-liner is far too thin. Nothing addresses partial-update semantics, enum-governed interactions (e.g. status/scheduled_for), or the many parameter relationships an agent must respect.

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 27% across 33 parameters, so the description is required to compensate and it adds no parameter meaning whatsoever. It never clarifies that only supplied fields change, nor explains the many undocumented fields (slug, tags, keywords, primary_category) that the schema also leaves bare.

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

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

The description uses a specific verb+resource ("Update fields on an existing article") and implies partial rather than full replacement, so the purpose is immediately legible. However, it does nothing to distinguish itself from close siblings such as Update_Collection, Update_SEO_Fields, or Write_Article, 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 guidance, no mention of when to prefer Write_Article (create) or Update_SEO_Fields, and no prerequisites such as the article needing to exist. The agent is left to infer routing 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, the description carries the full burden. It usefully discloses that each collection includes a count of published help articles and that content_kind='all' returns every collection, but it does not state that this is a read-only operation, mention permissions, pagination, or ordering.

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

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

Two tightly written sentences with the core purpose and scope front-loaded. Every sentence adds value, 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 simple two-parameter list tool with no output schema, the description adequately conveys what is returned at a high level. It could be more complete about pagination, ordering, or the full shape of each collection, but it covers the essentials.

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 description largely repeats the schema's content_kind default and 'all' behavior without adding syntax or meaning beyond it. site_id is only implied by 'for a site' and not elaborated.

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 'help-center collections (sections)' for a site, with the added return detail of published article counts. This clearly distinguishes it from sibling tools like Create_Collection, Update_Collection, and Browse_Articles.

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 explains the default content_kind behavior but gives no guidance on when to use this tool versus alternatives such as Browse_Articles or Search_Articles. No prerequisites, exclusions, or workflow context are 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 full burden. It implies a safe read (listing) and discloses that article counts are included, but says nothing about permissions requirements, result limits, or the shape of the returned list. For a zero-parameter read tool the risk is low, so this is a moderate gap rather than a serious one.

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

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

A single front-loaded sentence with no filler, and the most decision-relevant information (what is listed and that counts are included) comes first.

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

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

For a parameterless listing tool with no output schema, the description covers what it returns (sites plus article counts) which is the key missing structural piece. Minor gaps remain around ordering/pagination and the exact fields returned per site.

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 document; this meets the baseline of 4 by default.

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 Kamaan sites you can access') and clarifies scope with '(your blogs)', which is more precise than the bare name. It is clearly distinct from the singular Site_Details sibling, though it never names that sibling explicitly.

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

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

The phrase 'sites you can access' implies an access-scoped listing context, so the use case is inferable, but there is no explicit when-to-use statement and no mention of how this differs from Site_Details for per-site information.

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. 'Read' implies a non-mutating operation and 'in full' hints at return completeness, but nothing is said about authentication or site access requirements, rate limits, pagination, or what the response body contains for a read with no output schema.

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

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

A single short sentence with zero filler, and the action is front-loaded. It is efficient, though its brevity reflects under-specification rather than disciplined editing.

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?

Two required parameters with no schema descriptions, no annotations, and no output schema means the description is the only source of information an agent has, and it covers essentially none of what is missing. It is not adequate for calling the tool confidently.

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

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

Schema description coverage is 0%, so the description must compensate for two undocumented required parameters. It only addresses article_id ('by its ID') and never explains site_id, its relationship to the article, or the expected identifier format, leaving half the inputs 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 (read) and resource (article) with a clear scope qualifier ('in full'), which implicitly distinguishes it from the listing siblings like Browse_Articles and Search_Articles. It stops short of explicitly naming those alternatives, so sibling differentiation is inferred rather than stated.

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

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

There is no when-to-use guidance and no mention of alternatives, despite the presence of Search_Articles and Browse_Articles as obvious near-neighbors. 'By its ID' hints at the required lookup mode but never tells the agent when this is the right call versus a search.

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 behavioral burden and successfully discloses key traits: order equals index, unknown IDs are skipped, and the updated collection list is returned. It does not cover permissions, idempotency, or partial-list effects, but it is substantially transparent 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?

The description is four short sentences, front-loaded with the core action, and each sentence adds useful operational detail. There is no redundant or filler text.

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 reorder mutation with no annotations and no output schema, the description covers the action, parameter behavior, unknown-ID handling, and return value. Missing authorization requirements and behavior when only a subset of known IDs is provided are the main remaining gaps.

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

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

Schema coverage is 100%, so the schema already documents both parameters and establishes a baseline of 3. The description adds meaningful semantics beyond the schema by explaining that each ID is assigned order equal to its index and that all collection IDs should be passed.

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: reorder collections within a site. No sibling tool performs reordering, so the purpose is immediately distinguishable from Create_Collection, Update_Collection, and List_Collections.

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

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

The description implies when to use it by instructing the caller to pass all collection IDs in the desired order. However, it does not explicitly compare against alternatives like Update_Collection or state when not to use 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 carries the full behavioral burden. It never confirms this is a read-only operation, says nothing about result ordering, pagination, or the effect of 'limit', and gives no indication of what the returned results contain.

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, zero filler, with the default-scope behavior front-loaded before the override. Nothing redundant.

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

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

With no annotations and no output schema, the description should cover the return shape and the meaning of site_id/limit, but it stops at content_kind. It is adequate to make a correct call in the common case but leaves real gaps for a 4-parameter 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 only 25%, so the description must compensate and it does partially: it explains the content_kind enum values and their default, and clarifies that query matches title/focus keyword. site_id and limit remain unexplained in both schema and description.

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 ('Search a site's articles') and scopes the search field to title / focus keyword, which is concrete. It does not explicitly contrast itself with Browse_Articles or Read_Article, so the sibling differentiation is left 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?

The description gives clear routing among content kinds (blog default, 'help' for KB, 'all' for both), which is genuinely useful. However it offers no guidance on when to search versus browsing/reading a known article, which is the more important sibling decision among these 15 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, the description carries the full burden, and it only implies a read via the verb 'Get'. It does not state whether authentication or a specific permission scope is required, nor what happens when site_id is invalid or unknown. It does at least disclose the shape of the returned data, which is the main behavioral value here.

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

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

A single short sentence with the resource, scope, and returned fields front-loaded. Every clause earns its place and nothing is padded.

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

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

For a one-parameter read tool with no output schema, the description covers the key returned fields and the single-site scope, which is close to sufficient. It could still mention error behavior for unknown IDs or any permission requirement.

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

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

Schema description coverage is 100% and there is only one parameter (site_id) whose schema description is simply 'The site ID.' The description adds no format, source, or syntax hints beyond what the schema already states, 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 (Get) and resource (details for one site) and enumerates the payload (languages, translation config, domain), which is helpful since there is no output schema. It does not differentiate itself from the sibling My_Sites, 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 phrase 'for one site' plus the required site_id implies this is the lookup to use once you already know a site ID, as opposed to My_Sites which presumably enumerates them. However, no sibling is named and there is no explicit when-to-use or when-not-to-use statement.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose two meaningful traits: the operation runs synchronously and it creates new translated articles (a write side effect). It stops short of stating permissions, idempotency, overwrite behavior for existing translations, 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?

A single front-loaded sentence with no filler; the parenthetical efficiently carries the two key behavioral facts. Nothing is wasted, though it is arguably too terse for a mutation tool.

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

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

For a write tool with no annotations, no output schema, and 4 parameters at 25% schema coverage, the description should resolve the target_language vs target_languages ambiguity and say more about the resulting artifacts. It covers the mutation/synchronous facts but leaves key calling decisions to inference.

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% — only target_language is documented in the schema. The description's phrase 'one or more target languages' hints at the single-vs-multiple split between target_language and target_languages, but it never explains when to use which, and site_id/article_id carry no added 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 (translate an article) and a clear scope (one or more target languages). It implicitly separates itself from Edit_Article/Write_Article by producing translated copies, but it never names or contrasts a sibling explicitly.

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

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

There is no when-to-use guidance, no prerequisites (e.g. whether the source article must exist, whether existing translations are replaced), and no mention of alternatives such as Edit_Article. The agent must infer all usage conditions 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.

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

With no annotations, the description carries the full behavioral burden. It usefully discloses PATCH-style semantics ("only the fields you pass are changed"), which is a real trait beyond the schema, but it omits permissions/auth needs, how slug uniqueness conflicts are handled, and undo/irreversibility for a mutation. Some value, substantial gaps.

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

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

Two short sentences with no waste, and the core behavior (partial update) is front-loaded immediately after the purpose. 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?

For a 9-parameter mutation tool with no annotations and no output schema, two sentences is thin. Missing auth requirements, slug-uniqueness behavior, the order vs Reorder_Collections relationship, and any note on failure/partial-success semantics leave the agent under-equipped.

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 56%, so roughly half the parameters are described in the schema. The description only adds the meta-rule that unpassed fields are untouched; it gives no meaning for the undocumented params (e.g. name, order, description, content_kind) and does not clarify the order/reorder distinction.

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?

"Update fields on an existing collection" gives a specific verb (update) and resource (collection), and the second sentence clarifies it is a partial update. However, it does not distinguish this tool from siblings like Reorder_Collections (despite an `order` param here) or Update_SEO_Fields, leaving some ambiguity about which update tool to pick.

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. Given that Reorder_Collections exists and this tool also accepts an `order` parameter, the agent gets no help deciding between them, and no prerequisites 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully signals that content fields are untouched ('only the SEO/meta fields'), but says nothing about permissions, whether omitted fields are cleared or preserved, reversibility, or rate limits — significant gaps for a mutation tool with 13 fields to mutate.

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 waste; the scope constraint ('only') is positioned immediately after the verb. It is efficient, though arguably under-sized for a 15-parameter tool.

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

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

With 15 parameters, no annotations, no output schema, and near-zero schema coverage, the one-sentence description is too thin. It establishes scope but omits which fields are updatable, whether updates are partial or full-replace, and what the response looks like — the agent has little to go on beyond the tool name.

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 13% (just og_image and twitter_image), and the description adds no per-parameter meaning. It does not clarify the required site_id/article_id pairing, the schema_type enum, the focus_keyword vs keywords distinction, or the slug/canonical_url semantics, leaving 13 of 15 parameters effectively undocumented.

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

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

The description states a specific verb ('Update'), a specific resource ('SEO/meta fields of an article'), and scopes it with 'only', which implicitly separates it from the content-editing siblings Edit_Article and Write_Article. It stops short of naming any sibling, so the differentiation is inferable rather than explicit.

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

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

'only the SEO/meta fields' implies the intended context (metadata tweaks rather than full article edits), which is a reasonable usage signal. However, it never states when to prefer this over Edit_Article, nor any prerequisites or exclusions, leaving the routing decision to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden for a 34-parameter mutation tool. It discloses the content_kind default and that the created article is returned, but says nothing about write side effects, required permissions, the default value of status (draft vs. published), or how scheduling behaves — even though the schema shows a scheduled_for/status interaction that could auto-publish.

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, entirely front-loaded, with the default behavior first and the return value last. Every sentence adds information and none is redundant.

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

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

For a create tool with no annotations, no output schema, and 34 parameters at 29% description coverage, the definition is thin. It covers the blog/help fork and mentions the return, but leaves default status, scheduling behavior, and nearly all optional fields unexplained, which is inadequate for a tool of this complexity.

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 29% across 34 parameters, so the description should compensate and largely does not. It explains the content_kind branch and the collection_id pairing, but the vast majority of parameters (tags, status, seo_score, article_type, primary_category, translation_status, etc.) carry no meaning from either the schema or the description. Only the one branch is 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?

States a specific verb and resource ('Create a new article') and immediately qualifies the two supported outcomes (blog post vs. help-center article via content_kind="help"). It clearly separates creation from the edit/read/delete siblings by verb, though it never names an alternative tool. An agent can identify the operation without opening the schema.

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

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

The description gives an explicit conditional: default is a blog post, and use content_kind="help" (paired with a collection_id) for a KB article. That is real routing guidance for the main branch point. It stops short of any when-not guidance (e.g., use Edit_Article to modify an existing post, or Translate_Article for localizations).

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