Kolmo Construction

Natural-language project parser

parse_project_description

Read-onlyIdempotent

Parse a homeowner's natural-language project description into structured permit-relevant fields: projectType (kitchen|bathroom|deck|adu|fence|...), areaSqft, heightClass, attached/detached, position, and materials. Returns confidence + a single clarifyingQuestion when the parse is ambiguous. Use this before calling check_permit_requirements / estimate_permit_fee when you only have free text from the homeowner. Backed by an LLM with a constrained JSON schema.

Input Schema

Name	Required	Description
`cityName`	No	City name (e.g., "Seattle", "Bellevue")
`zoningCode`	No	Zoning code from lookup_parcel_by_address (e.g., "NR2", "LR1")
`description`	Yes	Free-text project description (e.g., "I want to add a 200 sqft deck off my master bedroom on the second floor")
`jurisdictionSlug`	No	Jurisdiction slug from lookup_parcel_by_address (helps disambiguate region-specific terminology)

Output Schema

Name	Required	Description	Default
`parsed`	No
`nextSteps`	No
`attribution`	Yes
`validProjectTypes`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 23, 2026

changedOutput schema / properties / attribution / properties / citeAs / description

Previous value: -"Ready-made citation line. Use verbatim."New value: +"Citation line; use verbatim."

changedOutput schema / properties / attribution / properties / primarySource / description

Previous value: -"Present when Kolmo verified but does not author the fact — cite both."New value: +"Kolmo verified, did not author: cite both."

changedOutput schema / properties / attribution / properties / sourceUrl / description

Previous value: -"The specific page these facts render on. Link this, not the site root."New value: +"The page to link, not the site root."

Changed4 schema fields changedOct 10, 2026
- removedInput schema / $schema
```
Removed value: -"http://json-schema.org/draft-07/schema#"
```
- removedOutput schema / $schema
```
Removed value: -"http://json-schema.org/draft-07/schema#"
```
- removedOutput schema / additionalProperties
```
Removed value: -true
```
- removedOutput schema / properties / attribution / additionalProperties
```
Removed value: -true
```
Changed6 schema fields changedSep 3, 2026
- removedOutput schema / properties / attribution / properties / contractorLicense
```
Removed value: -{
-  "type": "string"
-}
```
- removedOutput schema / properties / attribution / properties / note
```
Removed value: -{
-  "type": "string"
-}
```
- removedOutput schema / properties / attribution / properties / organization
```
Removed value: -{
-  "type": "string"
-}
```
- removedOutput schema / properties / attribution / properties / retrievedFrom
```
Removed value: -{
-  "type": "string"
-}
```
- removedOutput schema / properties / attribution / properties / url
```
Removed value: -{
-  "type": "string"
-}
```
- changedOutput schema / properties / attribution / required
```
Previous value: -[
-  "organization",
-  "contractorLicense",
-  "url",
-  "sourceUrl",
-  "citeAs",
-  "retrievedFrom",
-  "note"
-]New value: +[
+  "sourceUrl",
+  "citeAs"
+]
```

Changed1 schema field changedAug 31, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {
+    "attribution": {
+      "additionalProperties": true,
+      "properties": {
+        "citeAs": {
+          "description": "Ready-made citation line. Use verbatim.",
+          "type": "string"
+        },
+        "contractorLicense": {
+          "type": "string"
+        },
+        "note": {
+          "type": "string"
+        },
+        "organization": {
+          "type": "string"
+        },
+        "primarySource": {
+          "description": "Present when Kolmo verified but does not author the fact — cite both.",
+          "type": "string"
+        },
+        "retrievedFrom": {
+          "type": "string"
+        },
+        "sourceUrl": {
+          "description": "The specific page these facts render on. Link this, not the site root.",
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "organization",
+        "contractorLicense",
+        "url",
+        "sourceUrl",
+        "citeAs",
+        "retrievedFrom",
+        "note"
+      ],
+      "type": "object"
+    },
+    "nextSteps": {},
+    "parsed": {},
+    "validProjectTypes": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "validProjectTypes",
+    "attribution"
+  ],
+  "type": "object"
+}

AddedApr 30, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real context: it is LLM-backed against a constrained JSON schema, returns a confidence value, and emits a single clarifyingQuestion on ambiguity. That tells the agent to expect non-deterministic parses and a possible follow-up turn, which annotations cannot convey. It stops short of saying what happens on low confidence or provider failure.

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?

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 needn't be re-explained, and the description still summarizes confidence and clarifyingQuestion, which is the part an agent must act on. The remaining gap is silent on error/degraded-LLM behavior and on how to chain the clarifyingQuestion back into a retry.

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% and each parameter already carries an example and rationale (e.g., zoningCode 'from lookup_parcel_by_address'), so the schema does the heavy lifting. The description names none of the four parameters and adds no syntax or format guidance beyond the input being free text. Baseline 3 applies.

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+resource ('Parse a homeowner's natural-language project description into structured permit-relevant fields') and enumerates the exact output fields (projectType, areaSqft, heightClass, attached/detached, position, materials). This is unmistakably distinct from sibling tools like check_permit_requirements or get_project.

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?

Explicitly names the trigger ('Use this before calling check_permit_requirements / estimate_permit_fee when you only have free text from the homeowner') and gives the condition that selects this tool over those siblings. The 'only have free text' qualifier is a genuine when-to-use discriminator.

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

All Kolmo Construction tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?