Create, share and track client-facing proposals, project updates and decision briefs from selected AI work. Publish stable links with controlled reader access and view visits and approximate reading activity. Connect through an OAuth-authenticated remote MCP server.
Scored across 13 tools
Most tools are distinct, but several pairs overlap: read_document_for_app vs get_document, save_document_from_app vs update_document, and show_document vs get_document all touch the same resource with only contextual differences. Descriptions clarify the embedded-app vs general distinction, but an agent could still misselect.
All 13 tools follow a clean snake_case verb_noun pattern (create_document, delete_document, publish_document, set_document_sharing, etc.), with multi-word variants still readable and consistent.
13 tools is well within the ideal range and each appears to earn its place, covering create/read/update/delete/lifecycle, sharing, stats, and app integration without obvious padding.
Core lifecycle (create, get, update, delete, list), publishing (publish/unpublish), sharing (get/set), and stats are all covered. Minor gaps exist, such as no search/filtering over documents or granular per-recipient sharing management, but agents can work around these.
Create a private draft from selected content. The draft remains private until it is published. Supports structured text blocks or responsive static HTML/CSS documents with format html and mode static. Static HTML supports self-contained styles and body markup; viewport and security metadata are added by SharedBrief. Scripts, event handlers, images, SVG, external dependencies, forms, and meta elements are unsupported.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| idempotencyKey | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description's real contribution is the content-handling behavior: the draft remains private until published, static HTML must be self-contained, viewport/security metadata is injected, and scripts, handlers, images, SVG, externals, forms and meta are rejected. That is meaningful operational context for a write tool, though it says nothing about auth or the idempotency behavior beyond the hint.
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 privacy semantics, then the format options, then the unsupported-element list. Dense but every sentence carries information; the restrictions sentence is long but 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 2-parameter creation tool with no output schema, the description covers the content contract and hard limitations well. The remaining gaps are the undocumented idempotencyKey and no hint about what is returned (e.g. a document id) for the subsequent update/publish flow.
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 explains the two content variants and the format/mode='static' pairing, which is genuinely useful. However, the required idempotencyKey parameter is never addressed, leaving an agent to guess its purpose and expected 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 gives a specific verb and resource ('Create a private draft from selected content') plus the two supported content shapes (text blocks vs static HTML/CSS). It implies the draft/publish lifecycle that distinguishes it from publish_document and unpublish_document, but 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?
Usage is implied: you call this to make a new private draft that stays private until published. There is no explicit when-to-use/when-not guidance and no routing to update_document for edits or publish_document for release, so the agent has to infer the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a brief and its associated view records. The confirmation parameter must be true.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| confirm | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds genuine context: deletion is permanent and cascades to associated view records. It also flags the confirm=true guard, which is the key behavioral gate for invoking 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?
Two short sentences, front-loaded with the irreversible action and cascade effect. 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 two-parameter mutation whose safety profile is already covered by annotations, the description supplies the two missing facts an agent needs: permanence and the cascade to view records. It stops short of failure semantics or permission requirements, but nothing essential to a correct call is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the parameter burden. It only restates the confirm constraint that the schema already enforces via const:true, and says nothing about what 'id' identifies (the brief's UUID) or the consequences of an unknown/invalid id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ('Permanently delete a brief') and adds the cascade scope ('and its associated view records'), which distinguishes it from read/update siblings. The only nit is the naming mismatch between the tool id (delete_document) and the description's term 'brief', but intent 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?
No statement of when to use this vs. alternatives, no prerequisites about ownership/permissions, and no warning about irreversibility beyond the word 'permanently'. The only usage note (confirm must be true) is already enforced by the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve one of your briefs, including its content and current revision.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context by naming what is returned (content and current revision), which partly compensates for the absent output schema, but says nothing about permissions or scoping.
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 front-loaded sentence with no filler; the retrieval action and returned content lead the statement. It is efficient, though minimal rather than exemplary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only, single-parameter tool, the description is adequate and even hints at the return shape despite no output schema. It still omits any error behavior (e.g., not-found handling) and gives no routing against similar read siblings.
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 description never mentions the 'id' parameter, so it adds no format or constraint detail. The single required uuid id is largely self-evident from the tool's purpose, keeping this at a minimum-viable 3 rather than lower.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Retrieve one of your briefs') plus the payload scope ('content and current revision'), so the action is unambiguous. However, it does not differentiate from confusable siblings such as show_document, read_document_for_app, or list_documents, so an agent must infer the boundary itself.
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, no prerequisites, and no named alternative. With siblings like read_document_for_app and show_document in the same family, the description gives no help in choosing between them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve access settings and allowed recipient emails for one of your briefs. Only the owner can read these settings.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral detail the annotations lack - owner-only authorization - but says nothing about failure modes when called by a non-owner or about pagination/volume of recipient emails.
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, both load-bearing: the first defines what is returned, the second front-loads the authorization constraint. No filler or restated title content.
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-only getter with annotations covering safety and no output schema, the description covers purpose, returned content, and the owner precondition. Only edge-case behavior (non-owner errors, empty recipient list) is unaddressed.
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%, but the single 'id' parameter carries a uuid format and pattern in the schema itself. The phrase 'one of your briefs' implicitly identifies the parameter as a brief identifier, adding modest meaning, though no explicit format or sourcing guidance is given in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (retrieve) and resource (access settings and allowed recipient emails for a brief), which an agent can distinguish from set_document_sharing. It stops short of naming siblings explicitly, so it is clear but not maximally differentiated.
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 sentence 'Only the owner can read these settings' gives a precondition for use, but there is no guidance on when to call this versus set_document_sharing or get_document. Usage is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show approximate daily/browser views and aggregates for the most recent 100 visits. Visits are not unique people; active time is approximate. No reader emails are returned.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes further and discloses meaningful caveats: the sample is capped at the most recent 100 visits, visits are not unique people, active time is approximate, and no reader emails are returned - exactly the kind of data-quality/PII context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the purpose statement followed by the caveats. Every sentence conveys distinct information (scope of sample, non-unique visits, approximate time, no PII), with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining the return and does so reasonably: it names daily/browser views, aggregates, the 100-visit sample window, and the absence of reader emails. It stops short of describing the shape of the aggregates or the time window covered, which would have made it 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 0% and the single required 'id' parameter carries no description. The description never mentions the parameter, but given the sibling naming convention (get_document, delete_document) the identifier is easily inferred, so this is a minor rather than fatal 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 states a specific verb and resource: it shows views and aggregates, with the qualifying detail that they are daily/browser breakdowns. It implicitly targets a single document (matching the id parameter and the get_document_* sibling family), so an agent can distinguish it from get_document or list_documents, though it never literally names the resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use instruction and no mention of alternatives such as get_document or get_document_sharing. Usage is only implied by the word 'Show … views', which leaves the agent to infer that this is the analytics tool rather than a content-retrieval tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show up to 50 of your most recently created briefs.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: results are capped at 50 and ordered by creation recency. It omits pagination behavior and any default limit, which keeps it at a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence, front-loaded with the action and resource, with no filler. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with annotations covering safety and no output schema to explain, the description is nearly sufficient. The remaining gap is pagination/default-limit behavior, which is minor here.
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 'limit' parameter with 0% schema description coverage, so the schema explains nothing. The description partially compensates by naming the 50 maximum and implying a default ordering, but it never mentions that a limit parameter exists or what happens if it is omitted.
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 ('Show') and resource ('briefs') plus a scope ('most recently created', 'up to 50'), which is more than a tautology. It does not differentiate from close siblings like get_document or show_document, so it falls 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 indication of when to use this listing tool versus get_document/show_document, and no exclusions or prerequisites. Usage is only implied by the plural 'briefs'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish a brief at its stable unlisted link using its current access settings. Public links allow anyone; verified and specific-email links require verified sign-in.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
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 covered structurally. The description adds useful context on the access model (public vs verified vs specific-email links), but does not state reversibility or that existing access settings are reused rather than changed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the core action front-loaded and no filler. The access-model clause is a legitimate second sentence 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?
For a one-param mutation with no output schema, the description covers the action and link semantics, which is adequate. It leaves gaps on the target id, post-publish state, and how to undo, but annotations carry the risk profile.
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 'id' parameter, yet it only says 'a brief' and never clarifies that the id identifies the document to publish. The schema's uuid format/pattern is the only real guidance.
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 (publish) and resource (a brief) plus the scope ('at its stable unlisted link using its current access settings'). This clearly separates it from unpublish_document, though it does not name that sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description never says when to publish versus not, nor points to the inverse operation (unpublish_document) or prerequisites. The second sentence describes access behavior, not when-to-use guidance, so an agent gets little routing help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the latest owner document for the embedded app.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
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.
Save document content with revision matching. Published documents update at their existing link.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| content | Yes | ||
| expectedRevision | Yes |
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.
Replace access settings and the allowed recipient list for one of your briefs. Public allows anyone with the link; verified requires verified sign-in; specific requires a listed verified email. Changes take effect immediately for published briefs. Does not publish a draft or send invitations.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| mode | Yes | ||
| emails | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is partly covered. The description adds genuine value beyond them: "Replace" signals wholesale overwrite of the existing recipient list, "Changes take effect immediately for published briefs" discloses timing, and the publish/invite exclusions prevent false expectations.
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 mutation and its scope front-loaded, followed by mode semantics and then the negative constraints. No filler, no repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotation coverage of timing or side effects, the description supplies exactly the missing pieces: replacement semantics, per-mode behavior, immediate effect on published briefs, and the explicit non-actions. An agent has everything needed 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%, so the description must carry the burden, and it does for the important parts: it explains all three enum values of `mode` and clarifies that "specific" requires a listed verified email, which compensates for `emails` not being marked required in the schema. Only the `id` parameter is left unelaborated, which is self-evident.
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 ("Replace") and a precise resource ("access settings and the allowed recipient list") scoped to "one of your briefs." It is immediately distinguishable from the read-only sibling get_document_sharing and from publish_document, which it explicitly disclaims.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context: what each sharing mode means, that changes apply immediately to published briefs, and explicitly what the tool does NOT do (publish a draft, send invitations). It does not, however, name the counterpart tool for reading current settings, leaving that routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Display one of your documents in the embedded SharedBrief viewer and editor.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, destructiveHint=false, so safety and idempotence are covered by structured fields. The description adds the fact that it renders in an embedded viewer/editor, but says nothing about editor state, side effects, or whether opening is purely display.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence, front-loaded with the verb 'Display' and the resource 'document'. Nothing is wasted, though very little is included.
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 one required param, complete annotations, and no output schema, a one-sentence definition is barely adequate. The agent still cannot tell why it would choose this over get_document or read_document_for_app, which is a meaningful gap in completeness.
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% for a single 'id' parameter, which is already constrained to a UUID by schema format and pattern. The description adds no meaning about what the id refers to or how it is obtained; with one param the baseline is 3, so the score anchors there rather than rising.
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: 'Display one of your documents in the embedded SharedBrief viewer and editor.' That is more specific than a plain get, but the description does not differentiate it from get_document or read_document_for_app among the 13 document siblings, so it falls short of the 5 tier.
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. The phrase 'inside the embedded SharedBrief viewer and editor' implies a UI/embedding context, but with siblings like get_document and read_document_for_app present it is left to inference, and no alternative is named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove public access to a brief immediately. You can republish it later at the same link.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds real context beyond that: the effect is immediate, public access is revoked (not the document destroyed), and there is a restore path at the same link. It omits any permission/ownership requirement, keeping it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the effect front-loaded before the reversibility caveat. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, no-output-schema tool whose annotations already carry the destructive/idempotent profile, the description covers the core behavior and the recovery path. Missing only permission requirements and the return/confirmation behavior.
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 required 'id' parameter is completely undocumented in both schema and description. The description offers no guidance on which id is expected (document UUID) or whether it is the published document or version id. With low coverage the description should compensate, and it does not.
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 ('Remove public access to a brief') and a timing qualifier ('immediately'). It implicitly distinguishes itself from delete_document via 'You can republish it later at the same link', but never names the sibling tools, so the differentiation is inferential 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 reversibility note ('republish it later at the same link') implies when to choose this over delete_document, but there is no explicit when-to-use/when-not-to-use statement or named alternative. Usage is left to be inferred from the publish/delete siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace a brief's content while preserving its existing public link. Revision matching prevents stale overwrites. Supports structured text blocks or responsive static HTML/CSS documents with format html and mode static. Static HTML supports self-contained styles and body markup; viewport and security metadata are added by SharedBrief. Scripts, event handlers, images, SVG, external dependencies, forms, and meta elements are unsupported.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| content | Yes | ||
| expectedRevision | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructive=true, idempotent=false, openWorld=false-write behavior, and the description adds genuinely non-obvious traits: the public link survives the replacement, expectedRevision guards against stale overwrites, and static HTML has a precise support/unsupported boundary (no scripts, handlers, images, SVG, external deps, forms, meta). This is real behavioral detail 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?
Four sentences, front-loaded with the irreversible core operation and the preservation guarantee; the restrictions list is long but each element is actionable. Slight density in the final enumeration, but 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 destructive mutation with no output schema, the description covers what is replaced, what is preserved, concurrency safety, and content-format limits, so an agent can call it correctly. It omits what the response contains (e.g., the new revision needed for the next update) and whether fields outside content (sharing, publication state) are touched.
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%, but property names and const values are largely self-documenting; the description still contributes meaning by explaining the html+mode=static combination, the producer of viewport/security metadata, and the semantic purpose of expectedRevision (stale-overwrite prevention). It does not clarify the id parameter or the block-variant constraints (maxItems, maxLength), so it is not fully compensating.
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 ('Replace a brief's content') plus the distinguishing non-obvious effect ('while preserving its existing public link'), which separates it from create_document/delete_document and from publish/unpublish siblings. An agent can identify the operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied rather than stated: the description explains that revision matching prevents stale overwrites and that two content modes are supported, which tells the agent what it must supply, but it never names when to prefer this tool over siblings such as save_document_from_app or publish_document, and gives no exclusions or prerequisites (e.g., needing the current revision from get_document).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
create_documentdelete_documentget_documentget_document_sharingget_document_statslist_documentspublish_documentread_document_for_appsave_document_from_appset_document_sharingshow_documentunpublish_documentupdate_document
Add one secure layer between your agents and this server.