Read and write knowledge-base articles, categories, snippets, glossary, readers, and search data.
The last two health checks of this connector failed. If this server requires authentication, missing or expired test credentials may be the cause. A test profile lets Glama authenticate for health checks and discover tools; it is separate from your personal connections.
If you are the author, claim ownership, then add or update a test profile under Admin → Test Profile.
Scored across 24 tools
Each tool targets a clearly named resource+action, and the article revision vs. version distinction is clarified in the descriptions. The only real overlap is knowledgeowl_request, which as a read-only GET escape hatch can duplicate any list/get tool, but it is explicitly framed as a power-user fallback.
Every tool follows the same knowledgeowl_<verb>_<noun> snake_case pattern (create_article, get_category, list_snippets, update_article). Verbs map predictably to CRUD semantics with no mixed conventions.
24 tools is on the heavy side, but the breadth reflects the many distinct KnowledgeOwl resources (articles, categories, snippets, glossary, readers, tags, webhooks, etc.), so each tool maps to a real endpoint. A few list-only tools could arguably be consolidated with the request escape hatch.
The surface is asymmetric: articles and categories get create/get/list/update, but there is no delete operation anywhere and no update for snippets, glossary terms, files, tags, webhooks, or synonyms — many resources are list-only. Since knowledgeowl_request is GET-only, agents cannot work around the missing mutating operations.
MUTATES KnowledgeOwl data: creates a new article. KnowledgeOwl API: POST /article.json (JSON). Required by the API: project_id, name, status, url_hash, visibility, and current_version (a nested object { <lang>: { title, body, ... } } — pass it via the fields passthrough). Returns the created article.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The article name/title (required). | |
| fields | No | Additional documented KnowledgeOwl fields to send in the JSON write body (e.g. current_version, body) — merged OVER the typed fields above. | |
| status | No | Publishing status, e.g. "published", "draft", "review". | |
| url_hash | No | The article URL slug (e.g. "getting-started"). | |
| project_id | Yes | The knowledge base (project) id this article belongs to (required). | |
| visibility | No | Visibility, e.g. "public" or "private". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, and the description reinforces this with an explicit 'MUTATES KnowledgeOwl data' marker rather than contradicting it. It adds value beyond annotations by disclosing the endpoint and that the call returns the created article, though it does not mention permission requirements or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight paragraph with the mutation warning front-loaded and the endpoint, required fields, and return value packed efficiently into it. Minor deduction because the required-field list is dense inline and slightly muddies what the caller must actually supply versus what the API expects.
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 mutating tool with a nested-object parameter and no output schema, the description covers endpoint, payload shape, passthrough mechanism, and return value. It is not fully airtight: it lists six 'API required' fields while the schema requires only project_id and name, leaving the agent to guess how much is truly mandatory versus server-defaulted.
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 meaning the schema lacks: it names the six API-required fields and explains the nested shape `{ <lang>: { title, body, ... } }` for current_version, which the schema only alludes to via an 'e.g.' in the `fields` 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 and resource ('creates a new article') and prefixes it with the mutation scope, which cleanly separates it from knowledgeowl_update_article and the other knowledgeowl_create_* siblings. It also names the underlying API operation (POST /article.json), removing any ambiguity about what happens.
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 practical invocation guidance by naming the API-required fields and explaining that the nested current_version object must be routed through the `fields` passthrough, which is the non-obvious part of calling this tool. It stops short of explicitly contrasting creation with update_article or stating prerequisites (permissions, existing project).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
MUTATES KnowledgeOwl data: creates a new category (a node in the article tree). KnowledgeOwl API: POST /category.json (JSON). Required by the API: type, project_id, url_hash, name, visibility, status. Pass extra documented fields via fields. Returns the created category.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The category name (required). | |
| type | No | The category type (e.g. "blank", "topic", "custom-content"). | |
| fields | No | Additional documented KnowledgeOwl fields to send in the JSON write body (e.g. current_version, body) — merged OVER the typed fields above. | |
| status | No | Publishing status, e.g. "active". | |
| url_hash | No | The category URL slug. | |
| project_id | Yes | The knowledge base (project) id this category belongs to (required). | |
| visibility | No | Visibility, e.g. "public" or "private". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description declares a mutation ('MUTATES'), consistent with destructiveHint=true, and adds the transport (JSON POST) and return value ('Returns the created category') beyond the annotations. The most valuable disclosure is that the API itself requires six fields (type, project_id, url_hash, name, visibility, status) even though the schema marks only two as required — a real behavioral gap surfaced in prose. It stops short of saying what happens on duplicate url_hash or whether the node is placed under a parent.
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 dense, front-loaded block that opens with the mutation warning and the resource before listing API requirements. Every sentence carries information, though the telegraphic API-requirement list reads more like a spec dump than prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers mutation semantics, endpoint, required API fields, the escape hatch for extra fields, and the return value despite there being no output schema. Missing only edge-case behavior (duplicates, tree placement) for a 7-parameter write tool with a nested `fields` object.
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 and the schema already documents every field including the `fields` merge behavior. The description's enumeration of API-required fields adds some meaning by contradicting the schema's narrower required list, but adds no format or value examples beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource with scope: 'creates a new category (a node in the article tree)', plus the underlying endpoint POST /category.json. This clearly separates it from knowledgeowl_update_category (modify) and knowledgeowl_create_article (different 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?
Usage is implied by the verb 'creates' and the 'MUTATES KnowledgeOwl data' framing, and it explains how to send extra fields via `fields`. However, it never explicitly says when to prefer this over update_category, nor does it mention prerequisites such as a valid project_id or uniqueness constraints on url_hash.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
MUTATES KnowledgeOwl data: creates a glossary term and definition. KnowledgeOwl API: POST /glossaryterm.json (JSON). Pass extra documented fields via fields. Returns the created glossary term.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | The glossary term (required). | |
| fields | No | Additional documented KnowledgeOwl fields to send in the JSON write body (e.g. current_version, body) — merged OVER the typed fields above. | |
| definition | No | The term's definition. | |
| project_id | Yes | The knowledge base (project) id this glossary term belongs to (required). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With destructiveHint=true already in annotations, the description adds useful context: it is a mutating JSON POST to /glossaryterm.json, extra fields are merged over typed fields, and it returns the created term. It does not cover auth or error behavior, which keeps it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the mutation warning and endpoint, with no wasted 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 create mutation with no output schema, it covers the mutation, endpoint, extra-field mechanism, and return value. It lacks permission/error context but is otherwise sufficient.
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 four parameters. The description adds only a small amount of meaning by reiterating that `fields` carries extra documented fields and is merged over typed fields.
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 glossary term and definition.' It clearly distinguishes the tool from the list/get siblings, though it does not explicitly name an alternative create tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It signals 'MUTATES KnowledgeOwl data' and explains that extra documented fields go through `fields`, but it does not state when to prefer this tool over siblings or what prerequisites/permissions are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
MUTATES KnowledgeOwl data: creates a reusable content snippet. KnowledgeOwl API: POST /snippet.json (JSON). Pass the snippet body/content and any other documented field via fields (e.g. snippet_text/body). Returns the created snippet.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The snippet name (required). | |
| fields | No | Additional documented KnowledgeOwl fields to send in the JSON write body (e.g. current_version, body) — merged OVER the typed fields above. | |
| project_id | Yes | The knowledge base (project) id this snippet belongs to (required). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description leads with "MUTATES KnowledgeOwl data," consistent with destructiveHint=true, and adds context beyond annotations: the HTTP endpoint, the JSON body format, and the fact that the created snippet is returned. It doesn't cover failure modes or auth requirements, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences: mutation warning first, then endpoint, then parameter and return guidance. No wasted text, though the parameter sentence is slightly redundant with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter creation tool with a nested free-form object and no output schema, the description covers the write semantics, the endpoint, how to pass additional documented fields, and what comes back. Only extended behavioral details (error handling, permission requirements) are absent.
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 required params and the `fields` merge behavior are already documented. The description only restates that `fields` accepts the body/content (with a slightly different example set, snippet_text/body vs. schema's current_version/body), so it adds little beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("creates a reusable content snippet") and pairs it with the concrete API operation POST /snippet.json, which clearly separates it from sibling creators like knowledgeowl_create_article or knowledgeowl_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?
The verb 'create' plus the sibling set makes the intended usage fairly obvious, but the description never states when to choose this over alternatives or what prerequisites exist (e.g. required permissions or how the snippet must be scoped to project_id).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single article by id. KnowledgeOwl API: GET /article/{id}.json. Returns { valid, data:{...} }.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The article id (a Mongo-style hex string). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered structurally. The description adds real value beyond that by disclosing the underlying endpoint and the response envelope shape ({ valid, data:{...} }), which matters because no output schema exists. It does not cover failure modes for an unknown id, keeping it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with the purpose front-loaded and nothing padded. The endpoint sentence is marginal but provides traceability to the upstream API; the whole definition can be read in a couple of seconds.
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 this covers the essentials: what it fetches, the key, and the return envelope despite there being no output schema. Missing only failure behavior (e.g., response when the id does not resolve), which keeps it from top marks.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'id' parameter is already documented as a Mongo-style hex string in the schema. The description only restates 'by id' and adds no format, constraint, or example beyond that, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch a single article by id'), and the word 'single' implicitly separates it from the list_articles siblings. It stops short of naming an alternative explicitly, so the 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?
Usage is only implied: an agent can reason that this is the by-id lookup rather than a listing call. There is no explicit when-to-use / when-not-to-use guidance, no mention of error behavior for a missing id, and no pointer to list_articles or list_article_revisions as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single category by id. KnowledgeOwl API: GET /category/{id}.json.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The category id (a Mongo-style hex string). |
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 concrete API route (GET /category/{id}.json), which is mild context, but says nothing about 404 behavior or response shape; with no output schema, a bit more disclosure would have helped.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action; the API route line is mildly redundant with the name but harmless and quick to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with full schema coverage and a readOnlyHint annotation, this is essentially complete. Only error behavior remains unaddressed, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the id parameter is documented as a Mongo-style hex string, so the schema carries the load. The description adds no format or constraint detail beyond restating that the lookup is by id – baseline 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?
States a specific verb and resource ("Fetch a single category by id") plus the underlying endpoint, so the agent knows exactly what it returns. The 'single' vs the sibling knowledgeowl_list_categories is implicit rather than called out, so it stops just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by "by id" and the get-vs-list sibling naming, but the description never explicitly says when to use this instead of knowledgeowl_list_categories or knowledgeowl_update_category, nor what happens with an unknown id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single reader by id. KnowledgeOwl API: GET /reader/{id}.json.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The reader id (a Mongo-style hex string). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe non-mutating read, so the description's burden is lower; it adds the underlying REST mapping, which helps agents correlate with API docs. It does not disclose what happens on an unknown id (404 vs empty) or any auth/rate-limit behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the core action front-loaded ahead of the endpoint reference. 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 one-parameter lookup with no output schema, the description never indicates what a reader object contains or how a missing id is reported, which are the remaining things an agent needs. Acceptable but thin given there is no output schema to fall back on.
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 sole parameter is documented as "The reader id (a Mongo-style hex string)," so the schema already carries the semantics. The description only restates "by id" and adds no format, validation, or sourcing guidance beyond it — baseline 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?
States a specific verb and resource ("Fetch a single reader by id") and pins the exact endpoint (GET /reader/{id}.json). The word "single" implicitly separates it from knowledgeowl_list_readers, but that sibling is never named, so the differentiation is only inferable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the required id parameter signals "call this when you already have a reader id," and by omission an agent would guess list_readers is the way to discover ids. There is no explicit when-to-use, when-not-to-use, or alternative routing statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List article revision history (read-only audit trail). KnowledgeOwl API: GET /articlerevision.json. Returns { valid, page_stats, data:[...] }.
| Name | Required | Description | Default |
|---|---|---|---|
| _page | No | KnowledgeOwl pagination page number, 1-based. | |
| params | No | Additional documented query-string filters/operators to send verbatim (merged with the typed params above). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, but the description adds real value beyond them: the underlying endpoint (GET /articlerevision.json) and the response envelope { valid, page_stats, data }. It omits pagination behavior beyond the _page parameter, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences with no filler. Purpose comes first, then the API detail, then the return shape.
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 supplies the return envelope, and the parameters are covered by the schema. The one missing piece is disambiguation from the near-identical list_article_versions sibling.
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 _page and the passthrough params object are already documented in the schema. The description adds no parameter-level detail, which is acceptable at this coverage level but earns only the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("List article revision history") plus a clarifying parenthetical ("read-only audit trail"). It is clear what the tool does, but it never distinguishes itself from the sibling knowledgeowl_list_article_versions, a closely related and easily confused tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives. Given the sibling list_article_versions exists, the absence of any routing guidance is a meaningful gap; the only hint is the implied "audit trail" framing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List knowledge-base articles. KnowledgeOwl API: GET /article.json. Optionally filter by project_id (the knowledge base). Returns the list envelope { valid, page_stats, data:[...] }.
| Name | Required | Description | Default |
|---|---|---|---|
| _page | No | KnowledgeOwl pagination page number, 1-based. | |
| params | No | Additional documented query-string filters/operators to send verbatim (merged with the typed params above). | |
| project_id | No | Filter to a single knowledge base (project) id. |
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 useful behavioral context: the HTTP endpoint, optional project filtering, and the return envelope shape { valid, page_stats, data:[...] }. It does not cover pagination behavior, auth requirements, or rate limits, but with annotations present the added context is meaningful.
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 compact sentences and front-loads the primary purpose. The API endpoint and return envelope notes are useful, though slightly technical for a purely informational definition; still, every sentence contributes.
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 100% schema coverage and annotations declaring readOnlyHint, the description provides enough context, including the return envelope shape. No output schema exists, but the description mentions the envelope; pagination is left to the schema, which is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents _page, params, and project_id. The description reinforces project_id as a filter to a single knowledge base but adds no format or syntax detail beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List knowledge-base articles', and identifies the backing API endpoint GET /article.json. It is clearly distinct from knowledgeowl_get_article by being a list operation, though it does not explicitly name sibling alternatives or scope boundaries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by saying it lists articles and can optionally filter by project_id. However, it does not state when to use this versus knowledgeowl_get_article or other list_* tools, nor does it mention exclusions or conditions beyond the optional project filter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List article versions. KnowledgeOwl API: GET /articleversion.json. Returns { valid, page_stats, data:[...] }.
| Name | Required | Description | Default |
|---|---|---|---|
| _page | No | KnowledgeOwl pagination page number, 1-based. | |
| params | No | Additional documented query-string filters/operators to send verbatim (merged with the typed params above). |
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. The description adds the API endpoint and response envelope, which is useful, but it does not discuss pagination behavior or other operational details.
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 sentences, front-loaded with the action, and every sentence adds useful information: operation, endpoint, and return shape. 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 read-only list tool with fully described parameters and a readOnlyHint, the description is largely complete: it names the endpoint and return envelope. It could be stronger by clarifying its relationship to knowledgeowl_list_article_revisions or pagination behavior, but no critical information 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%, and the schema already documents the _page and params fields. The description adds no parameter-specific semantics beyond the schema, 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?
The description states a specific verb and resource: 'List article versions.' This is clear enough for an agent to know the operation, but it does not distinguish this tool from the sibling knowledgeowl_list_article_revisions.
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 such as knowledgeowl_list_article_revisions or knowledgeowl_list_articles. Usage is only implied by the tool name and endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List authors/agents (the team members who write and manage content). KnowledgeOwl API: GET /agent.json. Returns { valid, page_stats, data:[...] }.
| Name | Required | Description | Default |
|---|---|---|---|
| _page | No | KnowledgeOwl pagination page number, 1-based. | |
| params | No | Additional documented query-string filters/operators to send verbatim (merged with the typed params above). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already covers the safety profile, but the description adds the concrete endpoint and the response envelope { valid, page_stats, data:[...] }, which is genuinely useful since no output schema exists. It stops short of describing pagination behavior or default page size.
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 clauses: what it lists, the disambiguating definition, and the endpoint/return shape. Front-loaded and zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, non-required read tool with no output schema, the description supplies the resource definition, endpoint, and return envelope. Only pagination mechanics (default page, total counts) are left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both _page and params are already documented in the schema; baseline 3 applies. The mention of page_stats hints at pagination but the description adds no format or filtering semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('List authors/agents') and disambiguates the resource with a parenthetical ('the team members who write and manage content'), which separates it from knowledgeowl_list_readers without naming the sibling. The endpoint (GET /agent.json) further pins down the resource, though no explicit sibling routing is given.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the name and the parenthetical definition; there is no statement of when to use this versus list_readers or when-not to use it. Adequate for a straightforward read-only list, but no explicit guidance is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List categories (the article tree/table of contents). KnowledgeOwl API: GET /category.json. Optionally filter by project_id. Returns { valid, page_stats, data:[...] }.
| Name | Required | Description | Default |
|---|---|---|---|
| _page | No | KnowledgeOwl pagination page number, 1-based. | |
| params | No | Additional documented query-string filters/operators to send verbatim (merged with the typed params above). | |
| project_id | No | Filter to a single knowledge base (project) id. |
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 real value by disclosing the return envelope shape { valid, page_stats, data:[...] }, which matters since no output schema exists. It does not explain pagination traversal or what page_stats contains, which keeps it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short clauses, front-loaded with the verb and the disambiguating definition, followed by the endpoint and return shape. Nothing is repeated and no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-param, read-only list tool with no output schema, the description covers purpose, the optional filter, and the response envelope, which is most of what an agent needs. It stops short of describing pagination behavior across _page values or what the nested params object is for.
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 baseline of 3 applies. The description restates the project_id filter but adds no format, default, or interaction detail for the nested 'params' escape hatch or paging.
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 categories') and immediately disambiguates what a category is with '(the article tree/table of contents)', which separates it from sibling list_articles. It even names the underlying endpoint (GET /category.json), leaving no ambiguity about 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?
The description implies usage by noting the optional project_id filter, which gives the agent a hint about scoping. However, it never says when to use this versus knowledgeowl_get_category for a single category, or versus knowledgeowl_list_articles, so the routing guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List reader comments / feedback on articles. KnowledgeOwl API: GET /comment.json. Returns { valid, page_stats, data:[...] }.
| Name | Required | Description | Default |
|---|---|---|---|
| _page | No | KnowledgeOwl pagination page number, 1-based. | |
| params | No | Additional documented query-string filters/operators to send verbatim (merged with the typed params above). |
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 disclosing the GET endpoint and return envelope ({ valid, page_stats, data:[...] }), but it does not discuss authentication, rate limits, or pagination 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, front-loaded with purpose, followed by endpoint and return shape. There is no filler and every sentence adds 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?
Given the simple read-only list operation, fully documented schema, and readOnlyHint annotation, the description covers purpose, endpoint, and return shape adequately. It omits filtering and pagination guidance, but the schema already documents those parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so _page and params are fully documented in the schema. The description adds no parameter semantics beyond what the schema already provides, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('reader comments / feedback on articles'), plus the underlying API endpoint. It distinguishes this from sibling list tools by naming comments/feedback rather than articles, suggestions, or 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?
No explicit when-to-use or when-not-to-use guidance is provided, and no alternative tool is named. The purpose implies it lists comments, but an agent gets no routing criteria beyond the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files in the file library (images/attachments). KnowledgeOwl API: GET /file.json. Returns { valid, page_stats, data:[...] }.
| Name | Required | Description | Default |
|---|---|---|---|
| _page | No | KnowledgeOwl pagination page number, 1-based. | |
| params | No | Additional documented query-string filters/operators to send verbatim (merged with the typed params above). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already declares the safety profile, so the bar is lower. The description adds some value by disclosing the HTTP endpoint and the response envelope shape ({ valid, page_stats, data }), but says nothing about pagination behavior, result size, or how the verbatim `params` filters are interpreted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with purpose before the implementation and return-shape details. No filler, though the endpoint reference earns its place mostly for debugging rather than for tool selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by summarizing the return envelope, and the nested `params` object is covered by the schema. Missing only guidance on pagination semantics and the fact that listing can be narrowed via verbatim query filters.
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 `_page` and `params` are already documented in the schema; baseline 3 applies. The description does not add filter examples or syntax hints for the free-form `params` escape hatch, which would have been the one place description-level detail was warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ("List files in the file library") and disambiguates the resource with "(images/attachments)", which no sibling list_* tool covers. The endpoint reference and return envelope make the operation unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the resource name — you call it to browse files — but there is no explicit when-to-use guidance, no statement about when to prefer a typed filter path over the generic knowledgeowl_request sibling, and no prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List glossary terms and definitions. KnowledgeOwl API: GET /glossaryterm.json. Returns { valid, page_stats, data:[...] }.
| Name | Required | Description | Default |
|---|---|---|---|
| _page | No | KnowledgeOwl pagination page number, 1-based. | |
| params | No | Additional documented query-string filters/operators to send verbatim (merged with the typed params above). |
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 underlying endpoint and the response envelope ({ valid, page_stats, data }), which is genuinely useful behavioral context. It stops short of describing pagination semantics, max page size, or whether the list is complete or truncated.
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, front-loaded sentences with zero filler: purpose first, endpoint second, return shape third. Nothing repeats the title or wastes space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by naming the envelope fields, and the schema fully covers inputs. What is missing is pagination guidance (ties to page_stats) and a note on the nested params merge behavior, but for a simple read-only list tool this is close to sufficient.
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 both parameters are documented in-schema, so the baseline of 3 applies. The description mentions the response's page_stats but says nothing about _page or how the free-form params object is merged with typed params.
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 glossary terms and definitions') and pins it to the KnowledgeOwl endpoint GET /glossaryterm.json, which unambiguously distinguishes reading terms from create_glossary_term. It does not, however, contrast itself with siblings like list_synonyms or a hypothetical get_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?
There is no guidance on when to call this versus knowledgeowl_create_glossary_term or other list tools, and no mention of prerequisites or when the result set would be better served by a filtered request. Usage is only implied by the verb 'List'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List readers (knowledge-base end users / audience accounts). KnowledgeOwl API: GET /reader.json. Returns { valid, page_stats, data:[...] }.
| Name | Required | Description | Default |
|---|---|---|---|
| _page | No | KnowledgeOwl pagination page number, 1-based. | |
| params | No | Additional documented query-string filters/operators to send verbatim (merged with the typed params above). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read. The description adds real value by disclosing the response envelope ({ valid, page_stats, data:[...] }) in the absence of an output schema, but it says nothing about default page size, whether all readers are returned or only the first page, or any auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the purpose; the parenthetical gloss and the return shape both earn their place. The endpoint reference is the least useful fragment but takes almost no space.
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 fully documented parameters and no output schema, the description covers purpose, endpoint, and return shape. Remaining gaps are pagination behavior and total-count semantics, which are minor for this tool class.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both _page and the free-form params object are documented in the schema itself. The description does not add pagination conventions or examples of valid params keys, so it neither helps nor hurts beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List readers') and disambiguates the term with 'knowledge-base end users / audience accounts', which usefully separates it from sibling list tools like list_authors or list_comments. It also names the underlying endpoint, but does not explicitly contrast with knowledgeowl_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?
The word 'List' implies bulk retrieval and the get_reader sibling implies a single-record alternative, but the description never says when to use this versus get_reader or how it relates to the other list endpoints. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List reusable content snippets. KnowledgeOwl API: GET /snippet.json. Returns { valid, page_stats, data:[...] }.
| Name | Required | Description | Default |
|---|---|---|---|
| _page | No | KnowledgeOwl pagination page number, 1-based. | |
| params | No | Additional documented query-string filters/operators to send verbatim (merged with the typed params above). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is covered. The description adds value beyond that by naming the underlying endpoint (GET /snippet.json) and disclosing the response envelope { valid, page_stats, data:[...] }, which is meaningful since no output schema exists. It stops short of describing 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?
Three short sentences with zero waste: purpose first, endpoint second, return shape third. Nothing is repeated from structured fields and 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 two-parameter read-only list tool with no output schema, the definition covers purpose, endpoint, and response envelope. The only omission is how the free-form params object is practically used for filtering, which the schema gestures at but does not exemplify.
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 _page and the free-form params object are already documented. The description adds nothing about filter syntax or which query-string operators are valid, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ('List') plus resource ('reusable content snippets'), which an agent can distinguish from sibling list tools such as knowledgeowl_list_articles or knowledgeowl_list_glossary_terms. No explicit sibling differentiation is offered, but the resource noun does the disambiguating work.
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 verb: call this to enumerate snippets. There is no statement of when to prefer it over other enumeration tools, no mention of filter use cases, and no prerequisites, but the intent is unambiguous for a simple list operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List search suggestions / reader search analytics (what readers searched for). KnowledgeOwl API: GET /suggest.json. Returns { valid, page_stats, data:[...] }.
| Name | Required | Description | Default |
|---|---|---|---|
| _page | No | KnowledgeOwl pagination page number, 1-based. | |
| params | No | Additional documented query-string filters/operators to send verbatim (merged with the typed params above). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add beyond that. It does add the underlying endpoint (GET /suggest.json) and the response envelope { valid, page_stats, data:[...] }, which is useful. It says nothing about pagination limits, result ordering, or retention window, so it remains adequate rather than rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact fragments, front-loaded with the purpose and the clarifying gloss before the endpoint and return shape. Nothing is wasted; the slight terseness of the '/' separated clauses costs a little readability but not correctness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description compensates by sketching the return envelope, which is the main thing an agent would otherwise lack. For a read-only, zero-required-parameter list tool with a nested passthrough object, that is close to sufficient; only the shape of individual suggestion records and pagination behavior are left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (_page and the passthrough params object) are already documented and the baseline is 3. The description adds nothing about which query-string filters are accepted in params, which is the one place the schema cannot help, so no credit above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List search suggestions') and disambiguates with 'reader search analytics (what readers searched for)', which is genuinely clarifying since 'suggestions' could be misread as synonym/term suggestions. It does not explicitly contrast with the closest sibling (knowledgeowl_list_synonyms), 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 exclusions, and no mention of alternatives such as knowledgeowl_list_synonyms or the generic knowledgeowl_request escape hatch. The agent must infer from the name alone that this is the analytics-listing call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List search synonyms (terms treated as equivalent by search). KnowledgeOwl API: GET /synonym.json. Returns { valid, page_stats, data:[...] }.
| Name | Required | Description | Default |
|---|---|---|---|
| _page | No | KnowledgeOwl pagination page number, 1-based. | |
| params | No | Additional documented query-string filters/operators to send verbatim (merged with the typed params above). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered, but the description adds value by disclosing the return envelope ({ valid, page_stats, data:[...] }) even though no output schema exists, and by noting the underlying endpoint. It stops short of describing pagination behavior, default ordering, or auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short fragments, front-loaded with the core purpose and with zero filler language. The raw endpoint reference is only marginally useful to an MCP caller, but it costs a single short clause and can aid fallback to knowledgeowl_request.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-parameter list tool with full schema coverage, the description supplies purpose, return shape, and endpoint, which is nearly everything needed. Gaps are minor: default result count, sort order, and how page_stats relates to _page are not explained.
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 both documented inline, so the schema carries the parameter burden. The description only indirectly gestures at pagination via page_stats and adds no syntax or filtering detail beyond what the schema already says, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("List search synonyms") plus a parenthetical definition clarifying that these are terms treated as equivalent by search, which separates it conceptually from glossary terms or tags. It does not explicitly name a sibling it differs from, but the resource is distinct enough among the listed tools to be unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit statement of when to use this versus knowledgeowl_list_glossary_terms or the generic knowledgeowl_request escape hatch. Usage is implied by the resource name and the definition of synonyms, which is enough to infer the purpose but leaves the agent to decide relevance on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List article tags. KnowledgeOwl API: GET /tag.json. Returns { valid, page_stats, data:[...] }.
| Name | Required | Description | Default |
|---|---|---|---|
| _page | No | KnowledgeOwl pagination page number, 1-based. | |
| params | No | Additional documented query-string filters/operators to send verbatim (merged with the typed params above). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the safety profile, so the bar is lower, and the description adds real value by disclosing the response envelope ({ valid, page_stats, data:[...] }) that no output schema provides. It stops short of describing pagination semantics or how page_stats relates to the _page parameter, which would have made it 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 terse statements, front-loaded with the purpose before endpoint and return shape. The endpoint reference is slightly redundant for an agent that never calls the API directly, but it costs almost nothing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-parameter read-only list tool with full schema coverage, the description supplies everything essential plus a return-shape sketch. Only pagination behavior and the nature of tag records are left implicit, which are minor for this complexity level.
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 _page and the free-form params object are already documented; baseline 3 applies. The description adds nothing about accepted filter names or how params merges with typed params, so it neither compensates nor detracts.
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 article tags") and pins it to the concrete endpoint GET /tag.json, so there's no ambiguity about what the tool returns. It doesn't name a sibling that would be the wrong choice (e.g., knowledgeowl_request for ad-hoc queries), but the purpose itself is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use or when-not-to-use guidance. With a generic sibling like knowledgeowl_request available, an agent gets no signal about when this typed lister is preferable to a raw request, nor any prerequisite or filtering-context advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List configured webhooks. KnowledgeOwl API: GET /webhook.json. Returns { valid, page_stats, data:[...] }.
| Name | Required | Description | Default |
|---|---|---|---|
| _page | No | KnowledgeOwl pagination page number, 1-based. | |
| params | No | Additional documented query-string filters/operators to send verbatim (merged with the typed params above). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations supply readOnlyHint=true, so the safety profile is already covered; the description adds genuine value beyond that by naming the underlying endpoint (GET /webhook.json) and the response envelope shape { valid, page_stats, data }. It omits auth requirements and pagination semantics (whether page_stats implies finite paging), keeping it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three terse sentences with zero filler: purpose, endpoint, return shape, in that order. Nothing is redundant or buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully supplies the return envelope, and the readOnly annotation covers safety. What's missing for full completeness is auth/permission context and whether the free-form params object supports pagination cursors beyond _page.
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, which sets the baseline at 3. The description mentions page_stats in the return value but adds no filter/operator syntax guidance for the free-form 'params' object, so it does not exceed the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List configured webhooks'), which is unambiguous and distinct from all listed siblings — none of them deal with webhooks. It does not, however, distinguish itself from the generic knowledgeowl_request escape hatch, 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 explicit guidance on when to use this versus knowledgeowl_request, nor any prerequisites (auth scope, whether webhooks must be enabled). Usage is only implied by the verb 'List'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Power-user escape hatch: GET any KnowledgeOwl API path not wrapped by a dedicated tool. READ-ONLY — only GET is allowed. Pass the FULL API path after the base, starting with a slash, INCLUDING any query string, e.g. "/article.json?_page=2" or "/category/abc123.json". Returns the parsed JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Full API path after the base, starting with "/", e.g. "/article.json?_page=2". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, but the description adds real value beyond them: it narrows the constraint to 'only GET is allowed' and states the return shape ('parsed JSON'). It does not mention auth requirements, error behavior on a bad path, or pagination semantics, which is the remaining gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four compact sentences, front-loaded with the escape-hatch framing and the read-only constraint, each carrying distinct information (scope, restriction, format rule, return type). 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 single-parameter passthrough tool with no output schema, the description covers the essentials: what it does, the read-only limit, how to format the path, and that it returns parsed JSON. It omits error/edge-case behavior for invalid paths, which keeps it short of 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% and the schema already documents the path parameter, so baseline would be 3. The description adds genuinely useful meaning by clarifying that the caller must include the leading slash and the query string in the same argument, with concrete examples ('/article.json?_page=2').
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), and explicitly positions itself against the sibling tools that wrap common paths. An agent can immediately tell this is the generic fallback rather than a dedicated read tool.
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 'not wrapped by a dedicated tool' effectively tells the agent to prefer the sibling tools and reach for this only as a fallback, and 'READ-ONLY — only GET is allowed' rules out write usage. It stops short of naming a specific sibling or spelling out an explicit preference order, so it is clear but not fully prescriptive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
MUTATES KnowledgeOwl data: updates an existing article. KnowledgeOwl API: PUT /article/{id}.json (JSON — only included fields change). Use the fields passthrough for current_version (title/body) and any other documented field. The path id is never sent in the body.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The article id to update (path only; required). | |
| name | No | New article name/title. | |
| fields | No | Additional documented KnowledgeOwl fields to send in the JSON write body (e.g. current_version, body) — merged OVER the typed fields above. | |
| status | No | New publishing status. | |
| url_hash | No | New URL slug. | |
| visibility | No | New visibility. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, and the description reinforces this with 'MUTATES' and PUT semantics. It adds useful behavioral detail beyond annotations: partial-update behavior, JSON body handling, and that the path id is not sent in the body.
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-loads the mutation warning and resource. Every sentence carries operational information without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with a nested `fields` object and no output schema, the description covers endpoint, update semantics, partial writes, and path-id handling. It leaves out response/error behavior and auth requirements, but the schema and destructive annotation already carry much of the remaining context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so a baseline of 3 would be acceptable, but the description adds meaningful guidance about `fields` as a passthrough for current_version/body and about `id` being path-only. It clarifies how nested `fields` values are used beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: it updates an existing KnowledgeOwl article. It also names the API endpoint, which makes its purpose distinct from create, get, list, and update_category siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly explains that only included fields are changed and directs agents to use the `fields` passthrough for current_version and other documented fields. It does not explicitly exclude alternate update paths or describe when to prefer another sibling, but the usage context is otherwise clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
MUTATES KnowledgeOwl data: updates an existing category. KnowledgeOwl API: PUT /category/{id}.json (JSON — only included fields change). Use the fields passthrough for any other documented field. The path id is never sent in the body.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The category id to update (path only; required). | |
| name | No | New category name. | |
| fields | No | Additional documented KnowledgeOwl fields to send in the JSON write body (e.g. current_version, body) — merged OVER the typed fields above. | |
| status | No | New publishing status. | |
| url_hash | No | New URL slug. | |
| visibility | No | New visibility. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only carry destructiveHint=true, so the description does the heavy lifting: it declares mutation, discloses partial-update semantics (omitted fields are untouched), and states that `fields` entries are merged OVER the typed fields. It does not cover permissions, reversibility, or error behavior on a bad id, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, mutation warning front-loaded, followed by endpoint and then the two non-obvious mechanics (partial update, id not in body). 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 6-parameter destructive mutation with a nested `fields` passthrough and no output schema, the description covers the mechanics an agent most needs: partial update, merge order, and id handling. It is silent on failure modes (nonexistent id, validation errors) and what the call returns, which are the 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 each parameter is already documented. The description adds one genuinely new detail — that the path id is never sent in the body — but the merge-precedence note for `fields` merely repeats the schema text, so it is roughly at the high-coverage baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (updates) and resource (existing category), and explicitly flags it as a mutation of KnowledgeOwl data. The 'existing' qualifier plus the PUT endpoint make it clearly distinct from sibling knowledgeowl_create_category and knowledgeowl_update_article.
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 partial-update usage ('only included fields change') and tells the agent to route undocumented fields through `fields`, which is real usage guidance. However, it never states when to use this versus knowledgeowl_create_category or knowledgeowl_get_category, nor any prerequisites such as the category needing to exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read tickets, contacts, companies, agents and groups; create, update and reply to tickets.
Read tickets, users, orgs, macros and satisfaction ratings; create, update and comment on tickets.
Read spaces, collections, pages and content; search docs and manage GitBook organization spaces.
Write, edit, translate and publish blog and help-center articles across all your sites.
Add one secure layer between your agents and this server.
