InstaBids

Start a draft job

start_job

Use this when a homeowner wants contractor bids on a home repair or improvement job in the US. Creates a private draft from their description and five-digit ZIP and returns a one-hour link for the homeowner to open. Nothing reaches a contractor until the homeowner confirms their email and sends it. Do not include names, phone numbers, emails or street addresses. Do not use for emergencies. Ask the homeowner, one short question at a time and only for what is missing, what needs doing, where in the home, rough size or count, when it is needed and who supplies materials, then put the answers in the message. fill what you can; everything else can come later. Start with the homeowner’s description, trade and ZIP, plus a photo or a good description. Optional: photos, a description or transcript of a 20–60 s walk clip, timing and the job type’s must-haves from intake_templates. Never invent answers. ZIP only; never send a street address or a price. Nothing reaches contractors before the homeowner sends the card.

Input Schema

Name	Required	Description
`zip`	Yes
`trade`	Yes	Job trade; generic home repair is allowed.
`message`	Yes
`photoUrls`	No	Optional photos; attachment still requires the existing scan and photo permissions.
`quotes_by`	No	ISO date, or null for no deadline; never a price.
`walk_clip`	No	Description or transcript of a 20–60 s walk clip. This tool does not upload video bytes or fetch video URLs.
`must_haves`	No	Known answers to this job type’s intake_templates must-haves; unknown answers can come later.
`intent_level`	No	10 emergency; 8 soon; 6 planned; 4 if the price is right; 2 someday. Use only evidence from the homeowner.
`deadline_hard`	No
`deadline_reason`	No	Optional reason for the date, without names or contact details.
`intent_confidence`	No
`project_completion_deadline`	No	ISO date, or null for no deadline; never a price.

Output Schema

Name	Required	Description
`card`	No	Saved in-chat card, present only when available.
`status`	Yes
`message`	Yes
`claimUrl`	Yes
`expiresAt`	Yes
`understood`	No
`photosAdded`	No
`statusHandle`	No	Read handle for job_status, present only when available.
`photosRefused`	No
`cardUnavailable`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 4, 2026
- removedOutput schema / properties / sendUrl
```
Removed value: -{
-  "format": "uri",
-  "type": "string"
-}
```

Changed15 schema fields changedNov 3, 2026

addedInput schema / properties / deadline_hard
```
Added value: +{
+  "type": "boolean"
+}
```

addedInput schema / properties / deadline_reason

Added value: +{
+  "description": "Optional reason for the date, without names or contact details.",
+  "maxLength": 300,
+  "type": "string"
+}

addedInput schema / properties / intent_confidence

Added value: +{
+  "enum": [
+    "low",
+    "med",
+    "high"
+  ],
+  "type": "string"
+}

addedInput schema / properties / intent_level

Added value: +{
+  "description": "10 emergency; 8 soon; 6 planned; 4 if the price is right; 2 someday. Use only evidence from the homeowner.",
+  "enum": [
+    2,
+    4,
+    6,
+    8,
+    10
+  ],
+  "type": "integer"
+}

addedInput schema / properties / must_haves

Added value: +{
+  "description": "Known answers to this job type’s intake_templates must-haves; unknown answers can come later.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "answer": {
+        "maxLength": 300,
+        "minLength": 1,
+        "type": "string"
+      },
+      "key": {
+        "maxLength": 100,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "key",
+      "answer"
+    ],
+    "type": "object"
+  },
+  "maxItems": 20,
+  "type": "array"
+}

addedInput schema / properties / photoUrls

Added value: +{
+  "description": "Optional photos; attachment still requires the existing scan and photo permissions.",
+  "items": {
+    "maxLength": 2048,
+    "pattern": "^https://",
+    "type": "string"
+  },
+  "maxItems": 5,
+  "type": "array"
+}

addedInput schema / properties / project_completion_deadline

