[Workflow] Prefer exact ~help when paths are known and define a safe fallback for missing MCP metadata

[pDJJq]

Summary

I used the tool-bridge skill during a real Home Assistant MCP deployment and found it valuable as a safety and operational checklist. In particular, it helped with secret hygiene, live-schema verification, mutation authorization, bounded retries, and avoiding unnecessary device-control tests.

However, the recommended discovery workflow assumes two things that did not hold in practice:

1. keyword search is precise enough to be the default entry point for an unknown capability;
2. upstream MCP tools reliably provide effect and confirm metadata.

In this session, exact ~help was substantially more useful than search, while missing MCP annotations made the documented fast path impossible even for a clearly query-oriented tool.

Related Tool Bridge runtime reports:

• MCP tools with CamelCase names are advertised but cannot be called after path normalization tool-bridge#106 — mixed-case MCP tools were advertised by help but uncallable until explicitly renamed
• [Search] Coverage-blind keyword ranking is noisy and can put write tools above read intent tool-bridge#107 — keyword search returned 25–43 results and could rank a mutating tool above the intended read tool

What was useful

The skill's strongest guidance was:

• treat runtime descriptions as the source of truth;
• never guess arguments or paths from memory;
• keep credentials out of prompts, logs, arguments, and feedback;
• do not retry side-effecting calls with an unknown outcome;
• require authorization for real mutations;
• validate returned data instead of trusting only the process exit code.

Following that guidance, I verified the integration with a state query and did not turn devices on/off merely for testing.

Exact help was the most reliable discovery surface:

• node help exposed the 24 Home Assistant tools;
• tb help <node> --schemas --json exposed their live input schemas in one request;
• tool-level help exposed full upstream descriptions and path annotations;
• help made the CamelCase/canonical-path mismatch diagnosable;
• system/annotation/~help exposed the exact 2000-character note limit and write schema.

Where the workflow became awkward

1. Search-first is not always the shortest or safest path

The skill currently says to start with search when a capability is known.

In the observed gateway:

• turn on home light returned 43 tools;
• read current home temperature --limit 5 ranked hass_climate_set_temperature first and the correct state reader fourth;
• semantic search was unavailable;
• JSON search results carried schemas for the whole noisy page, consuming context.

When the user already supplied the mount (home/home-assistant), direct node/tool help was both shorter and more trustworthy than global search.

2. The fast path depends on metadata that real MCP servers may omit

The skill permits direct read calls only when path, schema, effect: read, and confirm: false are known.

Home Assistant's MCP Server supplied descriptions and schemas but omitted structured effect/confirm hints. As a result:

• get_live_context was semantically a state query, but effect and confirm were absent;
• device-control tools also had absent metadata;
• missing metadata created ambiguity rather than a defined safe fallback;
• the agent had to rely on exact help, input shape, user intent, and an admin-curated annotation to make a conservative read-only verification.

The skill correctly says not to guess, but it does not say what to do when the authoritative runtime schema is complete except for safety hints.

3. The skill does not explain how path annotations affect decisions

Admin-curated notes were added to the node and all 24 tools:

• get_live_context was marked as the preferred read-only entry;
• device controls were marked as writes;
• timer cancellation was marked high-impact;
• target narrowing and privacy rules were documented.

These notes were useful in exact ~help, but the skill does not define:

• whether annotations may support a conservative safety decision;
• that annotations are advisory and cannot override schema/upstream metadata;
• how to handle conflicts between description, schema, effect, confirm, and note;
• whether a missing effect plus a clear read-only annotation is sufficient for a user-requested read.

4. Help selection could be more explicit

The current skill discusses node and tool help, but not the practical choice between:

• tb help <node> --schemas --json for a small known mount;
• tb help <node>/<tool> --json for one unfamiliar or mutating command;
• search results that already include schemas;
• plain node help, which is intentionally an index.

A small decision table could avoid both redundant round trips and overly broad schema dumps.

Suggested workflow

A. Choose discovery based on what is already known

1. Exact command path known: use exact tool help only when the contract or safety metadata needs revalidation; otherwise reuse the verified contract.
2. Known mount/node, unknown command: use tb help <node> --schemas --json when the tool set is reasonably small.
3. Capability known but location unknown: use tb search ... --limit 10 --json.
4. Search is noisy or ambiguous: narrow by tree/path and switch to exact help instead of paging through low-confidence results.

Do not run global search when the user already provided the relevant node.

B. Define a conservative missing-metadata policy

A possible policy:

• missing effect is unknown, never equivalent to read;
• explicit write, destructive, or confirm: true keeps the existing authorization rules;
• if effect/confirm are absent, open exact tool help and inspect description, schema, and note;
• a clearly query-only operation may be called only for an explicit read request, with no mutation-shaped arguments, and the agent should record that the structured effect metadata was absent;
• an ambiguous or control-oriented operation is treated as mutating and requires the user's explicit intent;
• never auto-retry a metadata-unknown call after timeout.

If maintainers do not want agents to infer read-only behavior from exact help, the skill should instead say to stop and request direction. The important part is making the fallback deterministic.

C. Clarify annotation precedence

Suggested precedence:

1. live schema/path/scope and structured effect/confirm;
2. exact upstream description;
3. admin-curated path annotation as operational guidance;
4. feedback as historical experience.

Annotations and feedback must not override a conflicting live schema or downgrade a mutation to read-only.

Suggested acceptance tests

1. Known-node test: user supplies a mount path; the agent uses node --schemas or exact help and does not call global search.
2. Noisy-search test: search returns more than 10 mixed results; the agent narrows by path/help rather than calling the first result blindly.
3. Missing-metadata read test: a mock MCP read tool has schema and description but no effect/confirm; the agent follows the documented fallback.
4. Missing-metadata write test: a mock control tool has no effect/confirm; the agent still requires explicit mutation intent.
5. Annotation conflict test: a note claims read-only while structured metadata says write; the structured metadata wins.
6. Round-trip test: a small known node is described with tb help <node> --schemas --json rather than node help plus one help call per tool.

Bottom line

My practical ranking from this session was:

• exact ~help: highly useful and authoritative;
• the skill: useful for safety, but missing a real-world metadata fallback;
• global keyword search: useful only for narrow queries on the current gateway.

The skill would become much more reliable if it treated search as one discovery option rather than the universal first step, and explicitly covered MCP servers that omit safety annotations.