COBie MCP

by roynertr

Overview Schema Source Related Servers Discussions Admin

Python

Local

preview_update

Preview COBie Excel updates as a dry run, returning a diff of changes to review before applying them with confirmation.

Instructions

Preview COBie updates (dry-run) and return diff. Explicit preview gate.

**Preview gate:** Use this before apply. To commit, call update_cobie with
dry_run=False only after user confirmation (e.g. confirm_token CONFIRM_APPLY).
No confirm_token on server; client enforces confirm_token.

Args:
    excel_path: Path to COBie Excel file.
    draft_json: Same shape as structured_update_json for update_cobie (instructions array).
    actor_contact: Updater identity (required).
    as_of_date: Optional date for CreatedOn/InstallationDate.
    key_mode: Lookup mode for keys.

Returns:
    UpdateResult with success, updated_count, diffs, summary, next_actions, dry_run=True.

Example:
    result = preview_update("project.xlsx", {"instructions": [...]}, actor_contact)
    # result.diffs = [{"sheet": "Component", "row_key": "C-1", "column": "SerialNumber", ...}]
    # result.next_actions = ["To commit: call update_cobie with dry_run=False after confirm_token"]

Input Schema

TableJSON Schema

Name	Required	Default
`key_mode`	No	name
`as_of_date`	No
`draft_json`	Yes
`excel_path`	Yes
`actor_contact`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`diffs`	No
`errors`	No
`dry_run`	No
`success`	Yes
`summary`	No
`provenance`	No
`updated_at`	No
`output_path`	No
`next_actions`	No
`updated_count`	Yes
`evidence_items`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.0Sep 7, 2026

TDQS

A5/5.0

Behavior5/5

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

The description openly discloses that this is a non-committing dry-run, returns a diff, and explicitly warns that 'No confirm_token on server; client enforces confirm_token'. With no annotations provided, the description carries the full transparency burden and meets it well.

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

Conciseness5/5

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

The description is well-structured with clear sections for preview gate, Args, Returns, and Example. The formatting is scannable and thorough without being redundant; every sentence serves a purpose.

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?

Given the complexity of a dry-run preview with nested objects and a gate mechanism, the description provides a full example, return structure hints, and usage context. It covers all necessary aspects for an agent to invoke the tool correctly and know what to expect.

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

Parameters5/5

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

The schema has zero descriptions for the 5 parameters, and the description adds meaningful semantics for each one (e.g., 'Excel file path', 'Same shape as structured_update_json', 'Updater identity'). It even clarifies the nested draft_json structure, fully compensating for the lack of schema descriptions.

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?

The description states a specific verb ('Preview') and resource ('COBie updates') with explicit 'dry-run' and 'return diff'. It distinguishes itself from the sibling update_cobie by framing it as a preview before apply, making the tool's purpose unmistakable.

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?

It explicitly instructs 'Use this before apply' and says to call update_cobie with dry_run=False only after user confirmation. This provides crystal-clear when-to-use and when-not-to-use guidance relative to the sibling update_cobie tool.

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

Deploy Server