mazarbul

Overview Schema Source Related Servers Discussions Admin

reference

Mint or return a stable local external_ref for a URI, then relate local records to it as their primary source. Idempotent per scope; it does not fetch the URI.

Instructions

Mint-or-return an external_ref entity for a URI: a first-class local pointer to information held in another system (a GitHub issue, a Drive doc, a Granola transcript, a repo file). Returns the external_ref's resource name so you can relate(localEntity, has_primary_source, name) to record that a local record is grounded in it. Idempotent: the same URI in the same scope returns the same entity. Defaults to personal scope (local, not rendered to the shared project git tree); pass scope=project to share. Mazarbul does NOT fetch the URI — to make the referenced content searchable, fetch it with your own tools, remember() it, then reference() the URI and relate the two. Returns E_VALIDATION on a URI with no scheme or an unknown scope.

Input Schema

Name	Required	Description
`uri`	Yes	Absolute URI of the external thing, e.g. https://github.com/org/repo/issues/42, mailto:a@b.com, or a connector URL. Must carry a scheme.
`label`	No	Optional human-readable display name. Defaults to the URI. Keep third-party identity metadata out of project (git-rendered) scope.
`scope`	No	Scope to write into. Defaults to personal (local, not rendered to the shared project git tree). Pass "project" to share. Dedup is WITHIN scope: the same URI in two scopes yields two entities.

Output Schema

Name	Required	Description
`uid`	Yes	Bare ULID of the external_ref, derived deterministically from (scope, uri).
`uri`	Yes	The canonical URI, echoed back.
`name`	Yes	AIP resource name of the external_ref; pass to relate(localEntity, has_primary_source, name) or get(name).
`scope`	Yes	The resolved scope the external_ref lives in.
`created`	Yes	true if a new external_ref was minted, false if an existing one was returned (mint-or-return).

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 31, 2026

TDQS

A4.4/5.0

Behavior5/5

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

With no annotations at all, the description carries the full burden and does so: idempotency ('same URI in the same scope returns the same entity'), cross-scope dedup semantics, the side effect of writing into project git tree when scope=project, the explicit non-behavior (does not fetch), and the E_VALIDATION failure conditions.

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-loads the core action and resource in the first clause, then layers semantics, defaults, and failure modes in a logical order. It is dense but nearly every sentence carries distinct information; the parenthetical example list of sources is the only mildly expendable element.

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?

Covers purpose, idempotency, scope defaulting, the non-fetching boundary, the downstream relate() pattern, and the validation error case. An output schema exists, so return-shape detail is not required, and the description still names the returned resource name for follow-up use.

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 all three parameters are already documented, including the scope dedup caveat and the label guidance. The description's scope commentary largely restates the schema's own dedup note, so it adds only marginal meaning beyond the structured fields.

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?

States a precise verb+resource: 'Mint-or-return an external_ref entity for a URI', then defines what that entity is (a local pointer to information held elsewhere). This is clearly distinct from siblings like captureExternal, getSourceRef, and remember, which the description implicitly partitions by explaining itself as the pointer-creation step.

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

Usage Guidelines4/5

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

Gives concrete workflow context: it does NOT fetch the URI, so the agent should fetch with its own tools, remember() the content, then reference() the URI and relate the two. It also explains the personal-vs-project scope choice. It stops short of naming an explicit alternative sibling for the cases this tool is wrong, so it is a strong 4 rather than a 5.

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