[Annotations] Add bulk note management and structured safety overrides for upstream tools

[Disdjj]

Summary

I curated usage and safety guidance for a Home Assistant MCP mount after importing 24 tools.

The final annotation set contained:

• one parent-directory note;
• one mount-level usage note;
• 24 exact tool notes marking read, write, high-impact, privacy, and target-selection guidance.

Tool Bridge's path-note system worked correctly and the notes appeared in exact ~help. The tb note CLI also provides clear single-entry set/get/rm/ls commands.

The friction is that a realistic tool catalog requires many independent writes, and prose notes cannot fill missing structured safety metadata from an upstream MCP server.

Environment

• tb CLI: 0.25.0
• Gateway: 0.17.0
• Upstream mount: Home Assistant MCP Server with 24 tools
• All domain names, tokens, entity names, and household data are intentionally omitted

What worked

These commands provide a usable single-note workflow:

tb note set <path> <text>
tb note get <path>
tb note ls <prefix>
tb note rm <path>

Exact tool help correctly displayed the resulting note field.

This was useful for guidance such as:

• query state before control;
• prefer an exact entity name over an area-wide target;
• do not call broad turn-on/off tools with empty selectors;
• treat broadcast, volume, and timer cancellation as externally perceptible or high-impact;
• minimize disclosure of household state.

Friction observed

1. Catalog annotation requires one mutation per path

Annotating one 24-tool mount required 26 independent set operations.

There is no first-class:

• batch apply;
• import/export;
• dry-run/validation;
• atomic commit;
• delete-missing/prune mode;
• per-entry outcome summary;
• reusable template/group rule.

A shell loop or custom script can call tb note set repeatedly, but partial failure leaves an unknown mixed state and every caller must rebuild validation, retry, and rollback behavior.

2. Notes are prose only

The upstream MCP server supplied descriptions and schemas but omitted effect/confirm annotations. I could write notes such as [read-only], [write], or [high impact], but:

• exact help still had null/absent structured effect and confirm;
• search could not filter or rank using those safety notes;
• the public Agent Skill could not take its metadata-based read fast path;
• clients had to interpret prose conservatively.

Path notes are valuable operational documentation, but they are not a substitute for machine-readable safety metadata.

3. MCP virtualization cannot fill safety gaps

The current virtualization surface supports:

• prefix;
• rename;
• hide;
• description override.

It does not support per-tool effect, confirm, preferred/deprecated state, or safety tags.

That means an administrator can fix a tool's display name and description but cannot safely complete missing upstream metadata.

Suggested direction

A. Add batch note management

Possible CLI:

tb note apply --file notes.json --dry-run
tb note apply --file notes.json --atomic
tb note export home/home-assistant --file -

Example input:

{
  "prefix": "home/home-assistant",
  "items": [
    {
      "path": "get_live_context",
      "text": "Preferred read-only entry; filter by name, area, or domain."
    },
    {
      "path": "hass_cancel_all_timers",
      "text": "High impact; an empty area may cancel all timers."
    }
  ]
}

Useful semantics:

• strict path normalization and duplicate detection;
• validate every path/text before the first write;
• optional optimistic revision for the annotation collection;
• atomic all-or-nothing apply where the backend supports it;
• explicit partial-result reporting otherwise;
• export suitable for review and version control;
• optional prune/delete-missing limited to the declared prefix.

B. Add a separate structured tool-policy overlay

Do not overload free-form note text. Add either a dedicated policy surface or carefully extend virtualization, for example:

{
  tools: {
    GetLiveContext: {
      effect: "read",
      confirm: false,
      preferred: true
    },
    HassCancelAllTimers: {
      effect: "destructive",
      confirm: true
    }
  }
}

The exact storage model is open, but the live help/search output should expose provenance, for example:

{
  "effect": "destructive",
  "confirm": true,
  "metadataSource": {
    "effect": "admin_override",
    "confirm": "admin_override"
  }
}

C. Make safety overrides monotonic by default

An admin overlay should be able to:

• fill missing metadata;
• make an operation stricter;
• require confirmation;
• mark a tool deprecated or non-preferred.

It should not silently downgrade an upstream destructive tool to read or remove an upstream confirmation requirement.

If unsafe downgrades are supported at all, they should require a separate explicit capability and prominent audit trail.

D. Keep notes, structured policy, and feedback distinct

Suggested roles:

• description: what the upstream tool does;
• note: administrator-curated local usage guidance;
• structured policy overlay: machine-readable safety/preference metadata;
• feedback: operational experience from previous calls.

Live schema and stricter safety metadata should win over conflicting prose.

Suggested acceptance criteria

1. A 25+ entry note set can be validated and applied with one CLI operation.
2. A failed item cannot silently leave an unreported partial configuration.
3. Notes can be exported and reapplied without losing paths or text.
4. An admin can fill an absent upstream effect/confirm value with visible provenance.
5. An override cannot weaken an upstream destructive/confirmation signal by default.
6. Exact help and search expose the effective structured metadata consistently.
7. The public Agent Skill can distinguish a curated read tool from curated writes without parsing note prose.
8. Existing single-entry tb note commands and text-only annotations remain backward compatible.

Related:

• [Search] Coverage-blind keyword ranking is noisy and can put write tools above read intent #107: search does not use curated guidance and can rank writes above read intent;
• [Workflow] Prefer exact ~help when paths are known and define a safe fallback for missing MCP metadata tool-bridge-skill#3: the Agent Skill lacks a deterministic fallback when upstream MCP safety metadata is missing;
• [Safety metadata] First-party commands omit effect/confirm despite known read/write semantics #110: first-party commands also need complete effect/confirm metadata.