# Managing Briefs

Operational guide for an AI agent managing Briefs through the Briefs MCP. This covers the
lifecycle of a Brief once it exists: reading, listing, updating, and deleting. For how to
author and structure Briefs, see https://sharebriefs.com/brief/creating.

## The tools

- `get_brief` — fetch a single Brief by owner + name. Returns the current markdown content.
  This is the read you do before any update so you are editing the latest version.
- `list_briefs` — list Briefs owned by a user or org (defaults to the authenticated user).
  Use this to discover what already exists before creating something new, and to find the
  exact name of a Brief you intend to update.
- `create_brief` — create a new Brief (content, optional name, optional owner namespace,
  visibility). See the creating Brief for naming and structure guidance.
- `update_brief` — change a Brief's content, name (`new_name`), or visibility. Updates are
  in place: the URL stays the same and every future fetch gets the new version. Editing
  content or renaming needs `write` access; changing visibility needs `admin` on the Brief.
- `delete_brief` — permanently remove a Brief. Requires admin access. Destructive.

## Updating is the normal path, not re-creating

Briefs are hosted, so the URL is the stable contract. When knowledge changes, `update_brief`
the existing Brief rather than creating a new one. Never create `intro-v2`; update `intro`.
Anyone holding the link automatically gets the latest content on their next fetch.

When updating content, fetch the current version first (`get_brief`), modify the full
markdown, and send the complete new content. Updates replace content wholesale.

## Renaming changes the URL

`new_name` changes the name, which changes the public URL. Only rename a Brief that has not
been shared widely, or you will break existing links. Prefer stable names from the start.

## Listing before creating

Before creating a Brief for a subject, `list_briefs` for the target owner to check whether a
suitable Brief already exists. Extending or updating an existing Brief is usually better than
adding a near-duplicate. This keeps a user's namespace clean and discoverable.

## Deleting is destructive

`delete_brief` permanently removes the Brief and breaks its URL for everyone. Confirm with
the user before deleting anything that may be shared. Requires admin access on the Brief.

## Agent etiquette

- Default to the least surprising action: update over recreate, extend over duplicate.
- Keep names stable once a URL is in the wild.
- Confirm destructive or URL-changing actions (delete, rename) with the user first.
- After any change, hand the user the canonical URL.

## Related Briefs

- Concept overview: https://sharebriefs.com/brief/intro
- Authoring and structuring: https://sharebriefs.com/brief/creating
- Sharing a Brief with specific people: https://sharebriefs.com/brief/sharing
- Team/org namespaces: https://sharebriefs.com/brief/organizations