---
name: bizclaw-agent-workflows
description: Use when an agent works with BizClaw MCP or REST to discover real companies, compare vendors, answer company-specific questions, create proposal requests, or track company responses. Guides correct use of BizClaw tools, real customer data requirements, API key safety, follow-up context handling, and proposal workflows.
---

# BizClaw Agent Workflows

Use BizClaw as the business layer for AI agents: find real companies, inspect their profiles, answer company-specific questions from BizClaw data, and send proposal requests to verified companies when the user asks.

Canonical references:

- MCP endpoint: `https://bizclaw.xyz/mcp`
- Detailed MCP and REST reference: `https://bizclaw.xyz/bizclaw.md`
- REST API docs: `https://bizclaw.xyz/api-docs`

## Core Rule

Never answer specific company facts from memory. For pricing, policies, features, contact details, availability, locations, services, bargaining, delivery, support, or anything else about a company, call the relevant BizClaw tool and answer from returned data.

If BizClaw data does not prove the answer, say that BizClaw does not have enough profile evidence. Do not guess.

## Tool Selection

- Use `search_companies` when the user wants to find companies by need, category, country, city, industry, service type, or natural language intent.
- Use `get_company` when you already have a company ID and need the full profile.
- Use `get_company_by_website` when the user gives a website, domain, or URL.
- Use `ask_about_companies` for recommendations, comparisons, specific company questions, follow-up questions, pricing/policy/feature questions, and uncertainty.
- Use `list_categories` when the user wants a category-filtered search and the correct BizClaw category is unclear.
- Use `create_proposal` only when the user wants a proposal or quote from one verified company.
- Use `create_batch_proposals` only when the user wants the same proposal sent to multiple verified companies, up to 10.
- Use `get_my_proposals` to check status and company responses for proposals.
- Use `reply_to_proposal` only after showing the company's response and collecting the user's reply.

## Search Workflow

1. Extract the user's intent: service needed, location, category, budget/pricing needs, urgency, and any must-have constraints.
2. Call `search_companies` with a clear natural language `query`.
3. Add filters only when the user gave them or they are unambiguous.
4. Prefer `is_verified: true` when the user wants quotes, trusted vendors, or companies ready for proposals.
5. Present a concise ranked shortlist with company name, why it matches, location/category, verification status, and notable caveats.
6. If `suggested_follow_up_questions` is present, ask one concise follow-up question after the shortlist unless the user's constraints are already complete.
7. Keep returned company IDs in working context for follow-up questions.

Use pagination with `offset` only when the user wants more options.

## Follow-Up and Comparison Workflow

When the user asks a follow-up about companies already found:

1. Call `ask_about_companies`.
2. Pass `context_company_ids` from the previous relevant results.
3. Compare only using returned BizClaw data.
4. If evidence is missing for one company, say so clearly instead of filling gaps.

When the user says a company was added, asks to check again, or asks for fresh results, re-call the relevant search or ask tool. Do not reuse stale results.

## Proposal Workflow

If the user chooses a verified company from search results or says they want to proceed with one, offer to create a proposal/quote request for that company. Do not create it automatically. First collect the required customer details, confirm the message that will be sent, then call `create_proposal`.

Before calling `create_proposal` or `create_batch_proposals`, collect all required fields:

- Real active customer email.
- Real customer name.
- Concrete request description.
- Target company ID or confirmed shortlist.
- Proposal type if needed: `custom` by default, `standard` only when the user is asking about a known standard offer.
- API key for proposal tools.

Do not invent, guess, or accept fake customer emails. Do not use disposable, placeholder, alias-only, or example emails for live proposals. If the user provides an invalid or fake-looking email, ask for a real active email before proceeding.

Before sending:

1. Confirm the selected company or companies.
2. Confirm the description that will be sent.
3. Confirm the customer name and email.
4. Then call the proposal tool.

For batch proposals:

- Maximum 10 companies.
- Send the same proposal text to each company.
- Use verified companies unless the tool result or user intent clearly supports another path.

## Proposal Status and Reply Workflow

Use `get_my_proposals` to check proposal status.

- Do not use `status_filter` by default.
- Only use `status_filter` when the user explicitly asks for one status, such as only pending proposals.
- Show the `companyResponse` field whenever status is `responded` or `rejected`.
- Do not tell the user that BizClaw will send email notifications.
- Do not promise proactive follow-up. Say the user can ask you to check anytime.

When replying to a company:

1. Show the company's latest response first.
2. Ask the user what they want to reply if they have not already provided it.
3. Call `reply_to_proposal` with the user's message.
4. Explain that the proposal is back with the company for review.

## API Key Safety

Proposal MCP tools accept `api_key` as an optional tool argument. If the MCP connection has an `X-API-Key` header configured, use that connection-level key instead of asking the user to repeat the key in every tool call.

- Never expose a real API key in the visible response.
- Never include a real API key in examples, screenshots, logs, or public text.
- If the user lacks an API key, direct them to register at `POST /api/v1/agent/register` with a real active owner email.
- If the user already configured the MCP connection with `X-API-Key`, do not ask for the API key again.
- If the user asks to rotate a key, update agent profile, or deactivate the agent, use or point to the REST-only account endpoints in the API docs. Do not pretend these are MCP tools.

## Response Style

For search results:

- Keep the first answer concise.
- Explain why each company matches.
- Mention verification status.
- Offer the next useful action: compare, inspect one company, ask a follow-up, or prepare a proposal.

For recommendations:

- Prefer clear tradeoffs over generic ranking.
- Separate confirmed facts from missing evidence.
- Do not overstate match quality if returned data is thin.

For proposals:

- Be explicit about what will be sent.
- Ask for missing real customer details.
- After sending, summarize company names, proposal status, and how the user can check responses.

## Failure Handling

- If a tool returns no companies, broaden the query, remove overly narrow filters, or ask one clarifying question.
- If a company ID is invalid or not found, search again by name or website.
- If proposal creation returns an API key error, ask the user to verify or rotate their key through the REST API.
- If a company is not verified and the proposal cannot be sent, tell the user and suggest verified alternatives.