knowledgeowl

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

Annotations already mark destructiveHint=true, and the description reinforces this with 'MUTATES.' It adds useful behavioral context beyond annotations: the HTTP POST method, API-required fields, the nested current_version structure, and that the created article is returned. It does not discuss auth or side effects, but the annotation covers the destructive nature.

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

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

The description is three sentences with no filler. It front-loads the core purpose, then adds the API endpoint, required fields, passthrough mechanism, and return value. Every sentence contributes distinct, actionable 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 creation tool with nested objects and no output schema, the description covers the critical operational details: the write endpoint, API-required fields, how to pass current_version, and the return value. It does not enumerate all possible subfields of current_version, but the provided structure is sufficient for an agent to construct the call correctly.

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

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

Although schema coverage is 100%, the description adds significant meaning by stating that the API requires status, url_hash, visibility, and current_version even though the schema only marks project_id and name as required. It also explains how to pass the nested current_version object via the fields passthrough, which is essential for correct invocation.

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

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

The description opens with 'MUTATES KnowledgeOwl data: creates a new article,' identifying a specific verb and resource. It also names the exact API endpoint, POST /article.json, which clearly differentiates this creation tool from sibling tools like get_article, update_article, create_category, etc.

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 use when creating a new article, and 'MUTATES' distinguishes it from read-only list/get tools. However, it does not explicitly state when to choose this over update_article or provide any exclusions or alternative routing, leaving some selection guidance 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 only destructiveHint=true in the annotations, the description carries the behavioral burden and delivers: it warns 'MUTATES KnowledgeOwl data,' discloses the API contract, and importantly flags that the API requires six fields (type, project_id, url_hash, name, visibility, status) even though the schema only marks two as required. It also states the return behavior ('Returns the created category'), which matters given there is 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?

Five dense sentences, each earning its place: mutation warning, purpose, endpoint, API-required fields, fields escape hatch, and return value. The mutation flag is front-loaded and there is 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 7-parameter tool with no output schema, the description covers purpose, mutation, endpoint, required inputs, the fields mechanism, and the return value. Minor gaps remain: no prerequisites (e.g., how to obtain project_id), no explicit pointer to update_category for edits, and no mention of error behavior when API-required fields are omitted.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by listing which fields the API actually requires — correcting the schema's impression that only project_id and name matter — and by explaining how to funnel extra documented fields through the 'fields' object. This guides parameter selection beyond what the schema alone provides.

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 — 'creates a new category' — and grounds it in the domain as 'a node in the article tree,' which distinguishes it from sibling tools like create_article and create_glossary_term. The explicit API endpoint (POST /category.json) further pins down the operation.

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

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

Usage is implied: an agent would naturally select this to create a category. However, the description offers no explicit when-to-use/when-not-to-use guidance and never names alternatives such as update_category for modifying an existing category, leaving sibling routing to inference.

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

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

The description goes beyond the destructiveHint annotation by explicitly labeling the operation MUTATES, revealing the endpoint, and stating that extra fields are merged over the typed fields. It also tells the agent the tool returns the created glossary term.

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 contain no filler. The mutation nature, resource, endpoint, fields behavior, and return value are all present and 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?

With no output schema, the description usefully states that the created glossary term is returned. Parameter coverage is complete via the schema, and the destructiveHint annotation covers the write-safety profile. It does not mention error conditions or authorization, but those are not critical for a create operation.

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 meaningful parameter behavior: 'Pass extra documented fields via fields' and the important caveat that these are 'merged OVER the typed fields above.' This helps an agent understand how fields interacts with term, definition, and project_id.

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

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

The description opens with 'MUTATES KnowledgeOwl data: creates a glossary term and definition,' naming a specific action and resource. This clearly separates it from sibling create tools like create_article or create_snippet, and from list_glossary_terms.

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 explicit 'creates a glossary term' phrasing and the MUTATES label, but the description does not state when to prefer this over sibling tools or when not to use it. No alternatives or exclusions are named.

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

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

