brainattic

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

Annotations declare readOnly=false, idempotent=true and destructive=false, and the description goes beyond that by characterizing the write as 'soft' (a timestamp, not a deletion) and explicitly reversible. That is exactly the extra context an agent needs before mutating state; it only stops short of saying whether archived attachments are hidden from lists or how tenant_slug failures resolve.

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 semantics and the escape hatch both front-loaded. Every clause carries information.

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

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

An output schema exists so return values need not be described, and the schema fully documents the two parameters. Combined with the soft/reversible disclosure this is nearly complete; only the observable side effect (visibility in list/get) is 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% and both parameters carry detailed descriptions, including the multi-workspace behaviour of tenant_slug and where attachment_uuid comes from. The description adds no parameter meaning of its own, 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+resource ('Soft-archive an attachment') plus the concrete mechanism ('sets archived_at'), which distinguishes it from the sibling kb_attachments_restore by naming the exact opposite operation. An agent can pick the right one without opening the schema.

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

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

It points to kb_attachments_restore as the reversal path, which is useful routing, but it never states when archiving is the appropriate choice over leaving an attachment alone or what state archived attachments appear in (e.g. whether kb_attachments_list still returns them). Usage is implied rather than instructed.

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

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

Goes well beyond the annotations: discloses that the capability is short-lived (five minutes), single-use, that the returned size limit is authoritative, and gives a security constraint (never put the token in a path, query, argument, or log). It also clarifies the fragment-vs-server subtlety, which no annotation or schema field conveys.

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?

Dense and front-loaded, leading with the purpose before the protocol. The multiple imperative clauses about the token and multipart envelope are slightly repetitive, but each carries operational weight and none 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?

