SharedBrief

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

Annotations already cover the safety profile (destructive, idempotent, not read-only). The description adds real context beyond them: the verified-email prerequisite, the token-handling rule ('accepted from the invitation link and never echoed'), and the membership-control model. It doesn't state what success/error looks like, but no output schema exists and the safety dimension is well covered.

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

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

Four short sentences, front-loaded with the consent gate and prerequisite before the softer explanatory guidance. Every sentence carries relevant information; only the 'explain that admins control membership' sentence leans toward instructional filler.

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

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

For a mutation tool with annotations covering safety and no output schema, the description supplies the prerequisite, the consent requirement, and token handling. The main omission is failure behavior (expired/used token), but the structured fields carry most of the rest.

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 50%: 'confirm' is described in the schema, but 'token' only has a regex pattern. The description partially compensates by explaining where the token comes from and that it is never echoed, but it adds no format or source detail beyond that. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Join a team' by accepting an invitation) and immediately distinguishes it from sibling tools like invite_workspace_members, revoke_workspace_invitation, and resend_workspace_invitation. An agent can tell what this does without opening the schema.

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

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

Gives a clear gating condition ('only on an explicit user request to accept their invitation') and a prerequisite ('The connected account must have the invited verified email'). It does not explicitly name alternative tools for the invite/revoke side, so it stops short of a full comparison.

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 openWorldHint=true, so the safety profile is partly covered. The description adds real behavioral context beyond them: replacement needs the current revision as expectedRevisionId (optimistic concurrency), reader URL/access settings are preserved, a reserved job is not yet completed, and URL fetching is deferred to complete_document_import. Return format and failure modes remain unstated.

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 supported formats, then constraints, then the replacement and two-phase-job caveats. 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?

For a 7-parameter, nested-schema mutation with no output schema, it conveys the workflow shape well (reserve now, complete later) and the replacement contract. It is not fully complete: several parameters (htmlMode, workspaceId, idempotencyKey) are undocumented, though status/return info is delegated to sibling 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 0%, so the description must carry parameter meaning, and it only partly does: it explains the replace path (documentId plus current fileRevisionId as expectedRevisionId) and implies source.kind='url'. It says nothing about htmlMode's static/interactive enum, workspaceId, idempotencyKey, title, or declaredBytes, leaving several params undocumented.

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

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

States a specific verb+resource ('Import an existing PDF, image, HTML file or direct HTTPS URL as a private document') and immediately bounds scope by naming unsupported types (Office, video). This clearly separates it from siblings like create_document and complete_document_import 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?

Gives concrete when/when-not guidance: file bytes must originate from the authenticated embedded chooser or supported attachment transfer, never a local path, and Office/video are unsupported. It also routes the URL-fetch follow-up to complete_document_import. It stops short of explicitly contrasting against the nearest sibling (create_document) or stating prerequisites like permissions.

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

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

Goes well beyond the annotations by disclosing the race outcome, the billing side effect ('Storage remains charged until physical cleanup succeeds'), and the blast radius ('does not delete an existing document or original'). These are exactly the side-effect and post-condition details an agent needs for a destructive-but-idempotent operation, and they are consistent with destructiveHint=true rather than contradicting it.

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 its target, followed by the failure mode and the side-effect boundary. No filler and nothing repeated from the 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?

With no output schema, the description carries the return-value burden and does so ('read back the saved outcome'). It also covers the key held-state and cleanup caveats; the only shortfall is not explaining the jobId's origin or any authorization requirements beyond 'owned'.

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

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

The input schema has 0% description coverage, so jobId is documented only by its UUID pattern. The description supplies semantic context ('owned pending import') implying the id identifies that import job, but never says what the id is or where to obtain it, leaving a real gap for a low-coverage single-parameter 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?

Names a specific verb and resource ('Request cancellation of an owned pending import'), states the ownership scope, and adds that the call reads back the saved outcome. The clause 'does not delete an existing document or original' implicitly separates it from delete_document and shows it operates on the import job, not the document, so the agent can place it among the import 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?

Tells when this applies: only 'owned pending' imports, and warns that 'Completion may already have won', which signals the race with complete_document_import and that a successful call may still yield a completed job. It stops short of naming the alternative tools or explicitly stating when not to cancel.

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 destructive=true, idempotent=true, and openWorld=true, so the safety profile is partly covered. The description adds genuine non-annotation context: it does not publish, replacement preserves existing publication and access controls, and only a 'ready' state confirms the save. What actually gets destroyed on replacement remains unstated.

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

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

Four short, front-loaded sentences with no padding, and the key non-publishing constraint appears early. However, fragments like 'Only ready confirms saved state' are terse to the point of ambiguity rather than clear.

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

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

For a destructive, open-world mutation with no output schema, the description covers the non-publishing and replacement-preservation behaviors but leaves the required jobId, the meaning of the 'ready' state, and the returned result unaddressed. Adequate but with visible gaps.

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

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