The description opens with 'MUTATES KnowledgeOwl data' and specifies the HTTP method, which reinforces the destructiveHint annotation. It also discloses that the tool returns the created snippet, adding value beyond the annotations by describing the operation's effect and response.

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 focused sentences with no wasted words. The mutation warning and endpoint are front-loaded, followed by the key parameter guidance and return behavior — 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 creation tool, the description plus schema covers required parameters, the general behavior, and the return value. It does not describe error cases or prerequisites like authentication, but the annotations and schema provide enough context for an agent to invoke this tool correctly.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds valuable meaning by explaining that the snippet body/content should be passed via the fields parameter, with a snippet-specific example ('snippet_text/body'), which helps an agent populate the nested object correctly.

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 ('creates'), a specific resource ('reusable content snippet'), and the exact KnowledgeOwl endpoint (POST /snippet.json). This clearly distinguishes it from sibling tools like create_article, create_category, and create_glossary_term.

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 through the verb 'creates' and the resource type, but there is no explicit guidance about when to prefer this over alternatives, or when a different tool (e.g., update_snippet/list_snippets) would be more appropriate. No exclusions or conditional routing 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?

Annotations declare readOnlyHint=true, and the description adds useful behavioral context: it specifies the HTTP method (GET), the endpoint pattern, and the response envelope structure '{ valid, data:{...} }'. This goes beyond the annotations without contradicting them.

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 communicate the core action, the API endpoint, and the return shape without any filler. The most important information 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 simple one-parameter read-only getter, the description is mostly complete. It mentions the response envelope, and the schema covers the parameter. It doesn't cover error cases or detailed data fields, but given the low complexity and the readOnlyHint, those are not critical 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?

The input schema already fully documents the single required parameter 'id' with a meaningful description ('a Mongo-style hex string'). The description merely repeats 'by id' and adds no new semantic detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific verb ('Fetch'), a specific resource ('a single article'), and the key selector ('by id'). It clearly distinguishes this from sibling tools like list_articles and list_article_revisions by emphasizing the single-record nature.

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 makes the use case clear: retrieve one article when you have its id. It doesn't explicitly name alternatives or exclusion criteria, but the context is strong enough that an agent can infer this is the right tool for direct id-based lookup.

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

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

The readOnlyHint annotation already covers the safety profile, so the description's main contribution is confirming the GET endpoint and single-resource scope. It adds useful but minimal behavioral context; no mention of not-found behavior or response shape is needed given the tool's simplicity.

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-load the action and resource, then provide the endpoint. Every word 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 one-parameter read-only tool with readOnlyHint and full schema coverage, the description is fully sufficient. There is no missing detail an agent needs 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% and the id parameter already includes a helpful type description ('Mongo-style hex string'). The tool description only restates 'by id,' providing no additional meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Fetch a single category by id,' which clearly distinguishes it from list_categories and update_category. It also names the exact API endpoint, leaving no ambiguity about scope.

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 tool's use case is clear: use it when you have a category id and need a single category. It does not explicitly contrast with list_categories or mention when not to use it, so it stops short of full sibling routing.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the HTTP GET endpoint detail, but does not describe behavior on missing ids or the response shape, though those are less critical for a simple read-only lookup.

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-loads the core action and target, with the endpoint as useful confirmation. There is no filler or redundant restatement of the title.

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

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

For a one-parameter read-only lookup, annotations plus schema cover safety and input, and the description gives the endpoint. It is sufficient for an agent to call the tool correctly, though a note about list_readers or not-found behavior would make it even more 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 coverage is 100%; the id parameter is already documented as a Mongo-style hex string. The description does not add extra semantic detail beyond identifying id as the lookup key.

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

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