Despite an output schema existing, the description still explains the meaningful shape of the result (upload_url with #token fragment, authoritative size limit), which an agent needs to act correctly. It covers authentication, idempotency, expiry, and the non-multipart wire format — nothing needed to invoke correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters including the conditional tenant_slug behavior. The description only restates that document_id and filename are required and expected_sha256 optional, adding essentially no semantic detail beyond the structured 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?

States a specific verb+resource (begin a direct attachment upload) and adds a scope qualifier — 'for a client that can transfer local file bytes' — which implicitly separates it from siblings like kb_attachments_upload and kb_attachments_import_url. It does not name those siblings outright, so an agent must infer the routing, but the core purpose is unambiguous.

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

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

The qualifier 'for a client that can transfer local file bytes' gives a clear selection condition and the description spells out the full follow-up procedure (extract fragment token, POST raw bytes). It stops short of explicitly naming the alternative tool for clients that cannot transfer bytes, leaving that inference to the agent.

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, idempotentHint=true and destructiveHint=false, so safety is covered; the description adds genuinely new behavioral context by noting the download URL is short-lived and separately minted. It does not cover pagination or error behavior, but for a single-item read that is minor.

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

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

Two sentences, front-loaded with what the tool returns, followed by the one optional behavior that changes the call. 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?

An output schema exists, so return values need not be explained. Purpose, the optional URL behavior, and the embedding use case are all covered, which is everything an agent needs to call this single-record read 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 baseline is 3, but the description adds meaning the schema lacks: the kb-attachment://<uuid> embedding convention that explains why the uuid matters. That is useful semantic context rather than a restatement.

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 ('Retrieve attachment metadata') scoped to a single attachment, which separates it from kb_attachments_list without needing to open either schema. The added detail about attachment_uuid being the embedding handle makes the output's purpose concrete.

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

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

Explicitly gives the condition for include_download_url=true ('when you will download the bytes') and redirects to attachment_uuid for embedding. It doesn't compare itself to sibling tools like kb_attachments_list or kb_attachments_view_image, so it stops short of full when/when-not/alternatives coverage.

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

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

Even though annotations already set openWorldHint=true and destructiveHint=false, the description adds substantial behavioral context: the server uses a bounded transfer, validates the bytes, refuses on checksum mismatch without returning a hash, does not retain temporary source URLs or provider file IDs, and that active attachments persist until explicitly archived.

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 dense but front-loaded: the action comes first, then the critical do-not rules, then fallback guidance, optional integrity behavior, return format, and lifecycle. Every sentence adds decision-relevant information with no repetition of schema or annotations.

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 an output schema, this description covers what the agent must know: required host inputs, fallback path, checksum behavior, return value, how to embed the result, and persistence semantics until archive. Nothing essential 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 already 100%, so the baseline would be 3, but the description adds value by explaining expected_sha256 as an independent integrity check with no returned hash, include_download_url as a short-lived (~5 minute) capability, and the filename override requirement. It doesn't explicitly address tenant_slug or document_id beyond what the schema says.

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

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

The first sentence states a precise verb and resource: save the actual bytes of a host-provided file reference as a downloadable document attachment. It also implicitly separates this tool from siblings that handle uploads or plain URLs by specifying that the server itself fetches the host file object's HTTPS URL.

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

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

The description gives clear when-to-use and when-not-to-use guidance: never invent a URL, never substitute a description for the file, and use kb_attachments_begin_upload when the client already has local bytes. It does not explicitly distinguish the very close sibling kb_attachments_import_url, leaving that alternative for the agent to infer.

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 annotations declaring destructiveHint=false and idempotentHint=false, the description still adds real value: redirect validation, bounded transfer, integrity verification before storage, non-mutation of document body/revision, source URL and checksum not retained, and no server-side replay of failed requests. It avoids contradicting the annotations. It doesn't state the deployment size limit value or concrete failure/error surface, 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?

Front-loaded with the core action and the integrity constraint, then the linking recipe, then sibling routing — a sensible order. A few clauses (the 'ordinary string' phrasing, the non-retention note restated from the schema) come close to redundancy, but nothing is filler.

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

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

For a 7-parameter, non-idempotent write tool with an output schema present, the description covers what gets mutated (nothing in the body), what is returned (attachment_uuid), what is discarded (source URL/checksum), and the follow-up needed to actually render the file. No gap an agent would trip over.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by stressing that expected_sha256 must be independently supplied by the source service and never invented, and that expected_size_bytes must match exactly. filename and tenant_slug are left entirely to the schema, so it does not fully exploit the space.

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 (attach) and resource (exact original bytes from a public HTTPS URL to an existing document), and explicitly distinguishes itself from the two nearest siblings by naming them and their input sources. An agent can route between import_url, import, and begin_upload without opening a schema.

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

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

Explicitly names the alternatives and the condition that selects each ('For a chat-host file object use kb_attachments_import; for local bytes use kb_attachments_begin_upload'). It also covers the retry case: a failed one-use source must be replaced with a fresh capability before a deliberate retry.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: default filtering out archived attachments, pagination, and the per-row attachment_uuid with its `kb-attachment://<uuid>` embed syntax.

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

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

Three short sentences, front-loaded with the core purpose, then the default filtering behavior, then the practically important uuid detail. Nothing is redundant.

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

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

An output schema exists, so return values needn't be spelled out, and the description still gives the one return detail that matters operationally (the uuid embed format). For a read-only paginated list the entry is essentially complete; only explicit sibling routing is 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 all five parameters including limit/offset and the tenant_slug fallback rule are already documented in the schema. The description only reinforces the include_archived default; it adds no parameter syntax or format details beyond the structured 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?

States a specific verb and resource ('Paginated list of a document's attachments') with scope immediately clear. Among siblings (kb_attachments_get, archive, restore, list) an agent can pick this one without opening a schema.

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

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

The 'Active (non-archived) only by default' clause implies when this listing is and isn't sufficient, but the description never explicitly names alternatives such as kb_attachments_get for a single item or the archive/restore siblings. Usage is implied rather than stated.

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

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

Annotations already declare non-readonly, idempotent, non-destructive, and closed-world, and the description adds the concrete state change (clears archived_at) that the agent needs to reason about effect. Minor gaps remain, e.g. whether restoring an already-live attachment is a no-op, but the idempotent hint covers that reasonably.

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

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

One sentence, front-loaded with the verb and resource, then the state effect, then the inverse relationship. No filler.

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

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

With an output schema present and a fully documented schema, the description only needs to convey purpose, effect, and the inverse relationship, and it does all three. It could add one clause about failure or no-op behavior when the target is not archived, but that is a small omission.

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 tenant_slug and attachment_uuid are already fully documented, including the archived precondition on the UUID. The description adds no parameter-level detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb (restore) and resource (soft-archived attachment), and even names the mechanism it undoes (clears archived_at). The explicit 'reverse of kb_attachments_archive' distinguishes it cleanly from its sibling.

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 'soft-archived' qualifier and the 'reverse of kb_attachments_archive' pointer give a clear condition for use and route the agent away from the archive sibling. It does not state what to do if the attachment is not archived, so it falls short of full when/when-not guidance.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive, but the description adds substantial context beyond them: the size ceiling, that the web limit is deployment-configured and surfaced in the refusal message, that the server sniffs MIME types, and a lifecycle rule distinguishing swept unreferenced inline uploads from retained downloadable uploads.

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

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

Front-loaded with the verb, the payload constraint and the exclusivity rule before the routing guidance, and every sentence carries actionable content. It is a dense, unbroken paragraph for a tool with this much conditional behavior, which costs some scannability 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?

With an output schema present the description need not enumerate return fields, yet it still tells the agent what the key return value (attachment_uuid) is for and how to embed it. Combined with the size limits, fallback path and retention behavior, an agent has everything needed to call this correctly or route elsewhere.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning the schema cannot express: content_text and content_base64 are mutually exclusive and exactly one is required. It also explains how to use the returned attachment_uuid for embedding and warns that include_download_url mints an unauthenticated capability, which the schema only hints at with a default.

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

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

States a specific verb and resource plus the hard constraint that defines the tool: 'Upload a small file you already hold as text or bytes, up to 64 KiB.' It immediately differentiates itself from kb_attachments_import and kb_attachments_begin_upload by naming both as alternatives for the cases this tool does not cover.

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

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

Gives an explicit selection rule ('Supply exactly one of content_text or content_base64'), names both alternatives with the condition that selects each, and supplies a fallback procedure (permalink, ask user to Attach, then kb_attachments_list) for the residual case. This is a full when/when-not/alternative decision tree.

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

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

Annotations already establish this as a safe, read-only, idempotent call, and the description still contributes real behavior: the 1 MiB native envelope and the automatic URL fallback, the short lifetime of presentation URLs, and the explicit guarantee that MinIO and original bytes are never exposed as a download.

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

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

Front-loaded with the core action, then layered with mode semantics and constraints in three tight sentences. The opening clause and the auto-fallback clause overlap slightly, and the MinIO sentence reads as a defensive aside, but nothing is padded.

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

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

With an output schema and full schema descriptions in place, the description only needs to cover mode behavior and rendering constraints, which it does. The threshold, the fallback trigger, and the non-exposure guarantee are exactly the facts an agent cannot get from structured fields.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds semantic weight by framing 'native' as requiring ImageContent versus 'url' as an explicit request for the presentation capability, which tells the agent these modes can fail differently. tenant_slug semantics are left entirely to the schema.

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

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

States a specific verb and resource ('Present an existing Brainattic image attachment') and clarifies it renders image content rather than metadata. It never names the adjacent kb_attachments_get or kb_attachments_list, so the distinction from those siblings is left to inference.

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

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

Gives concrete selection guidance across the presentation_mode values: auto by default, native to force ImageContent, url to request the Brainattic presentation capability. It stops short of saying when to reach for this tool over kb_attachments_get when the caller wants metadata rather than a rendered image.

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 annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds useful downstream behavior ('flat list ordered by relevance', 'cite the source document for each claim'), but says nothing about result truncation, empty-result behavior, or the tenant-disambiguation refusal path. A solid but not rich supplemental contribution given the annotation coverage.

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

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

Front-loaded with the core purpose, then usage, then the output guidance and sibling routing. Three dense sentences with no filler; only the clause 'the model may not otherwise have access to it' is arguably padding, though it justifies the strong 'call this whenever' instruction.

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

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

With a full output schema and 100% parameter coverage, the description need only supply decision context, which it does. The one gap is the multi-tenant `tenant_slug` refusal flow, which is described in the schema but not signaled in the description, so an agent could hit an avoidable error on a multi-workspace token.

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 every parameter already carries a clear description, so the description rightly avoids duplication. It adds meaning only at the aggregate level (passages as context, relevance ordering), which is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Retrieves relevant passages from the connected private knowledge base') and implicitly distinguishes itself from document-level siblings by emphasizing passages. An agent can immediately tell this is a retrieval/RAG grounding tool rather than a CRUD or browse 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?

Gives an explicit trigger ('whenever a question depends on the organisation's stored knowledge') and names the alternative plus the condition that selects it ('For "show me documents about X" browse-style queries, prefer kb_documents_search'). Both the when and the when-not are present.

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 idempotentHint=true and destructiveHint=false, so the description adds the crucial behavioral fact that this is a soft archive setting archived_at and that it is reversible via restore. It does not discuss permissions or tenant scoping, but the schema handles tenant_slug thoroughly.

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

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

Two short sentences with zero waste. The key behavior is front-loaded and the reversal path is given immediately afterward.

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 archive operation with rich annotations, full schema coverage, and an output schema, the description provides exactly what an agent needs: the soft-archive semantics, the field changed, and the restore path. Nothing essential is missing.

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

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

Schema description coverage is 100%, so document_id, tenant_slug, and include_body are fully documented in the schema. The description adds no parameter-level detail beyond implying that archiving affects archived_at rather than the document body.

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 the specific verb and resource ('Soft-archive a document') and immediately clarifies the mechanism ('sets archived_at'). This distinguishes it from sibling kb_documents_delete and points to kb_documents_restore for reversal.

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 is the reversible archive path and names kb_documents_restore as the alternative for undoing it. It does not explicitly contrast with kb_documents_delete, but the 'soft' framing implies the distinction.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent behavior, so the description only needs to add context. It does: project_slug must exist (a failure mode) and group_slugs are created on demand (a side effect that creates group records beyond the document itself) — genuinely useful disclosure not present in 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?

Three short sentences, front-loaded with the action and then the two constraints that most affect a successful call. No filler and nothing 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 an output schema present, return values need no explanation, and the rich schema covers the 8 parameters. The remaining gap is duplicate-slug conflict behavior — given idempotentHint=false, the description should say whether creating with an existing slug fails or overwrites.

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 and the schema already documents tenant_slug, include_body, and document_date in detail. The description still adds referential semantics the schema omits: project_slug must pre-exist and group_slugs are auto-created, though its slug auto-generation note only repeats the schema.

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

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

States a specific verb and resource ('Create a new document') that clearly separates it from kb_documents_update, kb_documents_get, and kb_documents_list. It does not explicitly name or contrast with the edit_begin/edit_commit drafting flow, but the purpose itself 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?

Usage is implied by the verb 'Create' plus the note that project_slug must already exist, which tells the agent a prerequisite call (kb_projects_list/create) may be needed. There is no explicit guidance on when to use this versus the kb_documents_edit_begin/apply/commit flow for authoring content.

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

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

Adds real context beyond the annotations: the deletion cascades to all revisions and requires admin privileges. Annotations already cover destructiveHint and idempotentHint, so the description's contribution is the blast radius and auth requirement, which are the most decision-relevant facts here.

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

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

Three short sentences, front-loaded with the permanent/cascading nature, then precondition, then the safer alternative. 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?

Output schema exists so return values need not be explained, and the description covers destruction scope, auth, and reversibility. Only the fallback to a sibling archive tool is 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%, and the tenant_slug description already explains the multi-workspace omission rule in detail. The description adds nothing about document_id or tenant_slug beyond what the schema states, 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 ('Permanently delete a document and all its revisions'), including the cascade scope that distinguishes it from a plain document delete. An agent can immediately separate this from kb_documents_archive.

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

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

Gives a clear when-not path ('archive first if in doubt') and a precondition ('Admin-only'), which routes the agent away from this tool in ambiguous cases. It stops short of naming kb_documents_archive explicitly or describing confirmation/idempotency expectations, so it is strong but not exhaustive.

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

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

Goes well beyond the annotations by disclosing the atomic rejection contract and its four failure causes (no match / ambiguous / overlapping / out of range) plus the guarantee that the buffer is unchanged on failure. It also documents the return value (cumulative base→working unified diff). Minor gap: it never states that acceptance means staged-only, with commit as the persistence step — the key non-idempotent, non-destructive behavior an agent must know.

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 atomicity guarantee is correctly front-loaded and every clause is substantive. The edit-type enumeration partially duplicates the 100%-covered oneOf schema; trimming it to the non-obvious constraints (uniqueness, disambiguation, content ignored on delete_section) would tighten it without losing 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?

An output schema exists so return format needn't be re-explained, and annotations cover the safety profile; the description fills the remaining gap with the failure/rejection model. What's absent is the surrounding session lifecycle — that nothing is persisted until edit_commit and that edit_discard throws the buffer away — which matters for a non-idempotent, non-read-only mutation tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description earns more by explaining how the edit variants behave in combination (ordering, uniqueness of old_string, disambiguation via level/parent, empty array semantics). It does not mention the `diff` enum (full/none/delta) or tenant_slug at all, leaving those entirely to the schema.

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

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

Opens with a specific verb + resource ("Apply an ordered batch of edits to an open edit session") and immediately names the defining property (all-or-nothing). An agent can distinguish it from kb_documents_edit_commit / edit_discard / edit_begin without opening a schema, since it's clearly the staging-mutation step of a session workflow.

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?

States the prerequisite implicitly ("an open edit session") and gives a non-obvious usage mode (empty edits array = diff refresh only). It does not explicitly say the changes are not persisted until kb_documents_edit_commit is called, which is the single most important routing decision among the edit_* siblings.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, and the description adds real context beyond them: a revision snapshot is taken, and re-invoking resumes the existing session with resumed=true (which explains the idempotent hint). It omits session lifetime/concurrency behavior, e.g. whether an open session blocks other writers.

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

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

Three sentences, front-loaded with the action, then the workflow chain, then the resume edge case. No repetition of the title, no filler.

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

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

With annotations covering safety and an output schema covering returns, the description supplies the workflow and resume semantics an agent needs to call this correctly. Gaps are minor: session lifetime and how this relates to kb_documents_update.

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 document_id, tenant_slug and include_body are all documented in the schema; the description adds no parameter-level detail beyond the notion of a snapshot. Baseline 3 applies where the schema carries the semantics.

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

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

States a specific verb and resource ("Open a surgical edit session on a document") plus the side effect ("snapshot its current revision"). It immediately names the follow-on siblings (edit_apply, edit_commit, edit_discard), so an agent can place it in the workflow without opening other schemas.

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

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

Gives a clear usage sequence: begin, stage with kb_documents_edit_apply, then commit or discard, and explains the re-call/resume case. It does not explain when to choose this session workflow over the direct kb_documents_update sibling, which is the main remaining ambiguity.

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 idempotent, non-destructive, readOnly=false, and the description adds rich behavior beyond them: what is preserved (title/project/groups), the staleness contract (kb.documents.stale_revision, session kept open), and the no_changes short-circuit. This is exactly the mutation context an agent needs.

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

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

Front-loaded with the action, then the success shape, then the two failure/edge behaviors. Dense but every clause carries decision-relevant 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?

With an output schema present and 100% schema coverage, the description supplies the remaining operational contract — preservation semantics, stale-revision handling, no_changes — leaving no ambiguity about how to invoke or interpret the commit.

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 session_id, tenant_slug, and include_body are already documented in the schema. The description adds no parameter-level detail (e.g., how include_body interacts with the commit), which is fine given the schema baseline but not above it.

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

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

States a specific verb+resource ('Commit an open edit session') and the concrete effect ('flush its working buffer to a single new revision'), which cleanly separates it from sibling session tools like kb_documents_edit_apply, _discard, and _rebase.

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

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

Clearly establishes the context (after an edit session is open) and enumerates the branching outcomes that tell an agent how to proceed — stale revision leaves the session open to rebase or discard, and no_changes means no revision written. It stops short of explicitly naming sibling alternatives for the discard/rebase path, but the conditions are inferable.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the idempotency sentence largely restates structured data. The description does add real value by clarifying that the working buffer is destroyed and no revision results, but it omits permission requirements and what a 'no-op' response looks like.

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

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

Two tight sentences, the destructive outcome front-loaded, the idempotency caveat second. Nothing is wasted 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?

There is an output schema, so return values need no explanation, and annotations carry the safety profile. The one remaining gap for a destructive mutation is the auth/permission prerequisite, which is not mentioned.

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%, including full guidance on when to supply tenant_slug, so the baseline of 3 applies. The description adds no parameter-level detail beyond what the schema already documents.

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 ('Discard an edit session') and immediately scopes the effect ('throw its working buffer away — no revision is written'), which is exactly what distinguishes it from the commit/apply siblings. An agent can tell this apart from kb_documents_edit_commit without opening either schema.

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

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

The phrase 'no revision is written' implies this is the abort path versus commit/apply, but no sibling is named and no explicit condition ('use this when you want to abandon changes') is stated. Usage is inferable rather than guided.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, so the safety profile is covered. The description adds meaningful behavior beyond that — that `include` collapses multiple fetches into a single round-trip and that `revisions`/`attachments` have scoped returns. It doesn't discuss response size or failure modes, 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 clauses, zero filler. Purpose comes first, the include-array behavior second, the sibling routing last — a logical front-loaded order.

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

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

Output schema exists so return values needn't be explained, and the parameter-level details (tenant_slug multi-workspace rule, revision paging) live in the schema. The description is complete enough for correct invocation, with only minor gaps like not hinting at the multi-tenant requirement.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds framing the schema lacks: the `include` array is a round-trip optimization and each member bundles a specific related entity. That is genuinely useful semantics layered on top of an already well-documented schema.

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

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

States a specific verb and resource ('Retrieve a single document') plus the scope-defining detail 'with its full markdown body', which cleanly separates it from sibling get_meta. An agent can pick this over kb_documents_get_by_slug / kb_documents_get_meta from the first clause alone.

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

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

Explicitly names the alternative and the condition that selects it: 'Use kb_documents_get_meta when the body is not needed.' It also explains why to use the `include` array (bundling related rows in one round-trip), which is a usage decision, not just a schema restatement.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, yet the description still adds real value: 'cheap', no body returned, and notably that a missing document yields null rather than an error. It stops short of describing the multi-tenant refusal behavior, which is only documented in the schema for tenant_slug.

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 cheap/no-body distinction, then the null-return edge case, then the alternative. No sentence is redundant.

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

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

For a two-parameter read-only lookup with a full output schema and 100% schema coverage, nothing material is missing; the description even preempts the surprise of a null result. Its only gap, get_meta disambiguation, is a minor edge case rather than a missing requirement.

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

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

Schema description coverage is 100%, including a detailed note on when tenant_slug is required and what happens on omission, so the schema carries the parameter burden. The description only alludes to tenant scoping via 'in the tenant' and adds no new meaning for the slug parameter.

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

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

States a specific verb and resource ('slug-based lookup', 'minimal metadata (no body)') and explicitly contrasts with kb_documents_get for full bodies. It does not disambiguate from the very similar kb_documents_get_meta sibling, which appears to be the closest alternative for metadata-only reads, so it falls short of a clean 5.

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

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

'Use kb_documents_get for the full body' gives an explicit alternative with the condition that selects it. The slug-first use case is implied by the name and by 'slug-based lookup', but there is no guidance on choosing this over kb_documents_get_meta or when the slug is unknown.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds the cost signal ("cheap") and the key payload property ("minimal metadata, no body") that an agent needs to judge whether a second call is warranted. Return field detail is unnecessary because an output schema 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 short clauses, front-loaded with what the tool returns and costs, then usage, then the alternative. 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 simple two-parameter read with full schema coverage, an output schema, and complete annotations, 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%, so baseline is 3, but "id-based lookup" meaningfully disambiguates the document_id parameter from slug-based access in the presence of the kb_documents_get_by_slug sibling. The tenant_slug fallback behavior is left entirely to the schema.

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

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

"Cheap id-based lookup returning minimal metadata (no body)" states a specific verb, the identifier type, and the output scope in one clause. It is immediately distinguishable from kb_documents_get (full body) and kb_documents_get_by_slug (slug keyed).

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 the use case ("is this doc tagged right?" follow-ups after a search or list) and names the alternative plus the condition that selects it: "Use kb_documents_get when the body is needed."

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds genuine behavior: hidden-project docs are excluded by default, this mirrors the web /docs default view, and the filter is bypassed when project_slug is explicit. That default-exclusion rule is the kind of silent filtering an agent would otherwise miss.

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

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

Front-loaded with purpose, then filters, then sort, then the hidden-default caveat — a sensible information hierarchy with no filler. It is dense but every sentence carries a behavioral claim; the repetition of the hidden logic twice is the only slack.

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?

An output schema exists and annotations carry the safety profile, so the description only needs to cover invocation semantics — which it does, including pagination framing, sort options, and the tenant-scoped default view. Nothing an agent needs to call this 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%, so baseline is 3. The description largely restates the schema's own filter names and sort options, and its include_hidden/project_slug interaction is already spelled out verbatim in the schema property descriptions. It adds framing value but little new parameter meaning.

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

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

Opens with a specific verb and resource ('Paginated browse of documents in the tenant') and immediately separates itself from retrieval siblings by noting that the hidden filter does not affect kb_documents_search or kb_chunks_retrieve. An agent can pick between listing and searching without opening either schema.

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

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

Explains the default view and how to override it with include_hidden, plus the project_slug bypass rule, which is real decision guidance. However it never states plainly when to call this versus kb_documents_search (e.g. broad enumeration vs text matching) — that contrast is only implied by the aside about hidden docs.

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

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

Annotations already declare non-destructive, idempotent write semantics; the description adds the concrete effect (archived_at is cleared) rather than merely restating the name. It does not cover failure modes on a non-archived document, but the core behavior is disclosed.

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

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

Two short sentences, front-loaded with the action and the state effect, with zero filler. Every clause earns its place by adding either scope or sibling differentiation.

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?

An output schema exists and the annotations cover safety, so the description needn't explain returns or permissions. For a simple three-parameter mutation it is nearly complete, missing only what happens if the document is not archived (error vs. no-op).

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 thoroughly documents document_id, tenant_slug, and include_body, so the description does not need to repeat them. The description contributes only the archived_at semantic, which is the appropriate baseline-3 level of value when the schema does the heavy lifting.

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

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

States a specific verb (restore) on a specific resource (soft-archived document) and even names the state change (clears archived_at). It explicitly distinguishes itself from the sibling kb_documents_archive by calling itself the reverse of it.

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 'reverse of kb_documents_archive' framing plus the schema's 'must be archived' precondition gives clear context for when to call this. There is no explicit statement of what to do instead if the document is already active, but the usage path 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?

Annotations already declare readOnly, idempotent, closed-world, non-destructive behavior, so the bar is lower. The description still adds real context beyond them: tenant scoping, ranked-result semantics, mode selection, and the doc-grouped result shape that differs from chunk-level retrieval; it doesn't cover pagination interaction with limit/offset or refusal behavior (the schema does).

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

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

Three sentences, front-loaded with what the tool does, then mode summary, then routing guidance. Every sentence carries distinct information with no filler.

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

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

With annotations covering safety, a full schema, and an output schema, the description supplies what's missing: purpose, result shape, and sibling routing. It leaves limit/offset paging behavior implicit, a minor gap given the schema documents those fields.

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's only parameter-related content is restating the three modes, which the schema enum and its description already document, so it adds no meaning beyond structured data.

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 (hybrid keyword+vector search across documents) plus scope (caller's tenant) and output shape (ranked results with snippets). It explicitly distinguishes itself from kb_chunks_retrieve by noting this tool returns doc-grouped results for browse/search UIs, so an agent can pick between the two without opening schemas.

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

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

Names a concrete alternative and the condition that selects it: passage-level grounding goes to kb_chunks_retrieve, document browsing goes here. It doesn't address other plausible siblings (kb_documents_list, kb_skills_search), so it is clear but not exhaustive.

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

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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description discloses that every save inserts a revision, that the default mode is last-write-wins, and that a no-op save returns no_changes=true without inserting a revision. That is genuine behavioral context. It does not mention permission requirements or the tenant-ambiguity refusal path.

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

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

Three tight sentences, each carrying distinct information (what it does, omit semantics, concurrency mode, no-op result), with the core action front-loaded. 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?

An output schema exists, and the description still flags the one non-obvious return value (no_changes=true) that governs caller behavior. For a mutation tool with full schema coverage, this covers what an agent needs; only permission/tenant edge cases are left entirely 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 coverage is 100%, so each parameter is already documented individually. The description restates the preserve-on-omit rule that the schema already states per field, and only marginally enriches expected_revision_id with the last-write-wins default. 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?

"Save a new revision of an existing document" gives a specific verb (save/revision) and resource, and implicitly separates it from kb_documents_create. It does not explicitly contrast with the edit_begin/apply/commit family or revisions_restore, which are the nearest alternatives.

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?

Clear conditional guidance for the important choices: omit fields to preserve values, pass expected_revision_id for concurrency protection, omit for last-write-wins. No sibling tool is named as an alternative and no when-not-to-use case is given, so it stops short of a 5.

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

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

Goes well beyond the annotations: it discloses the mechanism (sets archived_at), that document links are preserved, and that the group just drops out of active listings and the sidebar. With destructiveHint=false and idempotentHint=true already declared, this adds the practical consequences an agent needs; only permission/prerequisite details are absent.

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

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

Three short sentences, zero waste, with the core action front-loaded and the reversibility/preservation caveats following. 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?

An output schema exists so return values needn't be explained, and the description covers scope, reversibility, and side effects. It could say more about archiving an already-archived group, though idempotentHint=true largely covers that, making this close to complete.

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

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

Schema description coverage is 100% and both parameters (slug, tenant_slug) are fully documented there, including the multi-tenant fallback advice. The description adds no parameter-level information, so the baseline 3 applies.

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

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

States a specific verb and resource ('Soft-archive a group') and immediately clarifies the mechanism ('sets archived_at'), distinguishing it from kb_groups_delete and kb_groups_restore by name. An agent can pick this tool over its siblings 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?

Explicitly names the alternative path ('Reversible via kb_groups_restore') and explains the effect (leaves active listings and sidebar), which implies when to prefer archive over delete. It stops short of an explicit when-not-to-use statement, so it is not a 5.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so 'Idempotent — no-op if already in the group' largely restates structured data. It does clarify what idempotency means here, which is mildly useful, but it omits permission requirements, behavior when the group or document does not exist, and append semantics.

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

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

Two short sentences with zero waste, and the core action is front-loaded before the idempotency note. Nothing extraneous.

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?

Output schema and annotations are present, so safety and return values are covered elsewhere. However, for a mutation tool this leaves gaps the description should fill — such as whether the group must pre-exist, what happens on a bad document_id, and whether this affects group ordering or counts.

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 tenant_slug parameter carries a detailed fallback explanation in the schema itself, so the description adds nothing beyond it. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource: 'Add a document to a group', which maps directly onto the tool name and is unambiguous. It does not name its natural counterpart (kb_groups_detach_document) or distinguish itself from other group tools, but the core action is clear.

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 phrase — you call this to associate an existing document with a group — but there is no explicit when-to-use, no prerequisites (e.g. group must exist), and no guidance on when to reach for the detach sibling instead.

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

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

Annotations already declare destructiveHint=false, readOnlyHint=false, and idempotentHint=true. The description adds useful specificity beyond the annotations by identifying slug as the idempotency key and stating that an existing group is returned rather than an error being raised.

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

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

Two short sentences with no waste. The core action is front-loaded and the idempotency behavior follows immediately.

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 is simple, schema descriptions are complete, annotations are rich, and an output schema exists. The description covers the key creation behavior and conflict handling, though it does not discuss tenant scoping or permissions, which are handled by the schema and surrounding tools.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value by making slug the idempotency key, which is not obvious from the schema's 'URL slug; auto-generated from name if absent' alone.

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

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

States a specific verb and resource ('Create a group'), which clearly distinguishes it from sibling operations like kb_groups_update, kb_groups_delete, kb_groups_get, and kb_groups_list.

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

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

Explains the key behavioral condition for calling it: idempotent on slug, returning the existing group if the slug already exists. This tells an agent it can safely create without checking first, though it does not explicitly name alternatives such as kb_groups_update for modification.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new cascade information: documents tagged with the group are not removed, only untagged, which is exactly the side effect an agent needs before calling. It does not address reversibility, though kb_groups_restore 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?

Two short sentences, zero filler, with the action stated first and the side effect second. Nothing could be trimmed without losing 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?

An output schema exists, so return values need not be explained, and the document-tagging consequence is disclosed. The remaining gap is whether the deletion is permanent or recoverable via kb_groups_restore, which an agent deciding between delete and archive would want to know.

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%, including detailed tenant_slug selection guidance, so the schema carries the parameter burden. The description adds no meaning beyond it, which is the expected 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?

The definition states a specific verb and resource ('Delete a group') with no ambiguity about what is removed. It stops short of distinguishing itself from the adjacent kb_groups_archive tool, which is the meaningful sibling an agent must choose between.

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 delete versus archive, nor any prerequisite or irreversibility warning. With kb_groups_archive and kb_groups_restore both present, the choice is left entirely to inference from the tool 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 declare idempotentHint=true and destructiveHint=false; the description restates idempotency but does add the concrete detail that it is a no-op when the document is not in the group. It stops short of the most useful behavioral fact: that the document itself is untouched and remains in the library.

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 operation and followed by the one behavioral caveat that matters. 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?

An output schema exists and all parameters are documented, so the description only needs to convey the operation and its edge case, which it does. Adding a note that the document persists after detachment would make it 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 tenant_slug parameter is documented in detail in the schema, so the description has no structural gap to fill. It adds nothing parameter-specific beyond the schema, which is the expected 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?

The description opens with a specific verb+resource: 'Remove a document from a group.' That cleanly separates it from the sibling kb_groups_attach_document, though it never names that sibling explicitly.

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

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

Usage is only implied by the verb — an agent can infer this is the inverse of attaching, but there is no explicit when-to-use, when-not, or pointer to a related tool such as kb_documents_delete for actually removing the document.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add context — and it does, by revealing that archived groups are retrievable and how archived state is signalled via archived_at. It stops short of saying what happens when the slug does not exist.

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 operation and followed by the one piece of state semantics an agent actually needs. Nothing is padded or repeated from 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?

An output schema exists and annotations are rich, so the description does not need to explain return shape; it still adds the archived_at interpretation. The only real gap is error behavior for an unknown slug, which is minor for a simple getter.

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

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

Schema coverage is 100%, with the tenant_slug fallback behavior fully documented in the schema itself. The description adds only the 'active or archived' qualifier on slug, which is marginal on top of the structured fields — 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 ('Retrieve a single group by slug') and the parenthetical '(active or archived)' narrows scope usefully. The word 'single' implicitly separates it from kb_groups_list, but no sibling is named explicitly.

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

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

Usage is only implied: an agent can infer that fetching one group by slug is the alternative to kb_groups_list, but the description never says when to prefer one over the other or how to obtain a slug. No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description adds ordering by name, the default archived filter, that each row carries archived_at, and that total is the full match count independent of limit/offset. That is meaningful behavioral context beyond the structured fields, though it omits any mention of empty-result 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 tight sentences with zero waste; scope and default filtering are front-loaded before pagination and return-shape details. Every sentence earns its place.

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

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

With an output schema present and annotations covering the safety profile, the description needn't explain return values, and it still adds ordering, filter defaults and total-count semantics. Nothing an agent needs to call this browse tool correctly is missing.

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

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

Schema description coverage is 100%, so limit, offset, archived and tenant_slug are already documented in the schema. The description reinforces the archived semantics but adds no syntax or format detail beyond what the schema provides, so the baseline 3 is appropriate.

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

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

States a specific verb (paginated browse) and resource (groups in the tenant) plus ordering (by name), which an agent can distinguish from kb_groups_get or kb_groups_create without opening the schema. It stops short of explicitly naming the sibling it replaces, but the resource and verb combination 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?

Explains the default scope (active/non-archived only) and the exact condition to switch (pass archived=true to list archived instead), giving an agent clear selection logic for the flag. It does not name alternatives like kb_groups_get for a single group, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already state non-read-only, idempotent, non-destructive, so the safety profile is covered. The description usefully resolves the 'toggle' ambiguity by making it a set-state operation, but says nothing about permission requirements, behavior for unknown slugs, 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?

Two short sentences, front-loaded with the operation and followed by the parameter semantics. Nothing is padded or redundant.

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

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

For a small state-setting mutation with full annotations, a complete schema, and an output schema, the description covers what an agent needs to call it correctly. The only gap is failure behavior for a missing group or ambiguous tenant, which the schema partly mitigates.

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

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

Schema description coverage is 100%, so all three parameters, including the conditional tenant_slug rule, are already documented. The description's pin/unpin explanation of pinned duplicates the schema text rather than adding syntax or edge-case guidance, so the baseline of 3 applies.

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

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

The description gives a specific verb (toggle) and resource (a group's sidebar-pin state), which is enough to separate it from kb_projects_pin_toggle and kb_groups_update. It stops short of naming any sibling explicitly, so differentiation relies on the reader noticing the 'group' 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 second sentence explains how to use the pinned parameter, not when to prefer this tool over alternatives such as kb_groups_update or kb_projects_pin_toggle. Usage is only implied by the pin/unpin framing.

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 idempotentHint=true, destructiveHint=false, readOnlyHint=false, so the safety profile is covered. The description adds real behavioral detail beyond that: the specific field cleared (archived_at) and the observable effect (group reappears in listings and sidebar), which tells the agent the change is reversible and non-destructive.

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

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

Two short clauses, zero filler, with the core action and its effect front-loaded. Every sentence earns its place by adding either mechanism or the inverse-tool pointer.

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?

An output schema exists and annotations carry the safety/idempotency profile, so the description needn't explain returns. For a 2-param, non-destructive restore, this covers everything an agent needs to select and 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%, and slug plus the multi-tenant tenant_slug guidance are fully documented in the schema. The description adds no parameter detail, so baseline 3 applies.

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

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

States a specific verb (restore/un-archive) and resource (group), plus the concrete mechanism: clears archived_at so the group returns to active listings and the sidebar. It explicitly names the inverse sibling kb_groups_archive, so an agent can distinguish it from archive/delete without opening a schema.

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

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

The phrase 'Reverses kb_groups_archive' gives a clear condition for use and points at the alternative tool. It doesn't state when-not to use it (e.g. versus kb_groups_delete or restore on an already-active group), but the context is unambiguous for this operation.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is carried by structured data. The description adds nothing beyond the mutation verb — no mention that changes overwrite existing values, that slug identifies the target, or the multi-tenant targeting requirement described in the schema.

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

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

One efficient sentence with no filler and the operation front-loaded. Very short, but it does not sacrifice needed clarity as written.

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?

An output schema exists and the input schema is fully documented, so the description needn't explain return values. Still, for a destructive mutation with multi-tenant targeting, the description leaves out the identification requirement and tenant resolution caveats that an agent would benefit from seeing up front.

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

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

Schema coverage is 100%, so the baseline is 3. The description only echoes the field names; the meaningful semantics (slug auto-derivation, null to clear description, tenant_slug resolution behavior) live in the schema, not the 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 ('Rename or update') and resource ('a group') plus the updatable fields, which is enough to distinguish it from read/archive/delete siblings like kb_groups_get and kb_groups_archive. It does not explicitly name those siblings, 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?

No when-to-use, when-not-to-use, or alternative is offered. The description never says to prefer kb_groups_create for new groups or explains the required slug-based identification, leaving usage entirely to inference.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so safety is covered; the description adds auth context not present in structured fields by framing the result as scoped to the token's default workspace. It does not discuss rate limits or failure modes when the token is invalid, which would have pushed it higher.

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

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

A single compact sentence pair with zero filler; the behavioral fact (what it answers) is front-loaded ahead of the pointer to the alternative. 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?

An output schema exists, so return values need no prose, and the tool takes no parameters and mutates nothing. Auth scoping is covered by the "token grants" framing, leaving nothing an agent needs 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?

Zero parameters, so the baseline is 4 by rubric; the empty schema is fully self-consistent and the description needs to add nothing about arguments. It correctly does not waste words restating that no inputs are required.

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 – "Health check" – and immediately says what it returns ("ok and your default workspace slug"), which distinguishes it from every kb_* CRUD sibling. An agent can tell from one sentence that this is a connectivity/auth probe, not a data 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?

Explicitly names the alternative and the condition that selects it: "Call kb_tenants_list to see every workspace the token grants," i.e. use this for the single default workspace, use the sibling for the full list. It stops short of stating when to reach for this tool (e.g. to validate credentials before a batch of calls), so not quite a 5.

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

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

Goes well beyond the annotations: discloses that documents are untouched, retain their project link and stay reachable, and that the project disappears from active listings, the sidebar, and the dashboard count. That is exactly the side-effect profile an agent needs for a non-destructive mutation, and it is consistent with destructiveHint=false and idempotentHint=true.

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

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

Three sentences, front-loaded with the action, then reversibility, then the non-effect on documents. No filler and nothing repeated from 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?

An output schema exists, so return values need not be described; the description instead covers the things structured fields don't: reversibility and the blast radius. For a single-required-param archive tool, nothing an agent needs 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 both parameters (slug, tenant_slug) are already documented in detail, including the multi-workspace fallback. The description adds no parameter-level information, so the baseline 3 applies.

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

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

States a specific verb and resource ("Soft-archive a project") plus the mechanism ("sets archived_at"), which immediately separates it from kb_projects_delete and kb_projects_restore. The parenthetical detail makes the semantics unambiguous, not just a restatement of the name.

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

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

Clearly signals when this is appropriate versus a hard delete by emphasizing soft-archive/reversibility and naming kb_projects_restore as the undo path. It does not explicitly say "prefer this over kb_projects_delete when you want to retain data," so the routing guidance is strong but implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered. The description adds one genuinely behavioral fact — slug is derived from name when omitted — but says nothing about name/slug collisions, failure modes, or what happens if the slug already 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?

Two short sentences, zero filler, with the core action front-loaded and the derived-field caveat immediately after it.

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

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

An output schema exists and the full parameter set is richly described in the schema, so the description needn't explain return values or tenant resolution. It is complete at the level it aims for, though a note on creation-time failure modes would round it out.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including the detailed tenant_slug fallback behavior. The description's auto-generation note merely restates the slug field's schema description, adding no new semantics.

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

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

States a specific verb and resource ('Create a new project'), which is clearly distinguishable from sibling mutators like kb_projects_update and kb_projects_archive. It does not explicitly call out those siblings, but the verb is unambiguous enough to route correctly.

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

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

No guidance on when to use this versus kb_projects_update or kb_projects_restore, and no stated prerequisites. The only contextual rule (tenant targeting when the token spans multiple workspaces) lives entirely in the schema, not the description.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description adds genuinely new behavioral information: the cascade effect on documents (project_id set to null). It stops short of stating whether the deletion is recoverable given kb_projects_restore exists, and says nothing about auth/permission 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?

Two short sentences with zero waste; the primary action is front-loaded and the side effect follows immediately.

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 destructive tool with full schema coverage, annotations carrying the safety profile, and an output schema present, the description supplies the one thing structured fields cannot: the downstream effect on assigned documents. 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 description coverage is 100%, so both the 'slug' and the conditional 'tenant_slug' are already documented in the schema, including the multi-workspace rule. The description adds no parameter-level meaning beyond that, which is 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?

States a specific verb and resource ('Delete a project') that an agent can act on immediately. It does not differentiate from sibling kb_projects_archive, which is the obvious adjacent operation an agent must choose between.

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 when a project should be removed. However, no alternative is named despite kb_projects_archive and kb_projects_restore existing, and there is no statement about when hard deletion is appropriate versus archiving.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that both active and archived projects are retrievable, which is genuinely useful scoping. It does not cover what happens on an unknown slug, though the output schema carries the return shape.

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

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

Two short sentences with zero filler, and the core operation is front-loaded ahead of the field detail.

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

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

For a single-resource read with full schema coverage, annotations and an output schema, the description covers the essentials (active vs archived reachability). Only the not-found behavior is left implicit, which is minor at this complexity.

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

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

Schema description coverage is 100%, and tenant_slug already carries a detailed fallback/refusal explanation in the schema. The description only echoes 'by slug' and adds no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Retrieve a single project by slug'), and the word 'single' implicitly distinguishes it from kb_projects_list. It does not name that sibling explicitly, so an agent must infer the routing rather than being told.

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

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

Usage is only implied: fetch one project by its slug. There is no explicit statement of when to use this versus kb_projects_list, nor any prerequisite about the slug's origin (e.g. from a list call).

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

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

Beyond the annotations (idempotent, non-destructive), the description discloses the actual effect of the flag: which listings filter the project out, that a 'Show hidden' control reveals it, and that search/retrieval tools still surface the content. This is exactly the kind of consequence-level detail annotations cannot express.

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

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

Purpose is front-loaded in the first sentence and every subsequent sentence carries real information. The parenthetical enumeration of four UI surfaces is slightly verbose but earns its place by making the blast radius concrete.

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 an output schema present and rich annotations, the description covers what the flag does, what it does not affect, and the value convention. An agent has everything needed to call this correctly without guessing about side effects.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the tenant_slug fallback guidance. The description only restates the boolean's meaning rather than adding format or edge-case semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Toggle a project's hidden flag') and immediately defines what 'hidden' means in terms of concrete surfaces (browse listings, sidebar, picker). An agent can distinguish this from kb_projects_pin_toggle and kb_projects_archive without opening a schema.

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

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

Explicitly tells the agent which values to pass ('hidden=true to hide, false to unhide') and clarifies the scope decision by noting hidden does NOT affect search or agent retrieval. It does not explicitly contrast with the sibling kb_projects_pin_toggle, leaving that differentiation to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint, so safety is covered; the description goes further by disclosing the default exclusion of hidden projects, the archived-vs-hidden lifecycle distinction, and that total is independent of limit/offset. What's missing is pagination behavior at the boundary (e.g., how to detect the last page beyond total), which keeps it off 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?

Four tight sentences, front-loaded with scope, then defaults, then cross-reference, then return semantics. No restatement of the tool name and no filler; every clause carries information an agent needs.

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

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

With an output schema present, return values needn't be detailed, yet the description still flags the one non-obvious field (total). Defaults, filter interactions, and the cross-tenant caveat are all covered, leaving nothing an agent needs in order to call this 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 baseline is 3, but the description adds real semantic value by explaining the interaction between archived and include_hidden and by clarifying that total is the full match count rather than the page size. It doesn't add anything for limit/offset/tenant_slug beyond what the schema already documents.

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 ('Paginated browse of projects in the tenant') and immediately scopes it with default filters, which cleanly separates it from kb_projects_get (single-item) and kb_projects_archive/restore (mutations). The archived-vs-hidden distinction is called out explicitly, so an agent can tell which projects this list will and won't return.

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 concrete when-to-use conditions: default active-only, pass archived=true for archived, include_hidden=true to see hidden ones, plus a pointer to kb_projects_hide_toggle for background. It doesn't explicitly say when to prefer kb_projects_get or how it relates to other list tools, but the filtering guidance is unusually actionable.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false; the description's main added value is resolving the 'toggle' vs. explicit set-state ambiguity, confirming the call is deterministic rather than a flip. It adds nothing about tenant-scoping refusal behavior beyond what the schema states, and no return-value context.

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

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

Two short sentences, zero padding, and the core action is front-loaded before the parameter hint. Nothing could be removed without losing 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?

With an output schema, full parameter documentation, and rich annotations, the description only needs to establish purpose and pin semantics, which it does. The remaining gap is its silence on how this relates to hide_toggle and whether pinning affects any listing order for the agent.

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

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

Schema description coverage is 100%, so all three parameters (including the conditional tenant_slug with its fallback instructions) are already fully documented. The description's restatement of pinned=true/false duplicates the schema rather than adding format or edge-case detail, so the baseline 3 applies.

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

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

States a specific verb+resource: 'Toggle a project's sidebar-pin state', which is concrete and distinguishable from kb_groups_pin_toggle by the resource. However, it never mentions kb_projects_hide_toggle, another closely related project-visibility operation, so sibling differentiation is only partial.

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 says how to invoke (pinned=true to pin, false to unpin) but not when to choose this over kb_projects_hide_toggle or when a pin should be set versus left alone. Usage is implied by the tool name rather than stated, and no exclusions or prerequisites are given.

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

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

Annotations already declare this is a non-read-only, non-destructive, idempotent mutation, so the description's added detail about clearing archived_at and restoring visibility is useful behavioral context. It does not cover permission requirements or response details, but the output schema helps.

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, front-loading the verb and resource before describing effects and the inverse sibling. 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 simple idempotent restore tool with a complete input schema, annotations, and an output schema, the description covers the state effect and sibling relationship well. Nothing an agent needs for correct invocation is missing.

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

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

Schema description coverage is 100%, with both slug and tenant_slug documented in the schema itself. The description adds no additional parameter-level meaning, so the baseline 3 is appropriate.

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

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

States the specific verb and resource ('Restore (un-archive) a project'), spells out the concrete effect (clears archived_at so it returns to active listings, sidebar, and dashboard count), and explicitly names the inverse sibling kb_projects_archive. This is enough to distinguish it from archive/delete/hide siblings.

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

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

The description clearly frames usage as reversing kb_projects_archive and restoring a project to active status. It does not explicitly say when not to use it or name alternatives like delete/hide, so it falls short of a full 5.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds no context beyond them. It does not warn that replacing a slug can break existing links/references, does not mention the tenant_slug refusal behavior needed with multi-workspace tokens, and does not state that omitted fields are left unchanged. For a destructive mutation, this is a meaningful gap.

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

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

One short sentence, front-loaded with the verb and resource, with zero padding. It is efficient but so sparse that brevity shades into under-specification rather than crispness.

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?

An output schema exists and the parameter schema is fully documented, so return values need not be described. However, the destructive nature of slug changes and the tenant-scoping behavior are the key operational facts an agent needs for a mutation, and neither is surfaced in the description.

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 name, slug, new_slug, description (including null-to-clear), and tenant_slug with its multi-workspace rule. The description's field list merely restates the schema at a coarser level and adds no syntax or edge-case detail.

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 ('Rename or update a project's name, slug, or description'), so the agent knows exactly what changes. It does not differentiate itself from nearby siblings such as kb_projects_create, kb_projects_archive, or kb_projects_hide_toggle, leaving the agent to infer separation from the name alone.

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

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

No guidance on when this is the right call versus alternatives. Notable omissions: whether archiving/repurposing is handled by kb_projects_archive, and the fact that changing a slug affects downstream references. The agent gets an action but no decision context.

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 idempotentHint=true and destructiveHint=true, so the safety profile is covered structurally. The description adds genuinely non-redundant behavior: already-cancelled rows are no-ops and out-of-scope targets return not_found rather than erroring — useful expectations beyond the hints. It does not say whether cancelling a schedule also cancels its pending reminder instances, which is the main remaining ambiguity.

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: the action/mode split comes first, then idempotency, then the authorization caveat. No filler and nothing 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?

Returns are covered by an existing output schema, and the description closes the two biggest gaps for a destructive, scoped mutation: idempotency and reachability. The only meaningful omission is the cascade question (does schedule cancellation affect already-scheduled reminder rows?), which matters for a destructiveHint tool.

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

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

Schema description coverage is 100%, so all three parameters (including the tenant_slug fallback guidance) are already fully documented in structured fields. The description's mention of reminder_id/schedule_id only restates the schema's mutual-exclusivity note and adds no format or edge-case meaning beyond it; 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 the specific verb (cancel) and both resources (single reminder via reminder_id, entire schedule via schedule_id), with the parameter that selects each mode named inline. An agent can distinguish this from kb_reminders_list/get/create 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?

Explains the two mutually exclusive cancellation modes and how to pick between them, plus the scoping rule that only reminders/schedules you created or receive are reachable. It stops short of naming alternatives (e.g. kb_reminders_get/list for discovering IDs) or telling the agent when not to use this at all.

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

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

Goes well beyond the annotations: it states the reminder actually SENDS a message over email/Slack/SMS, that delivery is irreversible, and that cancel only affects unfired reminders. Those are exactly the consequences an agent needs before invoking a destructiveHint=true tool.

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

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

Three tight sentences, front-loaded with the action, then the consequence, then the guardrail. The middle clause runs long with two joined ideas (irreversibility and cancel scope) but every sentence carries information.

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

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

For a 7-parameter mutation with an output schema and annotations, the description covers creation, irreversibility, and recipient scope. Multi-workspace token behavior lives only in the schema, which is acceptable but is the one area an agent might still stumble 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 already 100%, so the baseline is 3; the description earns more by explaining the semantics of omitting `recipients` (send to self) and `channels` (recipient preference) and by framing recipients as real people who will each receive a message. Tenant-slug and document-slug behavior is left to the schema.

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

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

States a specific verb and resource ("Create a one-off reminder") and scopes it to "one or more tenant members". The word "one-off" implicitly separates it from kb_reminders_create_schedule, but the sibling is never named outright, so the agent must infer the split.

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

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

Gives an explicit gating rule: "Create one only when the user asked for it, addressed to the people the user named." That is real when-to-use guidance plus an exclusion on recipient targeting, though it never points to kb_reminders_create_schedule for recurring cases.

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

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

Goes well beyond the annotations by disclosing the mechanics: rrule is validated before persistence, per-occurrence rows are expanded by the materialiser, every occurrence actually SENDS via email/Slack/SMS, and a delivered message cannot be recalled. It also clarifies that cancelling only stops occurrences that have not fired, which directly qualifies the destructiveHint.

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 sentences, front-loaded with what it does, then the persistence pipeline, then the irreversible-delivery warning, then the usage gate. No sentence is filler and the most consequential fact (messages cannot be recalled) is placed prominently.

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?

Output schema exists and annotations declare destructive/openWorld/non-idempotent, so the description's job is the judgment layer — and it delivers exactly that: irreversibility, delivery side effects, and the escalation condition for recipients. An agent has everything needed to decide and 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?

Schema description coverage is 100% and the per-parameter docs are already rich (including the recipients escalation warning and tenant_slug refusal behavior). The description reinforces the recipients constraint but adds no syntax or format meaning the schema does not already carry, so this sits at 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?

Opens with a specific verb+resource ("Create a recurring reminder schedule") and scopes it to recurring reminders only, which implicitly separates it from the single-fire kb_reminders_create sibling. It never names that sibling outright, so the differentiation requires a small inference.

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

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

Gives an explicit gating condition ("Create one only when the user asked for a repeating reminder, addressed to the people the user named"), which covers both when to use it and who it should target. It stops short of naming when-not/an alternative tool explicitly.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds non-obvious access-control semantics — the ownership/recipient visibility rule and the exact not_found outcome — which is genuine value beyond the annotations, though broader failure or paging behavior isn't described.

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 core action, and the access constraint follows. Every clause earns its place with no repetition of schema material.

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?

Output schema exists, so return values and the delivery rows need no prose explanation. Access rules are covered and tenant targeting is fully handled in the schema, leaving nothing an agent needs before calling it.

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

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

Schema coverage is 100%, so reminder_id and the tenant_slug workspace-selection rule are fully documented in the schema. The description only echoes 'by id' and adds no syntax or usage detail beyond what the schema states, 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 (fetch) and resource (a single reminder) plus the accompanying delivery rows, which clearly separates it from kb_reminders_list. An agent can pick this over the list sibling without reading either schema.

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

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

The description scopes when this works ('only reminders you created or receive are reachable') and that misses return not_found, which is clear contextual guidance. It doesn't explicitly name kb_reminders_list as the browsing alternative, so it falls short of the 5 bar.

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