Skip to main content
Glama
civil-qto-mcp

civil-qto-mcp

inspect_and_audit_boq_xlsx

Parse Excel Bill of Quantities workbooks and audit visible rows for math mismatches, hardcoded totals, sum gaps, shared formulas, zero quantities, and zero prices while skipping hidden data.

Instructions

[STEP 3C of HITL Workflow] Safely parse and mathematically audit an Excel (.xlsx / .xlsm) Bill of Quantities.

Safety & Auditing Features:
- Strictly skips `hidden` and `veryHidden` worksheets (listing them in `skipped_hidden_sheets`)
- Strictly skips hidden rows (`row_dimensions[r].hidden`)
- Automatically detects Single-Price and Hungarian TERC Split (Material + Labor) column layouts
- Audits 100% of rows on selected visible sheets for `MATH_MISMATCH`, `HARDCODED_TOTAL`,
  `SUM_RANGE_GAP`, `SHARED_FORMULA_RISK`, `ZERO_QUANTITY`, and `ZERO_UNIT_PRICE`
  (even when `keyword_filter` or `limit` paginates the returned `items` list)

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "file_path": "<file_path>"
    },
    "name": "inspect_and_audit_boq_xlsx"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of BoQ line items to return in `items` (protects LLM context window on 1000+ row BoQs).
offsetNoPagination offset for returned BoQ line items.
file_pathYesPath to the .xlsx or .xlsm Bill of Quantities workbook.
sheet_namesNoOptional list of specific visible worksheet names to inspect.
keyword_filterNoOptional case-insensitive regex/keyword filter on item description, item number, or code to reduce returned rows.

Output Schema

NameRequiredDescriptionDefault
itemsNo
file_pathYes
sheet_summariesNo
formula_anomaliesNo
has_shared_formulasNo
returned_items_countNo
total_matching_itemsNo
skipped_hidden_sheetsNoSheets with state 'hidden' or 'veryHidden' that were strictly excluded.
total_items_extractedNo
visible_sheets_processedYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does so well: it discloses hidden-sheet and hidden-row skipping, reports skipped sheets via `skipped_hidden_sheets`, auto-detects column layouts, and guarantees the audit covers 100% of rows regardless of pagination. It does not mention file-access requirements or performance on very large workbooks.

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 workflow step and one-sentence purpose, then scannable bullets for safety/audit behavior. Minor redundancy in the repeated 'Strictly skips' phrasing, but nothing wasteful.

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

Completeness4/5

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

An output schema exists, so return values need no explanation, and the audit coverage behavior is fully specified. The remaining gap is that the six audit finding codes are named but never defined, leaving an agent to infer their meaning from label names alone.

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?

Schema coverage is 100%, so the baseline would be 3, but the description adds genuinely new meaning: `keyword_filter` and `limit` only paginate the returned `items` list and do not narrow the audit scope. That interaction is not derivable from the schema and prevents a serious misinterpretation of paginated results.

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 specific verb pair and resource: 'parse and mathematically audit an Excel (.xlsx / .xlsm) Bill of Quantities'. The file-format scoping and 'MATH_MISMATCH/HARDCODED_TOTAL' audit vocabulary distinguish it from siblings like audit_technological_completeness or compare_qto_with_boq without needing to open a schema.

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

Usage Guidelines3/5

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

The '[STEP 3C of HITL Workflow]' tag implies sequencing context, but the description never states when to choose this over sibling audits or what precondition (e.g. an existing BoQ export) must hold. Usage is implied by the workflow label rather than declared.

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