States a specific verb ('Fetch'), resource ('a single reader'), and selection criterion ('by id'), and includes the REST endpoint. This clearly distinguishes it from list_readers and other get_* siblings at a glance.

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 the correct use case: retrieve one reader when its id is known. However, it does not explicitly say to use list_readers when multiple readers are needed, nor does it provide any when-not or 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?

Annotations already declare readOnlyHint=true, and the description reinforces this with 'READ-ONLY — only GET is allowed'. It adds concrete behavioral details: the requirement to pass a full path starting with slash and including a query string, and the parsed JSON return format. Safety is fully covered; no contradiction.

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

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

Two sentences with zero waste. The purpose is front-loaded, followed immediately by actionable usage rules and examples. Every word 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 one-parameter raw request tool with readOnly annotation and no output schema, this is complete. It covers path construction, allowed method, restrictions, and return type. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% with the path parameter already described and exemplified. The description repeats the same example and emphasizes 'INCLUDING any query string', which the schema example already implies. It adds no significant semantic value 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 (GET) and resource (any KnowledgeOwl API path not wrapped by a dedicated tool), making it clear this is a raw escape hatch. Distinguishes itself from the many specific sibling tools by explicitly targeting unwrapped paths. The examples show exact usage patterns.

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 frames when to use: 'any KnowledgeOwl API path not wrapped by a dedicated tool', which doubles as a when-not condition. The sibling tool list provides the alternatives. 'Power-user escape hatch' signals this is for advanced cases outside normal tooling.

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

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

Annotations already provide readOnlyHint=true, and the description reinforces this with 'read-only' and 'GET'. It adds useful behavioral context by naming the API endpoint and the response envelope { valid, page_stats, data }, which is beyond what the annotations alone supply. It does not discuss rate limits or pagination edge cases, but the annotation coverage lowers the burden.

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 compact and front-loaded: the first clause states the action, and the following fragments give the endpoint and return shape. Every sentence earns its place with no redundant 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 usefully includes the response structure. The schema handles parameter documentation. The main completeness gap is the lack of differentiation from list_article_versions and no mention of what the params object should contain for typical revision filtering.

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 two parameter slots (_page and params), so the baseline is 3. The description adds no parameter-level meaning: it does not clarify which filters are valid, whether an article identifier is expected, or how the params object should be structured beyond the schema.

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

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

The description states a specific verb and resource: 'List article revision history', and adds the clarifying context 'read-only audit trail'. It also exposes the exact KnowledgeOwl endpoint, which helps identification. However, it does not explicitly distinguish this tool from the nearly identical sibling 'list_article_versions'.

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 'read-only audit trail' implies when this tool is appropriate, and the endpoint reference adds concrete context. But there is no explicit guidance about when to prefer this tool over siblings like list_article_versions or list_articles, nor any exclusions or alternative routing.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful behavior beyond that: the exact HTTP endpoint, the optional project_id filter, and the returned envelope { valid, page_stats, data:[...] }. No contradiction with the read-only annotation exists.

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

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

Three compact sentences deliver the core operation, endpoint, optional filter, and return shape with no wasted words. The most important information 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 read-only listing tool with no required parameters, fully described schema, and no output schema, the description supplies the missing return envelope and endpoint. An agent has enough information to invoke it correctly and interpret the response.

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 _page, params, and project_id. The description only restates the project_id filter and contributes no additional parameter-level meaning beyond what the schema provides.

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 and resource: 'List knowledge-base articles' and identifies the KnowledgeOwl endpoint GET /article.json. It does not explicitly contrast itself with sibling tools like list_article_revisions or get_article, but the article-list scope 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 gives no guidance on when to choose this tool over alternatives such as get_article, list_article_revisions, or list_article_versions. The optional project_id filter is parameter-level instruction, not usage routing.

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

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

The readOnlyHint annotation already covers the safety profile. The description adds useful context by naming the REST endpoint and the top-level response shape ('{ valid, page_stats, data:[...] }'), but gives no details on pagination behavior, error cases, or what data entries 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?

