mazarbul

Overview Schema Source Related Servers Discussions Admin

captureExternal

Store a pointer, your summary, and a freshness anchor for an external item fetched from a connector without copying its body; recall then reuses it while fresh and flags re-fetch when stale.

Instructions

Index an external item you fetched from a live connector (Notion, Linear, Granola, Drive, GitHub) WITHOUT copying its body into maz. One call stores a pointer + YOUR summary + a freshness anchor; maz never fetches or holds the content. recall later returns the summary with an inline freshness verdict so you reuse it when fresh and re-fetch live when stale. The capture is UNTRUSTED (lineage connector:): facts land proposed, never superseding your own. Idempotent by contentHash within the connector's TTL. Pass status=deleted|access-revoked to tombstone an item you can no longer reach. Refuses project scope and ephemeral connectors (gmail/gcal/slack; read those live). recall FIRST before capturing, to avoid duplicates.

Input Schema

Name	Required	Description
`uri`	Yes	Absolute URI of the external item (must carry a scheme), e.g. a Notion page URL, a Linear issue URL, a Drive doc link. The canonical identity of the external_ref pointer.
`label`	No	Human-readable display name for the external_ref. Defaults to the externalId or connector, NEVER the raw URI (which would leak into a shared render).
`scope`	No	Scope to capture into. Defaults to personal. Project is refused: captured external content is sensitive and project renders to shared git.
`status`	No	active (default) records a live snapshot. deleted (a 404 on re-fetch) or access-revoked (a 403) tombstones the prior capture so recall flags it access-unverified instead of dropping it.
`stream`	No	Sub-channel within the connector, e.g. a Notion database id or a Linear team key. Optional.
`summary`	No	Your faithful summary of the fetched content. Put the stable external id and key facts in the prose so recall can find it. Required unless you pass summaries[] or a tombstone status.
`dedupKey`	No	Idempotency key. Defaults to <connector>:<externalId>:<scope>. Recapturing the same item must reuse the same dedupKey (omit it and pass a stable externalId, or pass it explicitly).
`connector`	Yes	The connector the item came from: notion, linear, granola, drive, github. Drives the freshness budget and the untrusted-lineage trust tag. Ephemeral connectors (gmail, gcal, slack) are refused: read those live.
`fetchTime`	No	When you fetched the item (RFC 3339 UTC). Defaults to now.
`summaries`	No	Chunked summary: one episode per element, all sharing one external_ref. Use for long items; otherwise pass summary.
`externalId`	No	The source-system stable id (Notion page id, Linear issue key). Used to mint the dedupKey when you omit it; hashed in any plaintext render.
`sourceType`	Yes	Open-taxonomy kind of the item, e.g. notion_page, linear_issue, meeting_notes, drive_doc.
`contentHash`	No	SHA-256 hex of the item's canonical content subset (the freshness ETag). Recapturing with the same hash within the connector's TTL is a no-op. OMIT it if you cannot compute a real SHA-256 over the fetched content; do NOT fabricate one (any non-64-hex value is rejected). Defaults to the hash of your summary text when omitted.
`externalUrl`	No	Dereferenceable location to re-fetch when stale. Defaults to uri.

Output Schema

Name	Required	Description
`action`	Yes	captured = first snapshot; skipped = unchanged within TTL (no write); revision = content changed (new episode, prior superseded); expired = unchanged but past TTL (fetch-time refreshed); tombstoned = item reported gone.
`freshness`	Yes	The resulting freshness verdict for this item, the same value recall will report.
`episodeNames`	Yes	Resource names of the summary episode(s) this capture is grounded in (one per chunk).
`sourceRefNames`	Yes	Resource names of the SourceRef provenance rows.
`externalRefName`	Yes	AIP resource name of the external_ref pointer entity.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 31, 2026

TDQS

A4.2/5.0

Behavior3/5

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

Annotations are empty, so the description carries the full burden — and it does cover a lot: untrusted lineage (connector:<name>), facts landing as proposed rather than superseding, TTL-scoped idempotency by contentHash, and tombstoning via status. It does not state auth/permission requirements or what the response contains on a duplicate no-op beyond the idempotency claim.

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

Conciseness4/5

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

Front-loaded with the core distinction (pointer, not body) and each subsequent sentence adds a distinct constraint (freshness verdict, trust tag, idempotency, tombstones, refusals, dedup workflow). Dense but nearly every clause earns its place; minor tightening possible.

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

Completeness5/5

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

With an output schema present, return values need not be explained, and the description covers the trust model, idempotency, refusal rules, and dedup ordering that the schema alone cannot convey. Sufficient for a 14-parameter mutation tool with no annotations.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents all 14 parameters; the description largely restates what the schema says (contentHash idempotency within TTL, status=deleted|access-revoked tombstoning, summary requirement). It adds framing about why project scope is refused but no syntax or format detail beyond the schema — baseline 3 applies.

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

Purpose5/5

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

Specific verb and resource: 'Index an external item you fetched from a live connector ... WITHOUT copying its body', naming the pointer+summary+freshness-anchor model. It explicitly distinguishes itself from ingest/remember siblings by stating maz never fetches or holds the content.

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

Usage Guidelines5/5

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

Gives both directions: 'recall FIRST before capturing, to avoid duplicates' and hard exclusions ('Refuses project scope and ephemeral connectors (gmail/gcal/slack; read those live)'). The alternative for ephemeral sources is named explicitly, and the tombstone path is described.

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