Schema description coverage is 0% across two parameters, so the description must compensate. It implicitly maps to fetchUrl via 'explicitly fetch the original direct HTTPS source' versus 'uploaded bytes', but jobId (the required uuid) is never explained, leaving half the parameters uninterpreted.

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 concrete action (inspect uploaded bytes and save the private imported document) plus an alternate path (fetch the original direct HTTPS source), which is specific enough to distinguish it from begin_document_import or get_document_import_status. The 'Does not publish' clause further separates it from publish_document, though the phrasing is dense.

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 (this is the completion step of the import flow, and 'Does not publish' implies a boundary) but no sibling tool is named and there is no explicit when/when-not guidance relative to get_document_import_status or cancel_document_import. An agent must infer the sequencing.

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 exactly what payload leaves the system (supplied message plus the connected account's verified email), that document content and conversation history are opt-in, that secrets should be excluded, and — critically — that success only means the email provider accepted the request, not that support read or replied. That last point is a real behavioral trait an agent needs to avoid over-promising to a user, and it is not derivable from readOnlyHint/openWorldHint/idempotentHint.

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

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

Five sentences, all substantive, with the critical precondition front-loaded in sentence one. Slightly dense — the data-sharing and idempotency rules could be tightened — but nothing is filler and each sentence carries distinct information.

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

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

For a 2-param mutation tool with no output schema and an open-world side effect, the definition covers payload scope, opt-in data sharing, retry semantics, and success criteria. The remaining gap is error/failure behavior (e.g., what a rejection looks like or delivery limits), but the essentials for correct invocation are present.

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

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

Schema description coverage is 0%, so the description carries the full param burden, and it does so: 'message' is constrained to only the supplied message (nothing else leaks), and 'idempotencyKey' is explained as generate-fresh-per-message versus reuse-with-identical-message-within-24-hours. That is operational semantics far beyond the UUID format in the schema, and it coherently explains the idempotentHint annotation.

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

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

States a specific verb+resource ('Send a support message to SharedBrief') and immediately scopes it with a precondition. It is unmistakably distinct from all sibling tools, which are entirely document-management operations, so an agent can never confuse this with get_document or update_document.

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 gating condition ('only when the user explicitly asks to contact support') and clarifies what is shared by default versus what requires explicit user selection. No alternative tool is named, but no plausible alternative exists in this toolset, so the guidance is effectively complete without an exclusion clause.

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, idempotent, non-destructive, closed-world, and the description adds the context that really matters: the result is a private draft, nothing is emailed or invited, and publication is a separate step. It also discloses content constraints (no external dependencies or network actions, static mode rejects scripts) and access-mode interaction rules beyond 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?

The trigger condition is correctly front-loaded, but the middle is bloated with reader-settings features (anonymous links, email gating, name/email/phone capture, passcodes, expiration) that this tool cannot configure and that the description itself defers to other tools. Those sentences serve as product context rather than call guidance.

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 cover the safety profile, so the description only needs to cover intent, privacy lifecycle, and content-format choice — all of which it does, including the interactive-vs-static and HTML-vs-blocks decisions an agent must make before calling.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds decision guidance, stating that interactive HTML uses format html with mode omitted, explicit static HTML is script-free, and structured blocks suit text-only documents. The remaining gap is workspace_id/idempotencyKey semantics, which it never mentions (though the schema documents them well).

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 ('Creates a private draft') with concrete artifact examples (sales proposal, client report, investor update, one-pager). It also distinguishes the outcome from its closest sibling by stating the draft remains private until published, which separates it from publish_document without needing 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?

Opens with an explicit 'Use when the user wants to turn conversation content into a saved, shareable document', and routes reader-settings/activity/lead controls to dedicated tools. It does not name the alternative paths for ingesting existing files (begin_document_import) or when to prefer duplicate_document, so the alternative map is incomplete rather than absent.

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, so the safety profile is covered. The description still adds real behavioral context: the creator funds it, existing briefs are not moved, and no invitations are sent. It does not address permissions or failure modes, keeping it short of a 5.

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

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

Three tight sentences with the core action front-loaded and no filler. It could be slightly more economical given how little it says about parameters, but nothing is wasted.

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

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

No output schema exists, so ideally the description would say what a successful create returns, and it does not. Still, for a two-parameter create whose safety profile is fully covered by annotations, the description gives enough behavioral context to call 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 0% for two required parameters (name, idempotencyKey), and the description says nothing about either. The idempotencyKey especially is non-obvious, and the description provides no syntax or intent guidance to compensate.

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

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

The description names a specific verb and resource ('Create ... separate brief library') and clarifies a key semantic distinction (independent of inviting teammates). The term 'brief library' does not match the tool name 'create_workspace', which creates minor terminology friction, but the scope is still understandable.

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

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

Calling it 'optional' and independent of teammate invitations implies a usage context (setting up a standalone library rather than sharing into an existing account). However, it never names sibling alternatives like list_workspaces or update_workspace, so when-not-to-use is only implied.

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

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

Annotations flag destructiveHint=true, but the description goes beyond that boolean with information an agent cannot get from structured fields: the deletion is permanent, view records are removed as part of it, and previously copied or downloaded content persists with recipients. The residual-content caveat is exactly the kind of irreversibility context that prevents a bad call.

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, no filler, and front-loaded with the destructive action and its scope before the parameter requirement and the caveat. Every sentence carries distinct information.

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

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

For a two-parameter destructive mutation with no output schema, the description covers the critical behavioral facts: permanence, scope of deletion, and leftover recipient copies. It does not mention error/not-found behavior or permission prerequisites beyond what the id schema implies, which is a minor 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 coverage is 50%: the id parameter is thoroughly documented in the schema (UUID of a document owned by the account), while confirm has no description. The description's statement that confirm must be true merely restates the schema's const:true constraint, adding no new meaning. Adequate but not additive.

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 adds the collateral scope — associated view records are deleted too. No sibling competes on the same verb, so an agent can immediately tell this is the hard-delete path rather than the milder unpublish_document or update_document.

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 gives one hard precondition ('the confirmation parameter must be true') but no when-to-use guidance relative to alternatives. With unpublish_document and update_document among the siblings, an agent would benefit from knowing when to hard-delete versus unpublish or archive, and no such framing is offered.

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 with the 'copies content, never publication, sharing recipients, reader controls, visits, leads or alerts' exclusion list — precisely the state-carryover question an agent cannot answer from readOnlyHint/idempotentHint/destructiveHint. It also grounds the idempotency hint in concrete retry behavior.

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

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

Three short sentences, zero filler, with the core action and copy semantics front-loaded before the retry note.

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

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

Covers scope, copy semantics, and retry handling for a two-parameter mutation. With no output schema, it could have said what the caller gets back (e.g. new document id), which is the only material gap.

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

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

Schema description coverage is 0%, so the description carries the burden. It explains the idempotencyKey's purpose clearly ('same key when retrying'), but the required uuid `id` is only obliquely implied via 'owned document' — the source-vs-new-document role of each parameter is not fully spelled out.

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 (duplicate) plus resource (owned document) and an explicit scope boundary (into a new private draft). An agent can distinguish it from create_document and copy-style 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?

States the precondition that the source must be an owned document and gives retry guidance tied to the idempotency key. It does not name an alternative sibling or state when-not-to-use, so it stops short of a full routing statement.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds meaningfully: it scopes results to documents owned by the connected account, reports actual publication state and whether the URL is owner- or reader-facing, and flags that imported originals return only bounded file metadata while original bytes/HTML come from an authenticated embedded preview. That is substantive behavioral context beyond the structured fields.

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 usage, then return semantics, then the import/preview nuance; each sentence carries information. The final sentence is jargon-dense ("authenticated embedded preview handles original bytes and HTML source") and costs a little readability.

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

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

With no output schema, the description takes on the burden of describing returns and does so: ownership scope, publication state, URL audience, and the import/preview distinction. An agent has enough to call it correctly and anticipate the response shape.

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?

Only one parameter and schema_description_coverage is 100%, so the schema already carries the meaning of id. The description adds a light constraint by saying the document must be owned by the connected account, but no additional syntax or sourcing detail beyond what the schema states.

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 (read/retrieve an existing SharedBrief document and its latest content/revision) and implicitly separates itself from list_documents and update_document by framing retrieval as a read step. An agent can tell this is a single-document fetch rather than a listing or mutation.

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 when the user wants to read an existing SharedBrief document or retrieve its latest content and revision before editing" gives a clear trigger plus a workflow context (pre-edit refresh). It does not name competing siblings such as read_document_for_app, read_document_file_from_app, or show_document, nor state exclusions, so no explicit 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 establish readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds genuinely useful data caveats: bounded pagination, verified vs self-reported emails, non-retroactive anonymous identification, non-unique visits, and approximate duration. These materially shape interpretation of results. It stops short of describing page size or exhaustion 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?

Terse and dense with no filler; the constraint leads. It reads as a packed set of clauses rather than a structured purpose-then-caveats flow, but nothing is wasted.

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

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

With no output schema, the description should help the agent understand the return payload; it supplies valuable interpretation caveats (visit semantics, email provenance, duration accuracy) but not the structure or fields returned. Adequate but leaves the agent guessing about output shape and pagination mechanics.

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

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

Schema coverage is 0%, so the description carries the burden for id, limit, and cursor. 'Bounded pages' vaguely gestures at pagination but never explains that limit caps page size (max 50) or what cursor does. The required document id is not described at all. Significant compensation gap.

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

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

The description references 'detailed reader activity' for a document, which conveys the resource but not a clear verb or the returned shape. It never distinguishes this tool from siblings like get_document_stats or get_document_leads, which likely overlap in the 'activity' space. Purpose is inferable but not precisely stated.

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

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

'Only use on an explicit owner request' is a strong, explicit when-to-use gate that most definitions lack. However, it names no alternative tool (e.g., get_document_stats for aggregate numbers) and gives no when-not condition beyond the owner-request constraint.

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 genuinely new behavioral context: a saved enabled preference is not a delivery guarantee while deliveryAvailable is false. That is the kind of semantic nuance 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?

Two tight sentences, no filler. The core purpose is front-loaded and the delivery caveat follows. It could be slightly tighter, but nothing is wasted.

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

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

With no output schema, the description partially covers return semantics by naming the preference value and deliveryAvailable. For a single-parameter read tool this is nearly sufficient; only the id's identity/format 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 0% for the single 'id' parameter, so the schema gives no meaning for it. The description's phrase 'per-document' implies the id is a document identifier, which partially compensates, but it never states the required format or that the id refers to a document explicitly.

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

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

States a clear verb+resource: read the saved per-document email alert preference, scoped to the workspace paying account. It implicitly separates itself from update_document_alerts and get_document_reader_settings by naming the exact resource (email alert preference), though it never explicitly contrasts with those siblings.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternative is named (update_document_alerts, get_document_reader_settings). The agent must infer from the name that this is a read-before-write check; the description offers no explicit routing.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: only a 'ready' status means the private draft, atomic replacement, or assetId result was actually saved, while errors and pending are not success. This result-interpretation guidance is valuable and not derivable from 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?

Two tightly written sentences with the purpose front-loaded and no filler. The second sentence is dense but every clause about success conditions earns its place.

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

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

With no output schema, the description must explain return values, and it does partially by defining 'ready' as the success state. However, it does not enumerate the full set of possible statuses (e.g. failed, cancelled) or the returned payload shape, leaving gaps for a status-polling 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 0% and the single jobId parameter is undocumented in the schema, so the description must compensate. 'Owned import job' hints that the jobId must reference a job belonging to the caller, adding some meaning, but it does not clarify format or lookup expectations.

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 ('Read an owned import job'), and the 'owned' qualifier distinguishes it from siblings like transfer_document_import_from_app. It is slightly imprecise in that the tool returns status, not the job itself, but an agent can still tell what it does.

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

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

There is no explicit when-to-use statement or named alternative, but the status-semantics sentence implies it is used to check the outcome of an import job. Usage is inferable rather than stated, so it lands at minimum-viable.

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 and the description correctly does not repeat them. It adds genuinely new context the annotations cannot: the data is self-reported rather than verified identity, and results come in bounded pages — both material for how an agent should present or trust the output.

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, no filler, and the most decision-relevant constraint (explicit owner request only) is front-loaded. The 'Bounded pages' fragment is terse but informative rather than padding.

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

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

With no output schema, the description usefully names the returned fields (name/email/phone) and flags their self-reported nature, which is the key interpretive context. It is close to complete for a simple read, with pagination mechanics the only real gap.

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

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

Schema description coverage is 0% across three parameters (id, limit, cursor), so the description carries the full burden. 'Bounded pages' hints that pagination exists but does not explain that limit caps at 50, that cursor is an opaque continuation token, or what the uuid id identifies — leaving the agent to reverse-engineer all three from the schema 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?

The description states a specific resource ('captured leads of this document') and the title/name carry the read verb, so it is clearly distinguishable from siblings like get_document_stats, get_document_activity, or get_document_sharing. It stops short of restating the action explicitly, but the resource scope is unambiguous.

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

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

'Only use on an explicit owner request for captured leads of this document' is a real gating condition that tells the agent when not to call it (proactive/incidental use) and implies an authorization requirement. No sibling alternative is named for adjacent lead-like needs, so it falls 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior. The description adds genuinely new behavioral context beyond them: the ownership scoping constraint and the redaction guarantee that the existing passcode and hash are never returned, which an agent could not infer from 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?

Two tight sentences with no filler. The positive statement of what is returned is front-loaded, followed immediately by the negative guarantee, which is exactly the right ordering for a read tool.

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

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

With no output schema, the description carries the burden of describing returns, and it does name the returned fields (capture fields, expiry, hasPasscode) plus what is withheld. It stops short of describing field types or the empty/absent case, but it is complete enough to invoke 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 0%, so the schema does not explain the single 'id' parameter. The description does not describe it either, but the parameter is a self-evidently named UUID identifier, so the gap is minor rather than severe. It neither compensates for nor worsens the coverage gap.

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

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

States a specific verb (read) and resource (saved reader settings for a document) and enumerates the returned fields (capture fields, expiry, hasPasscode). It is clearly distinguishable from update_document_reader_settings and get_document, though it never names those siblings 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?

'for an owned document' implies a precondition (ownership scope) that helps the agent decide applicability. However, there is no explicit when-to-use versus update_document_reader_settings or get_document, and no stated exclusions, so usage is only implied.

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

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

Adds real behavioral context beyond the read-only annotations: an authorization constraint ('Only the owner can read these settings') and a semantic caveat about what the returned list actually represents versus actual readers. The remaining prose concerns dashboard capture/passcode features that belong to other tools rather than this call's 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?

The useful content is front-loaded in the first three sentences; the rest is a long tangent about owner-dashboard capture fields, passcodes, expiration, public-vs-verified modes, and anonymous visits, none of which describe this read operation. Only the final routing clause about reader-settings/lead tools earns its place.

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

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

With no output schema, the description correctly discloses what is returned (access mode plus allowed recipient emails) and states the owner-only access requirement, which is the essential calling context. It is somewhat over-covered on unrelated dashboard features while the relationship to set_document_sharing stays 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?

Only one parameter and schema description coverage is 100% (the UUID's origin is documented as 'returned by document creation or listing'), so the schema already does the work. The description adds nothing further about the id, which is the expected baseline when coverage is complete.

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 ('check its current access settings', 'Returns the access mode and allowed recipient emails') and explicitly draws the boundary against the most confusable sibling: 'this list controls access and is not a list of actual readers' and 'does not return individual reader emails.' An agent can distinguish this from get_document_activity 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?

Opens with a clear triggering condition ('Use when the owner asks who is allowed to open a document') and names where to go instead for management ('use the dedicated reader-settings and explicit-request activity/lead tools'). It never explicitly names set_document_sharing as the write-side counterpart, so routing for modification is left partly 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/non-destructive, so the bar is lower, yet the description adds substantial context: results are approximate daily/browser views over the most recent 100 visits, visits are not unique people, active time is approximate, and it does NOT return individual reader emails. This discloses data limits and privacy boundaries the 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?

The trigger sentence is well front-loaded, but the back half drifts into owner-dashboard capture modes, passcodes, expiration, and sign-in requirements that this stats tool does not perform. Those lines inflate the definition without helping an agent call get_document_stats correctly.

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

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

With no output schema, the description carries the return-value burden and mostly does: it explains what data comes back (approximate views, engagement aggregates) and what it omits (reader emails). A 1-param read tool is adequately specified here, though the tangential dashboard detail crowds the useful content.

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?

Single parameter with 100% schema coverage, so the schema already documents the id fully. The description adds no syntax or format detail about the id and instead spends words on unrelated dashboard features; 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?

State a specific verb/resource: returns how a shared document was viewed, last opened, and reader engagement aggregates. It clearly describes what it returns, but only distinguishes itself from siblings (get_document_activity, get_document_leads, get_document_reader_settings) obliquely at the very end, so the differentiation is not front-and-center.

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 opening sentence gives a concrete when-to-use trigger ('user asks whether a shared document has been viewed, when it was last opened, or how readers engaged'). It also routes control-management tasks to 'dedicated reader-settings and explicit-request activity/lead tools,' naming alternatives, though without explicit when-not conditions.

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

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

Annotations already establish the safe read-only profile, so the bar is lower, and the description still adds real behavior: admins see pending invitations, tokens are never exposed, and no workspace is created. That is meaningful disclosure beyond the structured hints.

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

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

Four short sentences, front-loaded with what is returned before the admin caveat, scope note, and negative guarantees. Nothing is padded, though the final negative sentence is defensive filler.

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

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

For a zero-required-param read tool with no output schema, the description covers who is returned, the admin-only extension, the scope selector, and two negative guarantees. The only real gap is terminology alignment with the workspace_id parameter and differentiation from get_workspace_team.

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

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

The single parameter has 0% schema coverage, so the description must compensate. It conveys that the ID is optional and selects another library you belong to, but it calls the field 'library ID' while the schema names it workspace_id, which is more likely to confuse than clarify.

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: reading who can access briefs and their roles, plus the admin-only visibility of pending invitations. It is clear on its own, but it never distinguishes itself from the very similar sibling get_workspace_team, and its use of 'library ID' conflicts with the tool's own workspace_id parameter.

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 implicit context (admins see more, optional library ID scopes to another library you belong to) and one negative statement ('does not create a workspace'). It never says when to prefer this over get_workspace_team or how it relates to invite_team/remove_workspace_member.

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 read-only, idempotent, non-destructive behavior, so the description correctly spends its words elsewhere: it discloses that results are paginated ('bounded pages') and that captured identity is 'self-reported, not verified' — a genuine data-trust caveat an agent could not infer from annotations or schema. It does not describe ordering or retention, but the added context is substantive.

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

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

Three short sentences with no padding, and the restrictive precondition is front-loaded where an agent will see it first. Slightly compressed to the point that the core purpose statement is missing, but nothing is wasted.

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

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

With no output schema and no annotation gaps, the privacy and pagination warnings are the right content, but a 4-parameter cross-document tool still leaves the agent guessing how to scope a call (workspace_id vs documentId) and what an activity record contains. Adequate but with clear gaps.

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

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

Schema description coverage is 0% across four parameters, so the description carries the full burden and mostly fails: 'bounded pages' hints at limit/cursor but never explains page size or cursor semantics, and the distinction between documentId and workspace_id — the key scoping choice — is unaddressed.

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 leans on the name and title to convey the action, characterizing the tool as 'cross-document detailed activity' rather than stating plainly that it returns activity records spanning documents in a workspace. The phrase does differentiate it from per-document siblings like get_document_activity, but the actual output (what an 'activity' item is) is never stated.

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

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

'Only use on an explicit owner request' and 'Do not silently dump account-wide personal data' give an explicit precondition and an explicit prohibition, which is stronger guidance than most read tools. It stops short of naming the alternative (e.g. get_document_activity) for single-document lookups, but the 'cross-document' framing implies the boundary.

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), so the bar is lower, yet the description adds real value beyond them: role-dependent content (only admins receive pending invitation metadata) and an explicit data-exclusion guarantee ('invitation tokens and delivery payloads are never returned'). These are behavioral traits the 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?

Three short sentences, each carrying distinct information (subject, role-gating, data exclusion), with the main action front-loaded. No filler or redundancy.

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

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

For a single-parameter read tool with full annotation coverage and no output schema, the description is largely sufficient: it explains what is read, who sees what, and what is withheld. It stops short of noting whether pagination or workspace-membership is required to obtain the roster.

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

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

Schema description coverage is 0%, so the description must compensate for the single workspace_id parameter, but it only alludes to a 'selected workspace' without adding format, sourcing, or constraints. The uuid type and pattern live entirely in the schema, leaving the description adding almost nothing on this dimension.

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

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

The description states a specific verb and resource ('Read the selected workspace roster'), which an agent can contrast with get_workspace_activity or invite_workspace_members without opening a schema. It does not explicitly name sibling tools, but the resource scope is clear 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?

Usage is implied by 'read the selected workspace roster' and the mention that only admins see pending invitation metadata, but there is no explicit when-to-use guidance or named alternative for related reads like get_workspace_activity. The agent must infer the selection condition from 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 establish the write/idempotent/non-destructive profile, and the description adds genuine context on top: invitees join as Members only after verifying their email, admins manage roles and removal, and the caveat 'Queued does not mean delivered' flags asynchronous delivery. It stops short of stating required permissions or rate limits, but adds real value beyond 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?

Front-loaded with the core action and outcome, then supporting constraints; five sentences with little filler. The 'No workspace creation or document move is needed' sentence is slightly indirect but earns its place by scoping the operation.

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 with no output schema and sparse parameter documentation, the description covers membership outcome, the verification step, and delivery caveat, but omits return/result shape, error behavior, and the purpose of the idempotencyKey — an important gap given the required parameter.

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

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

Schema coverage is low (25% — only confirm is documented), so the description must compensate. It contributes the 20-email cap and the conditional need for a shared-library ID, but only 'confirm' is explained in the schema and the description's 'library ID' wording does not clearly map to the schema's 'workspace_id', leaving emails and idempotencyKey semantics unexplained.

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

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

States a specific verb and resource — inviting people to view/manage the briefs already in the account — plus an outcome (reader activity, leads). It gestures at its scope distinct from a workspace invite ('No workspace creation or document move is needed'), but never names or contrasts the close sibling invite_workspace_members, so sibling differentiation is only implied.

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

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

Usage is implied rather than stated: the scope note and 'An explicit library ID is only needed for another shared library' hint at when an ID is required, but there is no explicit when-to-use / when-not-to-use guidance and no routing between this and invite_workspace_members.

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

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

Annotations declare non-readOnly, idempotent, open-world, non-destructive operation. The description adds crucial behavioral detail beyond annotations: invitees gain manage/publish/change sharing/delete rights across the selected library, including account briefs, plus delivery semantics ('Queued is not delivered'), seven-day link expiry, and verified-email requirement.

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

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

One dense paragraph that front-loads the admin restriction and core action before permission scope, prerequisites, and delivery details. Every sentence carries operational weight and nothing is wasted.

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

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

For a high-stakes invitation mutation with no output schema, the description covers permission scope, prerequisites, delivery semantics, and expiry well. The main gap is the unexplained workspace_id and idempotencyKey parameters, but annotations and schema cover types, so it is largely 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 only 25%, so the description must compensate. It adds the 20-email limit and implies the confirm requirement through 'explicit user request' and 'Explain before sending', but never explains workspace_id or the required idempotencyKey, leaving critical invocation parameters undocumented.

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

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

States a specific action: email up to 20 addresses to join the team as Members, with admin restriction and library-level scope. It distinguishes itself through role and permission details, though it never explicitly names a sibling alternative such as invite_team.

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?

Specifies prerequisites clearly: 'Admin only', 'Requires explicit user request naming recipients and the selected brief library', and an instruction to explain scope before sending. It gives strong context for when the tool is appropriate, but does not explicitly compare against alternatives like invite_team or resend_workspace_invitation.

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 (destructiveHint=true, idempotentHint=true), it discloses data-retention behavior ('briefs stay with the team'), an operational precondition ('Last admin must first promote someone else'), and a non-obvious billing consequence that would otherwise be a surprise. It also directs the agent to explain continued billing before confirming.

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

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

Four short, front-loaded sentences with no filler; the core action leads and the caveats follow. Efficient, though the billing sentence could be tightened.

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

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

For a destructive, non-idempotent-scope mutation tool with no output schema, it covers the critical safety and billing nuances an agent needs. Remaining minor gaps concern workspace_id semantics, which the schema partly carries.

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 50%: workspace_id is documented only by its UUID format in the schema, while confirm carries a schema description. The phrase 'Explain continued billing before confirmation' adds some intent to the confirm flag, but the description does not fully compensate for the undocumented half.

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

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

The description uses a clear verb and resource: 'Remove your team access,' which precisely conveys that this is a self-leave operation. It implicitly distinguishes from remove_workspace_member by the possessive 'your,' but does not name any 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?

It provides meaningful conditions and prerequisites: the last-admin case must promote someone first, and funding-account holders are warned billing is not cancelled. Alternatives are not named, so it falls 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?

Annotations already cover read-only/safe/non-open-world, so the bar is lower, and the description adds genuine traits beyond them: search is literal title matching (not fuzzy), the limit ceiling of 50, and cursor semantics including expiry and restart. Return payload shape is not described, but that is minor 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?

Four tight sentences, scope front-loaded, each segment carrying distinct information (scope, filters, limits, pagination). No filler.

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

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

For a zero-required-param list tool with read-only annotations and no output schema, it covers scope, filters, limits, and pagination adequately. Enum values and the return shape are left to the schema, which is acceptable given no output schema exists.

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?

With 0% schema coverage the description carries the burden and mostly succeeds: it gives meaning to workspace_id, search (literal title), status, sort, limit (default 25, max 50), and cursor behavior. The only flaw is naming the cursor parameter 'nextCursor' while the schema calls it 'cursor', a small mismatch that could confuse an agent.

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 ('Find documents') plus scope: personal workspace by default, team via workspace_id. This separates it from get_document (single) and list_workspaces, though it does not name any 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?

Gives clear usage context: it lists personal documents by default and team documents when workspace_id is supplied, and describes the pagination continuation path. No explicit alternatives or exclusions are named, 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful detail that a role (Admin/Member) is returned and that workspace defaults do not shift with dashboard selection, but says nothing about ordering, pagination, or auth requirements.

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

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

Purpose is front-loaded in the first sentence and the whole thing is three tight sentences. The latter two sentences address workspace defaulting, which is related context but sits slightly outside the tool's own behavior.

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

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

For a zero-parameter, read-only list tool with annotations covering safety and no output schema, the description is nearly complete. It tells the agent what it gets back (workspaces plus role) and how workspace scoping defaults behave 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies no filtering or scoping inputs are needed.

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

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

The description states a specific verb (List) and resource (personal and team workspaces you currently belong to) and clarifies the returned payload (your Admin or Member role). This clearly separates it from siblings like get_workspace_team, get_team_members, and list_documents without needing to name them.

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 explains the defaulting rule for document creation/listing and dashboard selection, which is useful ambient context, but it never states when to call this tool instead of an alternative such as get_workspace_team or get_team_members. Usage is implied rather than directed.

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 destructive=true, idempotent=true, and openWorld=true. The description adds a genuinely non-obvious behavioral note — that app-only execution prevents model context disclosure while the host still sees requests. However, it never clarifies which of the six actions are reads versus writes, so the destructive flag's applicability per action remains opaque.

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 text is short, but the first sentence is a comma-spliced fragment list rather than a front-loaded statement of function, and the second sentence's app-only/host remark is tangential to invoking the tool correctly. Size is fine; structure and load-bearing value are weak.

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?

This is a high-complexity tool: six actions, a nested patch object, two required parameters, zero schema descriptions, and no output schema. The description omits action-specific behavior, conditional parameter requirements, and mutation semantics, leaving substantial gaps an agent must fill by guessing.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it largely does not. It hints at reader controls, activity/leads, and alerts, which gesture at the action enum, but says nothing about id, patch (passcode, expiresAt, captureFields), cursor, or enabled, nor which parameters apply to which action. Two required parameters are effectively undocumented.

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

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

The description names the domains the tool covers (reader controls, activity/leads, alert preferences), which loosely maps to the action enum, but it never states a verb+resource and reads as a fragment list. It also fails to distinguish this tool from siblings like get_document_activity, get_document_leads, get_document_alerts, get_document_reader_settings, and update_document_alerts, which cover the same ground. An agent cannot tell from the text how this differs from those.

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

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

There is no explicit when-to-use guidance and no alternatives are named, despite at least six sibling tools overlapping with these actions. The only quasi-contextual statement is about app-only execution, which is not a use-selection criterion. The agent is left to infer trigger conditions entirely.

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

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

Annotations already mark this destructive, non-idempotent, open-world, but the description adds the substantive consequences: all team members gain internal management and activity access, an explicit confirmation step is required, current revision is enforced, and reader URL and external access settings are preserved. This is exactly the beyond-annotation context an agent needs before a destructive move.

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 and resource, then ordered by consequence, prerequisite, and exclusion with no filler. The sentences are dense but each carries distinct information; only minor tightening is possible.

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

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

For a destructive, four-required-param mutation with no output schema, the description covers impact scope, confirmation requirement, revision requirement, preserved settings, and unsupported cases. Nothing an agent needs to invoke it safely 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 low at 25% (only 'confirm' is documented), yet the description compensates by implying the role of each remaining argument: the personal brief (document_id), the Admin team (workspace_id), the concurrency guard ('Requires current revision' → expectedRevision), and the confirmation gate. It does not spell out formats or constraints explicitly, so it does not fully close the gap.

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

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

States a specific verb and resource ('Move an explicitly selected personal brief you created into a team') with the qualifying scope ('where you are Admin'). No sibling tool performs this personal-to-team move, so an agent can distinguish it immediately.

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

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

Gives clear preconditions ('personal brief you created', 'Admin' in the target team) and a hard exclusion for unsupported directions ('does not move team briefs back to personal or transfer file funding'). It stops short of naming an alternative tool for those excluded cases, so it is strong context rather than full when/when-not/alternatives routing.

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

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

Adds substantial behavior beyond the annotations: sign-in requirements per mode (public vs verified/specific-email), that dashboard reader controls may apply in every mode, and that publishing does not send invitations. It clarifies the openWorld/exposure implications that the destructiveHint=true annotation only gestures at.

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

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

Front-loads the trigger and core action, then layers mode/sign-in caveats in a logical order. It is dense and runs long, but each sentence carries a distinct behavioral fact rather than filler.

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

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

An output schema exists and annotations already carry the safety/idempotency profile, so the description need not explain return values. Given the multi-mode publishing complexity, the description supplies the mode and sign-in context an agent needs to call 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 the single 'id' parameter is fully documented in the schema (UUID of an existing owned document). The description adds no syntax or format 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+resource ('Publishes the document at its stable unlisted link') and its scope ('existing SharedBrief draft'), which is enough for an agent to distinguish it from unpublish_document and the reader-settings siblings 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?

Opens with an explicit trigger ('Use when the user wants a shareable link to an existing SharedBrief draft'), names an exclusion ('does not email recipients or send invitations'), and routes the agent to alternatives ('use the dedicated reader-settings and explicit-request activity/lead tools to manage these controls').

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 readOnly/idempotent/non-destructive/closed-world, so the description is freed to add genuinely new context: per-call authorization checks on the document and revision, host-visible requests, and bytes being excluded from model context. Those are meaningful operational and privacy traits not derivable from annotations. It stops short of explaining return shape or failure modes on authorization denial.

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

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

Three terse sentences, each carrying distinct information (scope, authorization, output handling), with the scope constraint front-loaded. The telegraphic style is efficient and free of waste, though the dropped articles make it slightly harder to parse than it needs to be.

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 three-parameter tool with zero schema description coverage and no output schema, the description leaves too much unsaid: it never explains how to supply id/revisionId/index, how to detect the end of the file versus the 320-chunk bound, or what is actually returned when bytes are excluded from context. The authorization and host-visibility notes are useful but not sufficient.

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

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

Schema description coverage is 0% for all three required params (id, revisionId, index), so the description must compensate and largely does not. The word 'chunk' plus the schema's index max of 319 faintly implies index is a chunk offset, but id and revisionId are never explained and no usage relation between them (revision-scoped read) is stated.

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 phrase 'App-only bounded owner file chunk' conveys the resource (owner's original file, read in bounded chunks) and the restricted context (app-only), but it is a noun phrase rather than a verb+resource statement, and it never contrasts itself with the sibling read_document_for_app. An agent can guess it fetches raw file bytes rather than document content, but not confidently.

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

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

No when-to-use guidance or alternatives are given. 'App-only' hints at a context restriction but the description never says when this is preferable to read_document_for_app, nor what happens if called outside the app 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 readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the freshness nuance of "latest," and says nothing about what "owner document" means or what happens when no document exists. With annotations carrying most of the burden, this is adequate but thin.

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

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

A single, front-loaded sentence with no filler or repetition. Brevity is appropriate, though it is under-specified rather than maximally efficient.

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

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

With no output schema, the description carries responsibility for describing what is returned (document body? metadata? which fields?), and it does not. The meaning of "owner document" and its relationship to the embedded app remain unexplained.

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

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

Schema description coverage is 0% for the single required 'id' parameter, so the description must disambiguate it — yet it never says whether the id is a document id or an app id. Combined with "owner document," this leaves the caller guessing what entity they are addressing.

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?

It states a verb (read) and a resource (document) scoped to an embedded app, which is more than a tautology. However, "owner document" is opaque, and nothing distinguishes it from siblings like get_document, show_document, or get_document_sharing — an agent cannot tell which read variant applies.

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

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

There is no when-to-use guidance and no mention of alternatives despite thirteen sibling document tools. The phrase "for the embedded app" hints at a context but never states the condition under which this tool is preferred over get_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 flag destructiveHint=true and idempotentHint=true, but the description adds genuinely non-obvious context: the removal is immediate, team briefs are preserved, the last-admin case is blocked, and external recipient/billing state is untouched. That blast-radius description is exactly what a destructive tool needs and goes beyond the annotation flags, though it does not address reversibility/re-invitation.

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

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

Four short clauses, with the hard constraint ('Admin only') front-loaded and no redundant restatement of the tool name or title. Every sentence carries a distinct fact.

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

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

For a 3-required-param destructive tool with no output schema, the description supplies the constraints and effect scope an agent needs, and annotations cover the safety profile. The one real gap is parameter identification, which the schema only partly documents.

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

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

Schema description coverage is only 33% — user_id and workspace_id carry no descriptions, and confirm's description is in the schema rather than the description text. The description contributes no parameter-level meaning (no format, no identification of what user_id/workspace_id must reference), so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('remove this person's internal team access') and scope-limits itself against adjacent operations by noting what it does not touch (external recipient permissions, billing responsibility). It does not name siblings such as update_workspace_member_role or leave_workspace, so the agent must still infer the boundary, but the resource 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?

Gives a clear precondition ('Admin only') and an explicit prohibition ('Cannot remove the last admin'), which is real when-to-use guidance for a destructive call. It does not route the agent to alternatives (e.g. leave_workspace for self-removal, update_workspace_member_role for role changes), so it stops just 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?

Adds substantial information beyond the annotations: what is preserved (original file revision, reader URL, publication and access settings) and the failure mode (stale revision is rejected), which explains the non-idempotent, concurrency-checked behavior. It does not reconcile destructiveHint=true or say whether the rename is recorded/applied as a new revision, so it stops short of full disclosure.

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

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

Three sentences, no filler, front-loaded with the action and scope before prerequisites and preservation guarantees. Every sentence earns its place.

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

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

For a single-field mutation with no output schema, it covers prerequisite, preservation semantics, and the rejection case, while annotations carry the safety profile. Missing only minor details such as whether the change bumps the revision or how an invalid title is handled.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does explain expectedRevision ('requires the current content revision', stale values rejected) and implies id by 'owned document'. The id format and the title's 160-char bound are left entirely to the schema, so compensation is partial.

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 precise verb+resource ('Change only the title of an owned document') and immediately scopes it against the general-purpose sibling by saying only the title changes, in any supported format including imported originals. An agent can distinguish this from update_document 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?

Gives clear preconditions: the document must be owned and the caller must supply the current content revision. The 'only the title' scoping implicitly routes other edits to update_document, but that alternative is never named, so usage is inferred 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?

Adds real signal beyond the annotations: it discloses that earlier links stop working (concrete consequence of the destructiveHint), that this is an admin-gated operation, and that queuing an email is not proof of delivery. It stops short of stating error behavior when the invite is already accepted or already-delivered email handling.

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

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

Three short sentences, zero filler, with the access restriction front-loaded and the link-invalidation consequence placed before the caveat about delivery.

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 required-confirm mutation with no output schema, it covers the key side effect and the delivery caveat, but omits what a caller gets back, how to find the invitation, and what happens if the invitation state has changed since listing. Adequate but with clear gaps.

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

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

Schema coverage is only 33% — only 'confirm' is documented; workspace_id and invitation_id carry just UUID patterns. The description never mentions any parameter, so with two undocumented parameters and low coverage it fails to compensate.

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

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

Names a specific verb (replace/resend) and resource (invite link) and scopes it to 'existing pending or expired' invitations, which separates it from invite_workspace_members and revoke_workspace_invitation. It never names those siblings, so the differentiation is implied rather than explicit.

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

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

The 'existing pending or expired' qualifier implies when this tool applies, but there is no explicit guidance on when to use it versus revoke/re-invite, no prerequisites beyond 'Admin only', and no hint on how to obtain the invitation_id.

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, and the description adds genuinely new behavior: the admin-only authorization requirement, that queued delivery is cancelled, and the important nuance that an already-submitted provider message cannot be recalled though its link stops granting membership. That partial-irreversibility detail is exactly the kind of context annotations cannot convey.

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 the authorization constraint front-loaded and the destructive caveat last. Every clause earns its place; no filler.

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

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

For a destructive mutation with annotations covering safety and no output schema, the description is largely complete: it explains the action, the admin gate, and the delivery nuance. The remaining gap is that the two UUID parameters are undocumented, though their names make intent inferable.

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

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

Schema description coverage is only 33% — only 'confirm' is documented, and workspace_id/invitation_id carry format/pattern but no prose. The description mentions 'pending invitation' but adds no meaning about what the two UUID parameters identify, so it fails to compensate for the coverage gap.

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

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

Specific verb ('invalidate') plus resource ('pending invitation') with added scope ('cancel queued delivery'). An agent can distinguish this from resend_workspace_invitation, invite_workspace_members, and remove_workspace_member without opening any schema.

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

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

'Admin only' supplies a clear prerequisite, which is more than most definitions offer. However, it never states when to choose this over resend_workspace_invitation or remove_workspace_member, so the when-not/alternatives guidance is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description usefully adds that writes are revision-matched and that already-published documents are updated in place rather than forked to a new link. It does not say what happens on a revision mismatch or whether existing content is fully replaced, which matters for a destructive write.

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

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

Two short sentences, with the core action front-loaded and the published-link consequence second. No filler, though the second sentence could have carried more useful detail in the same space.

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

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

A destructive, non-idempotent write with three required parameters, no parameter documentation, and no output schema needs more than two sentences. Failure semantics for a stale revision, content replacement behavior, and required authorization are all 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 description coverage is 0% across three required parameters. 'Revision matching' hints at the meaning of expectedRevision but never states that it must equal the current server revision or what a mismatch does. The 'id' target and the two distinct content shapes (block array vs static HTML) 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 ('Save document content') and adds the revision-matching qualifier, so the agent knows this is a content-write, not a metadata update. It does not distinguish itself from the sibling update_document or explain the title's SharedBrief framing, 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 statement of when to use this tool versus the obvious alternatives (update_document, publish_document, create_document). The note that published documents update at their existing link is a behavior, not a when-to-use rule or precondition.

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 real context: it is a full replacement of prior access settings and the recipient allowlist, changes apply immediately for published documents, it neither publishes drafts nor sends invitations, and it deliberately returns no individual reader emails. That is the kind of side-effect and return-scope disclosure 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?

The trigger and mode semantics are front-loaded and earn their place, but the middle-to-late portion drifts into dashboard features (pre-view name/email/phone capture, passcodes, expiration) and repeats mode caveats already present in the schema. Several of these sentences are tangential to invoking this specific tool, so the definition is longer than needed.

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

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

For a 3-parameter mutation tool with no output schema, the description covers side effects, immediate effect timing, scope of replacement, and what is not returned, which is more than adequate. It stops short of only trivial detail, and the mode/email specifics live in a fully-covered schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description still earns credit: it explains that public mode allows anyone with the link while verified/specific require a verified sign-in, and that 'emails' is an allowlist that fully replaces the previous list rather than a lead report. The 50-item cap and per-mode requirement are left to the schema, so it is not a full 5.

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 concrete trigger plus the three access outcomes it sets (link-anyone, sign-in-required, listed-emails), which is a specific verb+resource statement. It is clearly separable from get_document_sharing, update_document_reader_settings, get_document_leads and publish_document because it names what it does not do (no publishing, no invitations, no email reporting).

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 states when to use it ('when the owner wants to make a document accessible...') and when not to ('Does not publish a draft or send invitations'), and it routes the agent elsewhere for adjacent concerns by naming the dedicated reader-settings and explicit-request activity/lead tools. The only minor softness is that the alternatives are named by category rather than by exact 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully adds that the output is an in-conversation viewer/editor rather than raw data, but it never clarifies whether edits made in that editor persist or how they are saved, a meaningful ambiguity for a tool whose description includes 'edit'.

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

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

Two tight sentences with no filler, but the when-to-use trigger is front-loaded while the actual action (what the tool does) is deferred to the second sentence. Swapping them would make the purpose scannable first.

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

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

For a one-parameter tool with rich annotations and no output schema, the description covers the trigger and the mechanism adequately. The remaining gap is the fate of edits made through the embedded editor and whether the tool returns any confirmation or document payload.

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?

There is a single parameter with 100% schema description coverage, including UUID format and ownership scoping, so the schema carries the semantics. The description adds nothing about the id beyond 'an existing SharedBrief document', which is the expected baseline when the schema is already complete.

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 second sentence states the concrete action: it opens an embedded viewer/editor for a SharedBrief document, which tells an agent this is a UI-facing display tool rather than a data fetch. It does not, however, explicitly distinguish itself from sibling read tools such as get_document or read_document_for_app, leaving that inference to the agent.

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 a clear trigger condition (user wants to preview, review, or manually edit an existing document inside the conversation), which is genuinely actionable. It stops short of naming alternatives or exclusions, e.g. when to prefer get_document for programmatic retrieval or read_document_for_app for app consumption.

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?

Despite the annotations already declaring read-only, non-destructive, idempotent behavior, the description adds substantial behavioral context: the chat host processes transfer requests, file bytes stay out of model context, private PDF/image/HTML import is supported, and host acceptance is verified separately. It also warns that an external dashboard link alone is not full in-chat transfer, which is useful operational detail.

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

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

The description is front-loaded with the core action, followed by three efficient sentences covering privacy behavior, supported formats, and a verification caveat. Every sentence adds relevant information without repetition or padding.

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

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

For a zero-parameter tool with annotations covering safety and idempotency, the description is largely complete: it explains the embedded chooser, model-context isolation, supported formats, and acceptance verification. The main gap is that it does not describe the relationship to sibling import workflow tools such as begin, complete, cancel, or transfer_document_import_from_app.

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

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

The tool has zero parameters, so there are no parameter names, types, or defaults for the description to clarify. With 100% schema coverage and no parameters, the baseline of 4 is appropriate; the description does not need to compensate for parameter semantics.

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

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

The description uses a specific verb and resource: 'Open the authenticated embedded file chooser' for in-chat document import. It clearly states the supported private import types and distinguishes in-chat transfer from an external dashboard link, but it does not explicitly differentiate this tool from sibling import tools such as begin_document_import or transfer_document_import_from_app.

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

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

The description implies the tool is for opening an embedded file chooser during in-chat import, but it gives no explicit when-to-use guidance, prerequisites, or alternatives. It mentions that an external dashboard link alone is not full in-chat transfer, but this caveat does not tell an agent when to choose this tool over the many sibling import tools.

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

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

Annotations already declare destructive=true, idempotent=true, and openWorld=true. The description adds two useful non-annotation facts: the operation is app-only authenticated and bytes are excluded from model context/results. However, it says nothing about the begin/chunk/status/complete/cancel action lifecycle, which is the core behavioral model of this tool.

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

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

Two short sentences are front-loaded, but for a 6-parameter, multi-action import tool this is under-specification rather than effective conciseness. The brevity leaves core semantics unexplained.

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 complex destructive, idempotent, multi-action tool with no output schema and 0% schema coverage, this description is grossly incomplete. An agent cannot determine the correct action sequence, required parameters per action, or expected behavior from either the description or the schema.

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

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

Schema description coverage is 0% across 6 parameters with nested objects and a 7-value action enum. The description mentions none of them, so the agent gets no help understanding the action lifecycle, source kinds (upload/url), replace semantics, or size bounds beyond what the raw schema shows.

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?

"App-only authenticated bounded import transfer" largely restates the tool name (transfer_document_import_from_app) without clarifying what the operation actually accomplishes. It never says this is a multi-step document import flow, nor distinguishes it from siblings like begin_document_import or complete_document_import.

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 invoke this tool versus the many import-related siblings (begin_document_import, complete_document_import, get_document_import_status, cancel_document_import). The reader cannot tell whether this is the entire flow, one step, or an alternative path.

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 destructiveHint=true; the description goes further by explaining what actually happens: reader access is removed immediately, the document is retained privately, republishing needs a slot or Plus, and copied/downloaded content may remain. This is rich behavioral context beyond the annotation, including an important warning about over-limit Free owners.

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 front-loaded with the core purpose, followed by the key behavioral effects and the Free-plan warning. Every sentence contributes useful guidance without repetition.

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

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

For a single-parameter mutation tool with annotations already covering safety, the description adds enough context about outcomes, republishing constraints, and residual access to let an agent invoke it correctly and warn appropriately.

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?

There is only one parameter, whose schema description coverage is 100%, so the schema already fully documents the 'id' field. The description adds no parameter-specific detail beyond the schema, which is acceptable given the baseline of 3 for high coverage but leaves no extra value.

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

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

The description states a specific verb ('withdraw') and resource ('a published document'), clarifies the resulting state ('retaining it privately'), and distinguishes the tool from the sibling publish_document (which handles the reverse action) and delete_document (which removes the document entirely).

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 states when to use it ('when the owner wants to withdraw a published document from readers') and mentions that republishing uses the same link. It doesn't explicitly name sibling alternatives, but the context of reader access removal makes it obvious.

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

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

Goes well beyond the annotations: content is fully replaced, a matching revision is required to prevent stale overwrites, published edits hit the existing reader link immediately, access settings are preserved, and no invitations are sent. This is exactly the mutation-impact context the destructiveHint/openWorldHint flags do not convey. The trailing "No external dependencies or network actions" is worded like a tool-level claim even though it means the HTML payload, which slightly muddies the openWorldHint: true signal.

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

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

Front-loads the trigger correctly, but runs to nine sentences and repeats material the schema already states verbatim (format html with mode omitted, static rejects scripts, blocks for structured text). The content-format sentences could be cut 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?

Strong on side effects and content formats, but with no output schema the description never says what the call returns — the new revision value in particular, which the agent needs to chain another update. For a destructive, revision-gated mutation that is a real gap.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by explaining the expectedRevision semantics ("the latest document revision is required to prevent stale overwrites") and by disambiguating the two content shapes: html format with mode omitted for interactive, static only for explicit static requests, blocks for text-only 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+resource ("revise an existing SharedBrief document") plus the key constraint "Replaces its content" and the invariant "without changing its shared link". That implicitly separates it from create_document, rename_document and publish_document, but no sibling is named, so the agent still has to infer the boundary.

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 when the user wants to revise an existing SharedBrief document" is a clear trigger condition with concrete examples (proposal, report). The revision-precondition ("the latest document revision is required") tells the agent when it is not yet safe to call. There is no explicit statement of when to prefer rename_document or publish_document 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 this as an idempotent, non-destructive write. The description goes well beyond them by disclosing plan requirements (Plus), delivery-availability preconditions, membership verification, and that the acting teammate is not subscribed. This is exactly the extra context annotations cannot carry.

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, zero filler, action front-loaded in the first clause. Each sentence adds new information: precondition, exclusion, side-effect scope.

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 boolean toggle with no output schema, the description covers behavior, preconditions, and non-effects thoroughly. The remaining gap is parameter-level detail, particularly what the 'id' refers to, which the schema does not supply.

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

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

Schema description coverage is 0% for both parameters, so the description must compensate. It conveys that 'enabled' toggles view email alerts and implies 'id' is a document identifier via 'per-document', but never confirms the id is a document UUID or explains request/response semantics for either field.

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 pair (enable/disable) and a precise resource (per-document view email alerts to the workspace paying account), plus explicit negative scope. An agent can distinguish this from get_document_alerts and update_document_reader_settings 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?

Clearly states preconditions: enabling requires Plus and available email delivery, the paying account must remain a verified workspace member, and disabling is allowed after downgrade. It also rules out adjacent behaviors (personal alerts, publication, sharing), but never names a sibling tool as the alternative for those 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?

Adds substantial context beyond the annotations: patch merge semantics (omitted fields unchanged, null clears only the named field), tier gating for passcode/expiry, and a security model for passcode entry. Consistent with destructiveHint=true (null clears fields) and idempotentHint=true (repeatable patch).

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 patch semantics and scope exclusions, then the security guidance. Most sentences earn their place, though the passcode-security block repeats the 'host receives it' point across the embedded-entry and app-only sentences.

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

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

No output schema or annotation covers the safety/security dimension, so the description rightfully supplies patch semantics, tier limits, and passcode handling. It leaves captureFields behavior undocumented, which is the main gap for a 0%-coverage nested 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 0% and the patch object is nested, so the description must carry the load. It explains the omit/null semantics that govern every field and details passcode and expiry behavior, but never mentions captureFields (name/email/phone) or what its enum values or null mean.

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 ('Patch reader settings only') and immediately distinguishes itself from siblings by exclusion ('Does not publish or change sharing recipients'), routing the agent away from publish_document and set_document_sharing. The read counterpart get_document_reader_settings is implicitly differentiated by 'Patch'.

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 when-not guidance (no publishing, no sharing-recipient changes) and explicit prerequisites for passcode/expiry mutations (Plus required, downgrade rules). However, it never names the sibling tools to use instead when it declines those operations, so routing is left to inference.

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

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

Annotations already declare non-destructive, idempotent, closed-world behavior, so the bar is lower. The description adds real value beyond them by disclosing the admin permission requirement and by enumerating what is NOT affected (membership, document links, billing), which prevents an agent from assuming side effects.

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

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

Three short sentences with the most important constraint ('Admin only') front-loaded, followed by the action and then the scope limits. Every clause earns its place and nothing is padded.

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

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

For a two-parameter mutation with no output schema, the description covers the safety-relevant essentials: permission requirement and non-effects. It stops short of describing the response or failure behavior on an over-length name, which is a minor gap rather than a blocking one.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It clarifies that `name` is a display name and that `workspace_id` identifies the target workspace, but it omits the 80-character limit and any format expectations, so it only partially compensates for the undocumented 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 ('Change the workspace display name') and immediately bounds the scope by excluding membership, document links and billing. This distinguishes it from siblings like update_workspace_member_role, rename_document, and create_workspace without needing to open any schema.

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

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

'Admin only' supplies a clear precondition for use, and the exclusion list implicitly tells the agent this is not the tool for membership changes. However, it never names an alternative tool or states positively when to prefer this over e.g. rename_document, so guidance remains implied rather than explicit.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description goes beyond them with a real business rule ('the last admin cannot be demoted'), the authorization requirement, and the blast radius ('takes effect in web and MCP'). It does not say what the response looks like or what happens when the last-admin guard trips, so it stops 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 constraint that matters most ('Admin only') followed by the action, and each sentence carries information. Four short sentences with no filler, though the closing web/MCP sentence is tangential to invocation.

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

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

For a destructive 4-required-param mutation with no output schema, the description covers authorization, target role semantics, and the key guard condition. It leaves failure behavior and the confirm workflow unstated, which is a minor gap given the schema documents confirm.

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

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

Schema coverage is only 25% – only 'confirm' is documented in the schema. The description clarifies the meaning of the two role values (admin gets invite/remove/manage rights; member is the baseline), but says nothing about user_id or workspace_id scope, so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource ('Promote a member to Admin or demote an admin to Member') and enumerates the only two target states. An agent can immediately separate it from invite_workspace_members or remove_workspace_member, which change membership rather than role.

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?

'Admin only' gives an explicit prerequisite and the promote/demote framing makes the use case clear, but no alternative tool is named and no exclusion ('use remove_workspace_member to revoke access entirely') is offered. Clear context, no routing guidance.

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