The description is appropriately concise—two short sentences that deliver the core purpose, endpoint, and response shape without filler. Every sentence adds value.

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

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

For a read-only list operation with well-covered parameters, the description plus annotations are mostly sufficient. However, the ambiguity with 'list_article_revisions' is unresolved, and the lack of detail about the contents of 'data' or filtering may leave an agent under-informed.

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

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

Schema description coverage is 100%, so the baseline applies. The description does not repeat parameter details, and the schema already documents '_page' and the free-form 'params' object. The description adds no extra meaning beyond the schema.

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

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

The description states a clear verb and resource: 'List article versions', and identifies the exact API endpoint. However, it does not differentiate from the sibling tool 'list_article_revisions', which likely covers a similar or overlapping concept.

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_articles' or especially 'list_article_revisions'. No context, exclusions, or selection criteria are provided, leaving the agent to guess based on 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?

Annotations provide readOnlyHint=true, and the description adds the exact HTTP method and endpoint (GET /agent.json) plus the response envelope { valid, page_stats, data:[...] }, which implies a read-only paginated list. This goes beyond the annotation baseline, though it does not cover auth or rate limits.

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 carry the purpose, endpoint, and return shape with no filler. The most important identifying information 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 simple read-only list with two optional parameters, the description plus schema covers the essentials: endpoint, response envelope, pagination parameter, and read-only intent. It does not enumerate the valid filters accepted through params, but the schema defers those to API documentation.

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

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

The input schema has 100% description coverage for its two parameters, _page and params. The description adds no parameter-specific meaning beyond the endpoint context, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb and resource: 'List authors/agents' and defines them as 'the team members who write and manage content.' This distinguishes it from other list_* tools by resource, though it does not explicitly contrast it with a sibling like list_readers.

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 parenthetical definition implies when to use the tool—when you need content team members/authors—and the endpoint reinforces that. However, there is no explicit when-to-use, when-not-to-use, or routing to alternative 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?

The readOnlyHint annotation already covers safety; the description adds the concrete API endpoint (GET /category.json) and the exact return envelope {valid, page_stats, data:[...]}. This gives the agent useful behavioral detail beyond the annotation.

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

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

Three short sentences with no filler: the operation is named first, then the endpoint and return shape, then the optional filter. Every sentence adds 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?

The tool has no output schema, so the description correctly supplies the return envelope and pagination metadata. It is sufficiently complete given the schema covers the parameters; only minor details like _page behavior are left to the schema.

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

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

Schema description coverage is 100% and all three parameters already have descriptions. The tool description only re-mentions project_id and adds no new parameter syntax or constraints, so the baseline 3 applies.

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

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

The description uses a specific verb ('List') and resource ('categories'), and clarifies that categories mean the article tree/table of contents. This distinguishes it from sibling get/create/update category tools by implying a bulk read.

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 title and list semantics, and the optional project_id filter is noted, but no explicit when-to-use or alternatives are given. There is no guidance contrasting it with get_category or list_articles.

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

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

Annotations already set readOnlyHint=true, and the description reinforces this by specifying the HTTP GET method. It also discloses the return shape as { valid, page_stats, data:[...] }, which is useful context beyond the annotation.

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

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

The description is two tight sentences with the core purpose front-loaded, followed by a useful endpoint and return-format note. No filler or redundant restating of the tool name.

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

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

For a simple read-only list tool with no output schema, the description supplies the essential return structure and endpoint. The absence of alternative-routing guidance is a minor gap, but the tool is otherwise adequately specified.

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 fully documents both parameters: _page and params. The description adds no additional meaning about these parameters, but the baseline of 3 is appropriate when the schema carries the parameter documentation burden.

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

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