Added value: +{
+  "description": "ISO date, or null for no deadline; never a price.",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / properties / quotes_by

Added value: +{
+  "description": "ISO date, or null for no deadline; never a price.",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / properties / trade

Added value: +{
+  "description": "Job trade; generic home repair is allowed.",
+  "maxLength": 100,
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / walk_clip

Added value: +{
+  "description": "Description or transcript of a 20–60 s walk clip. This tool does not upload video bytes or fetch video URLs.",
+  "maxLength": 1000,
+  "minLength": 1,
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "message",
-  "zip"
-]New value: +[
+  "message",
+  "zip",
+  "trade"
+]

addedOutput schema / properties / cardUnavailable

Added value: +{
+  "const": true,
+  "type": "boolean"
+}

addedOutput schema / properties / photosAdded

Added value: +{
+  "maximum": 5,
+  "minimum": 0,
+  "type": "integer"
+}

addedOutput schema / properties / photosRefused

Added value: +{
+  "maximum": 5,
+  "minimum": 0,
+  "type": "integer"
+}

addedOutput schema / properties / understood

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "missingMustHaves": {
+      "items": {
+        "pattern": "^gap_[a-f0-9]{16}$",
+        "type": "string"
+      },
+      "maxItems": 100,
+      "type": "array"
+    },
+    "nextQuestion": {
+      "additionalProperties": false,
+      "properties": {
+        "author": {
+          "const": "assistant",
+          "type": "string"
+        },
+        "instructionFlags": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "text": {
+          "maxLength": 600,
+          "type": "string"
+        },
+        "untrusted": {
+          "const": true,
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "untrusted",
+        "author",
+        "text",
+        "instructionFlags"
+      ],
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "scopeSummary": {
+      "maxLength": 600,
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "trade": {
+      "maxLength": 600,
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "trade",
+    "scopeSummary",
+    "missingMustHaves",
+    "nextQuestion"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedNov 3, 2026
- addedOutput schema / properties / card / description
```
Added value: +"Saved in-chat card, present only when available."
```
- addedOutput schema / properties / statusHandle / description
```
Added value: +"Read handle for job_status, present only when available."
```
Changed1 schema field changedNov 2, 2026
- addedOutput schema / properties / sendUrl
```
Added value: +{
+  "format": "uri",
+  "type": "string"
+}
```
Changed1 schema field changedOct 31, 2026
- addedOutput schema / properties / statusHandle
```
Added value: +{
+  "pattern": "^[A-Za-z0-9_-]{43}$",
+  "type": "string"
+}
```
First observedOct 30, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only declare the mutation/safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds substantial behavior beyond that: the job stays a private draft, nothing reaches a contractor until the homeowner confirms email and sends, and a one-hour link is returned. It also discloses the PII and ZIP-only constraints that govern what may be submitted.

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

Conciseness3/5

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

The critical scoping and privacy rules are front-loaded, which is good, but the text is long and repeats itself ('Nothing reaches a contractor until the homeowner confirms their email and sends it' vs 'Nothing reaches contractors before the homeowner sends the card'). The mid-section question checklist is useful but reads as a run-on.

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?

For a 12-parameter mutation tool with an output schema and annotations, the description covers the workflow, privacy constraints and intake procedure thoroughly. The main gap is that idempotentHint=false is never surfaced as a warning about creating duplicate drafts if the tool is called twice.

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

Parameters4/5

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

Schema coverage is 67%, and the description compensates well for the core fields: it explains what belongs in message, that zip is five-digit and street-address-free, that trade is required, and that photos, walk_clip transcripts, timing and must_haves from intake_templates are optional. It does not explain intent_level, intent_confidence, deadline_hard or project_completion_deadline, which rely on the schema text alone.

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 and resource ('Creates a private draft' job) plus the trigger condition (homeowner wants contractor bids on a US home repair/improvement job) and the return value (a one-hour link). It is clearly distinguishable from siblings like job_status and job_guidance.

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?

Explicit when-to-use ('when a homeowner wants contractor bids'), explicit when-not ('Do not use for emergencies'), and explicit data exclusions (no names, phones, emails, street addresses, prices). It also prescribes the intake procedure: ask one short question at a time, only for what is missing, and never invent answers.

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

All InstaBids tools Inspect

Try in Browser

Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?