The description states a specific verb and resource: 'List reader comments / feedback on articles.' It also names the exact API endpoint (GET /comment.json), making it clearly distinct from sibling list tools like list_articles or list_suggestions.

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 is given on when to use this tool versus alternatives, and no exclusions or prerequisite conditions are mentioned. The description implies a simple read/list use case but does not help an agent choose between list_comments and related list 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?

The readOnlyHint annotation already marks this as a safe, non-destructive operation. The description adds the exact API endpoint and the response envelope shape ({ valid, page_stats, data:[...] }), giving an agent a clear picture of the tool's behavior beyond the annotation.

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 that lead with the purpose, then provide the API endpoint and return shape. Every sentence earns its place with no redundant 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, read-only list tool with no required parameters and no output schema, the description covers the essential facts: what is listed, the API endpoint, and the response format. An agent has enough information to invoke it correctly without further research.

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

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

Schema description coverage is 100%, so both parameters (_page and params) are already documented in the schema. The description adds nothing about parameter semantics, but it does not need to; the baseline of 3 applies because the schema carries the full burden.

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

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

States a specific verb ('List') and resource ('files in the file library (images/attachments)'), clearly distinguishing it from sibling tools like list_articles or list_categories. The API endpoint is also named, leaving no ambiguity about what the 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?

The description clearly scopes the tool to a specific resource type ('file library (images/attachments)'), which implies when to use it relative to the list_* siblings. It does not explicitly state when not to use it or name alternatives, but the context is clear enough for tool selection.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral context by specifying the HTTP method (GET), the API endpoint, and the top-level response shape ({ valid, page_stats, data:[...] }). No contradictions with the annotations were found.

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

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

The description is two sentences long and wastes no words. The core purpose is front-loaded, followed by the API endpoint and return shape, which are directly useful to an agent.

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 straightforward read-only list operation with two optional parameters, the description is largely complete: it names the endpoint, indicates a GET request, and reveals the response envelope. With no output schema present, the explicit return structure adds value. It could mention pagination-related details like page_stats semantics, but the schema covers the _page parameter.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add additional parameter-level meaning beyond the schema, but it does not need to because _page and params are already adequately described in the input schema.

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

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

The description opens with a specific verb and resource: 'List glossary terms and definitions,' which clearly identifies what the tool does. The endpoint reference 'GET /glossaryterm.json' further pins down the scope and distinguishes it from sibling tools like create_glossary_term and list_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 usage context is implied: use this tool when you need glossary terms and definitions. However, there is no explicit guidance about when to choose this over related tools such as create_glossary_term or list_synonyms, and no mention of exclusions or limitations.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds the exact API endpoint and the response shape ({ valid, page_stats, data:[...] }), providing useful behavioral context beyond the annotation, though it does not cover pagination behavior or rate limits.

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-load the purpose, then add the API endpoint and return shape. There is no filler; every clause contributes 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 read-only list operation with 0 required parameters, the description plus schema cover the essentials. The return shape is disclosed, and the schema documents the optional parameters. Missing details like pagination field mapping are minor given the low 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 100%: both _page and params have descriptions in the input schema. The description adds no parameter-level details, so the baseline score of 3 is appropriate.

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

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

States a specific verb and resource ('List readers'), clarifies what 'readers' means ('knowledge-base end users / audience accounts'), and names the exact API endpoint. This makes it clearly distinguishable from sibling list_* tools and get_reader.

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 'List readers' phrasing, but there is no explicit guidance on when to choose this tool over alternatives like get_reader or knowledgeowl_request. No exclusion criteria or alternative tooling is mentioned.

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

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

The readOnlyHint annotation already covers the safety profile, so the description does not need to restate that this is read-only. The description adds value by naming the exact API endpoint and the response envelope ({ valid, page_stats, data:[...] }), which is useful since there is no output schema. It does not explain page_stats or pagination behavior, but the annotation lowers the bar for behavioral 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 sentences with no filler. The first sentence states the action and resource, and the second provides the endpoint and return shape. Every word 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 simple read-only list operation with no required parameters and full schema coverage, the description is sufficient. It provides the response envelope despite lacking an output schema, though it could have briefly explained the meaning of page_stats or noted that results are paginated to be 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?

Schema coverage is 100%, so both parameters (_page and params) are documented in the schema. The description does not add further parameter-level meaning, such as examples or the effect of params on filtering, which keeps it at the baseline of 3.

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 ('List') and a distinct resource ('reusable content snippets'), which clearly identifies the tool's purpose and separates it from sibling list tools like list_tags or list_glossary_terms. It does not explicitly distinguish itself from a same-resource alternative, but the resource name and endpoint make the intent unambiguous.

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

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

No guidance is given about when to use this tool versus other list_* tools or alternatives. The description does not mention filtering, pagination strategy, or any exclusions, leaving the agent to infer appropriate usage solely from the resource name.

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

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

Annotations already mark readOnlyHint=true, and the description adds useful behavioral context beyond that: it identifies the underlying KnowledgeOwl API endpoint (GET /suggest.json) and the top-level response shape. This gives the agent concrete expectations about the operation without contradicting the annotations.

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

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

The description is concise and front-loaded: two sentences capture the tool's purpose, data interpretation, API endpoint, and response shape. Every sentence adds value, and there is no redundant 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?

For a list tool with no output schema, the description adequately explains the endpoint and return structure. The meaning of specific response fields like `valid` and `page_stats` is not elaborated, but the core purpose and response skeleton are clear enough for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the input schema fully documents both `_page` and `params`. The description adds no additional parameter-level meaning, which is acceptable since the schema already carries that burden. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'List search suggestions / reader search analytics', then clarifies what the data means ('what readers searched for'). This clearly distinguishes it from other list_* siblings like list_synonyms or list_tags by focusing on reader search behavior rather than generic 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?

The description provides clear context for when to use the tool: when you need reader search analytics or to see what readers searched for. It does not explicitly name alternative tools or state when not to use it, so it stops short of a perfect score, but the intended use case is unambiguous.

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

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

The readOnlyHint annotation already marks this as safe, and the description aligns with a read-only GET. The description adds value by revealing the exact endpoint (GET /synonym.json) and the response envelope { valid, page_stats, data }, which helps the agent anticipate pagination and response structure. No contradictions with annotations.

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

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

The description is a single, information-dense sentence that front-loads the core purpose, then adds the endpoint and return shape. There is zero redundant text, and 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?

For a read-only list tool with two optional parameters and no output schema, the description is complete: it states the resource, the endpoint, and the response format. The schema covers the parameters, so nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, with _page and params already documented in the schema. The description does not add parameter-specific details, but per the baseline, the schema carries the semantic weight and the tool is simple enough that no additional param guidance is necessary.

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

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

The description uses a specific verb and resource: 'List search synonyms', and clarifies the domain meaning ('terms treated as equivalent by search'). It also names the exact API endpoint and return shape, leaving no ambiguity about what the tool does. This distinguishes it from sibling list tools like list_glossary_terms and list_tags.

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 description (listing search synonyms), but there is no explicit guidance on when to choose this over alternatives or when not to use it. Given the many sibling list tools, a sentence about exclusions or alternatives would strengthen the definition, but the core purpose is evident enough for basic selection.

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

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

Annotations already declare readOnlyHint=true, and the description adds value by specifying the HTTP method (GET), the endpoint, and the response shape. This gives the agent a clear picture of a safe read-only listing operation without contradicting the annotation.

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 deliver the core purpose, the endpoint, and the return shape with no redundant information. Every sentence earns its place and the key verb-resource pair 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 simple read-only list tool with only two well-documented parameters and no output schema, the description is complete. It covers what the tool does, how it is called, and what response to expect, so an agent has enough context 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 description coverage is 100%, so the parameters _page and params are already fully documented in the schema. The description does not add parameter-level detail, matching the baseline for fully covered 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?

The description states a specific verb and resource ('List article tags') and identifies the exact API endpoint (GET /tag.json). This clearly distinguishes it from sibling tools like list_articles or list_snippets.

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

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

Usage is implied by the resource name and endpoint, but there is no explicit guidance on when to use this tool versus alternatives like knowledgeowl_request or list_articles. No when-not-to-use or exclusion criteria 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?

The readOnlyHint annotation already establishes that this is a safe read operation, and the description adds useful behavioral context by specifying the HTTP endpoint and the shape of the response: { valid, page_stats, data:[...] }. This goes beyond what the annotation alone provides.

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

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

The description is three short, purposeful sentences. It leads with the core purpose, then the endpoint, then the return shape. No filler or redundant wording. Every sentence contributes 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 read-only list operation with fully documented parameters and no output schema, the description is nearly complete: it states the purpose, endpoint, and response envelope. The main omission is a detailed explanation of pagination behavior, but the schema already documents _page as 1-based and the response hints at page_stats, so this is acceptable.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters (_page and params). The description itself adds no parameter-level detail, but none is needed because the schema carries that burden.

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

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

The description uses a specific verb and resource: 'List configured webhooks.' It also names the exact API endpoint, which disambiguates it from the many sibling list_* tools. No other sibling targets webhooks, so the resource is clearly distinct.

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 makes the tool's usage context obvious: it lists configured webhooks. It does not explicitly discuss when not to use it or compare it with knowledgeowl_request, but among the sibling tools no alternative webhook-listing tool exists, so the guidance is effectively 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?

Annotations already indicate destructiveHint, and the description reinforces this with 'MUTATES' while adding non-obvious behavior: the API uses PUT with only-included-fields-change semantics, and the id is never sent in the request body. This goes beyond the bare annotation and helps the agent understand the operation's side effects.

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, each with a distinct purpose: identify the operation, state the HTTP semantics, and clarify the two non-obvious parameter behaviors. No filler, no repetition of schema definitions.

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?

Combined with the exhaustive schema and destructiveHint annotation, the description covers operation type, endpoint, partial-update behavior, and the path/body split. It does not describe return values, but no output schema exists and the required parameter is already documented in the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter guidance: the `fields` passthrough is the correct way to send current_version/body, and it merges over typed fields. The note that id is path-only prevents a common invocation error.

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 ('updates') and resource ('existing article'), and the leading 'MUTATES' clearly signals a write operation, distinguishing it from read/list/create siblings. The explicit endpoint further pins down the exact operation.

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

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

The description makes clear this tool is for modifying an existing article, and the partial-update semantics ('only included fields change') convey when it is appropriate relative to create/get alternatives. It does not name sibling tools explicitly or state when not to use it, but the context is sufficiently obvious.

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

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

Annotations only give destructiveHint=true; the description adds HTTP PUT, partial-update semantics ('only included fields change'), and the fact that the id is path-only. This materially clarifies side effects, though it does not cover auth, error, or failure behavior.

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

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

Three short sentences lead with the operative verb and pack only non-redundant details: mutation, endpoint, partial-update behavior, passthrough, and id placement. Nothing is wasted.

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

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

For a partial-update tool with a rich schema and no output schema, the description gives enough to invoke correctly: resource, method, partial-update semantics, id placement, and passthrough behavior. It could mention the return value, but that is not essential for 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 covers all six parameters, so the baseline is 3; the description adds meaning beyond the schema by explaining the 'fields' passthrough and clarifying that the id is never sent in the JSON body. This prevents body/path confusion.

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?

Description identifies the exact action ('updates') and resource ('existing category'), and 'MUTATES' distinguishes it from non-mutating category tools; 'existing' rules out creation. Clear and unambiguous even 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?

Use is implied: update an existing category, with the 'fields' passthrough for other documented fields. But it does not name alternatives like create_category or update_article, nor 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.