BizClaw Business Directory MCP
Server Details
Search, compare, and contact real-world companies through a public MCP business directory.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.5/5 across 9 of 9 tools scored. Lowest: 3.9/5.
Each tool has a distinct purpose: searching, getting details, creating proposals (single/batch), listing proposals, replying, asking questions, and listing categories. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., search_companies, create_proposal, get_company). The verbs are clear and the naming is predictable.
With 9 tools, the set covers the core workflows of a business directory MCP without being over- or under-scoped. Each tool earns its place.
The tool surface covers search, retrieval, proposal creation (single and batch), proposal tracking, reply negotiation, and a question-answering fallback. No obvious gaps for the intended use case.
Available Tools
9 toolsask_about_companiesAsk About CompaniesAInspect
Ask a natural language question about companies and get AI-powered recommendations.
Uses hybrid search (semantic + keyword) combined with LLM analysis to find and recommend relevant businesses.
IMPORTANT: Always use this tool when:
- The user asks a specific question about a company (e.g., "do they offer bargaining?", "what are their prices?", "do they deliver to X?")
- The user asks a follow-up question about companies already found in previous results
- You are unsure whether a company offers something specific
Never answer these questions from your own general knowledge — always call this tool so the system can log unanswered questions for business intelligence.
Args:
question: Natural language question (e.g. "Which logistics companies offer cold chain delivery in Istanbul?")
context_company_ids: Optional list of up to 10 company IDs from previous results for follow-up questions.
ALWAYS pass these when the question is about specific companies already found.
Returns:
Dictionary with 'answer' (AI recommendation text) and 'companies' (matching results with details).
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | Optional UCP request metadata. Use {'ucp-agent': {'profile': 'https://agent.example/.well-known/ucp'}} for UCP-aware negotiation. | |
| question | Yes | Natural language question about companies, recommendations, pricing, policies, features, or follow-up context. | |
| context_company_ids | No | Optional company UUIDs from previous results for follow-up questions. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral traits beyond annotations: it uses hybrid search + LLM, logs unanswered questions for business intelligence, and emphasizes that the system should be invoked rather than using general knowledge. Annotations (readOnlyHint=false) are consistent with the logging side effect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose, explanation, important usage guidelines in bullet points, args, and returns. It is concise yet comprehensive, with no redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 params, 1 required, 100% schema coverage, output described), the description provides complete context: usage guidelines, parameter semantics, and return structure ('answer' and 'companies'). No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description adds significant meaning: it provides examples for 'question', and for 'context_company_ids' it explains the mandatory usage 'ALWAYS pass these when the question is about specific companies already found.' This adds context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Ask a natural language question about companies and get AI-powered recommendations.' It uses a specific verb (ask) and resource (companies), and distinguishes from sibling tools like search_companies by focusing on natural language queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'Always use this tool when: The user asks a specific question about a company...' and 'Never answer these questions from your own general knowledge — always call this tool.' It also mentions follow-up questions and context_company_ids usage, offering clear alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_batch_proposalsCreate Batch ProposalsAInspect
Create proposals to multiple companies at once (max 10).
Same proposal is sent to each company.
Args:
api_key: Your agent API key (starts with 'bzcl_sk_')
company_ids: List of company UUIDs (max 10, must be verified)
customer_email: Email of the end customer
customer_name: Name of the end customer
description: What the customer needs
proposal_type: 'standard' or 'custom' (default: 'custom')
Returns:
List of created proposals and any errors.
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | Optional UCP request metadata. Use {'ucp-agent': {'profile': 'https://agent.example/.well-known/ucp'}} for UCP-aware negotiation. | |
| api_key | No | Optional BizClaw agent API key starting with bzcl_sk_. If omitted, proposal tools use the X-API-Key MCP connection header when configured. | |
| company_ids | Yes | List of BizClaw company UUIDs. Maximum 10 for batch proposals. | |
| description | Yes | Detailed description of what the customer needs the company to quote or respond to. | |
| customer_name | Yes | Real end-customer name for the proposal request. | |
| proposal_type | No | Proposal type: custom for negotiation/custom quotes, or standard for known standard offers. | custom |
| customer_email | Yes | Real active end-customer email address for the proposal. Do not use fake or disposable emails. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool is not read-only, not idempotent, and not destructive. The description adds that the same proposal is sent to each company and returns a list of created proposals with errors. No contradictions, but minimal additional behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single-sentence purpose statement followed by a clear Args list and Returns note. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a complete input schema, annotations, and an output schema reference (though not shown), the description adequately covers the tool's functionality. However, it does not mention prerequisites like company access permissions or partial failure scenarios, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema provides 100% coverage with detailed descriptions for all 7 parameters. The description's Args section repeats these explanations with similar detail, adding little value beyond what the schema already offers. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool creates proposals to multiple companies at once (max 10) with the same proposal. The verb 'Create' and resource 'batch proposals' are specific, and the batch nature distinguishes it from the sibling 'create_proposal' tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit constraints (max 10 companies, same proposal sent to each) and detailed parameter descriptions including required fields and types. However, it lacks explicit guidance on when to use this vs the sibling 'create_proposal' tool, though the batch/single distinction is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_proposalCreate ProposalAInspect
Create a proposal/quote request to a verified company on behalf of a customer.
Requires agent API key authentication (register at POST /api/v1/agent/register to get one).
Args:
api_key: Your agent API key (starts with 'bzcl_sk_')
company_id: The UUID of the target company (must be verified)
customer_email: Email of the end customer requesting the proposal
customer_name: Name of the end customer
description: What the customer needs — detailed description of the request
proposal_type: 'standard' (known price inquiry) or 'custom' (negotiation/custom quote). Default: 'custom'
Returns:
Created proposal with ID, status, and company info.
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | Optional UCP request metadata. Use {'ucp-agent': {'profile': 'https://agent.example/.well-known/ucp'}} for UCP-aware negotiation. | |
| api_key | No | Optional BizClaw agent API key starting with bzcl_sk_. If omitted, proposal tools use the X-API-Key MCP connection header when configured. | |
| company_id | Yes | BizClaw company UUID returned by search_companies or get_company_by_website. | |
| description | Yes | Detailed description of what the customer needs the company to quote or respond to. | |
| customer_name | Yes | Real end-customer name for the proposal request. | |
| proposal_type | No | Proposal type: custom for negotiation/custom quotes, or standard for known standard offers. | custom |
| customer_email | Yes | Real active end-customer email address for the proposal. Do not use fake or disposable emails. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses that the tool requires authentication, company verification, and returns created proposal details. It explains proposal_type meaning and the need for real customer email. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one introductory sentence, a list of parameters with clear formatting, and a returns statement. No redundant or unnecessary information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, 4 required) and existence of an output schema, the description fully covers the tool's purpose, required inputs, authentication, and return value. It is complete without needing additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds substantial meaning beyond the schema: it specifies that api_key starts with 'bzcl_sk_', company_id must be a UUID from search_companies, customer_email must be real and not fake, customer_name is real end-customer, and proposal_type explains 'standard' vs 'custom'. This enrichment helps the agent choose correct inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a proposal/quote request to a verified company on behalf of a customer.' It uses a specific verb (create) and resource (proposal/quote request), and the title matches. Sibling tools include create_batch_proposals and reply_to_proposal, so this tool is well-distinguished as a single proposal creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the prerequisite of agent API key authentication and that the company must be verified. It provides context on when to use (on behalf of a customer) but does not explicitly mention when not to use this tool versus alternatives like create_batch_proposals or reply_to_proposal. However, the step-by-step parameter guidance implies usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_companyGet CompanyARead-onlyIdempotentInspect
Get full details for a specific company by its ID.
Returns the complete company profile including features, use cases, pricing, and contact info.
Args:
company_id: The UUID of the company (obtained from search results)
Returns:
Complete company profile dictionary, or an error if not found.
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | Optional UCP request metadata. Use {'ucp-agent': {'profile': 'https://agent.example/.well-known/ucp'}} for UCP-aware negotiation. | |
| company_id | Yes | BizClaw company UUID returned by search_companies or get_company_by_website. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive. Description adds specifics: company profile content (features, use cases, pricing, contact) and error behavior, providing useful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two paragraphs plus args/returns. Perfectly concise: every sentence adds value. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter retrieval tool with output schema indicated, description covers input source, return shape, and error case. Fully adequate for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, achieving baseline 3. Description adds value by specifying that company_id comes from search results, aiding proper invocation. Meta parameter is omitted but already documented in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Get' and resource 'full details for a specific company by its ID'. Distinguishes from sibling 'get_company_by_website' by specifying ID-based retrieval. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context that ID comes from search results and returns error if not found. Implicitly suggests using after search, but lacks explicit comparison with alternatives like 'get_company_by_website'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_company_by_websiteGet Company by WebsiteARead-onlyIdempotentInspect
Look up a company by its website URL.
Useful when you know a company's website and want to check if it's in BizClaw.
Args:
website_url: The company's website URL (e.g. "https://example.com" or "example.com")
Returns:
Company profile if found, or an error message.
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | Optional UCP request metadata. Use {'ucp-agent': {'profile': 'https://agent.example/.well-known/ucp'}} for UCP-aware negotiation. | |
| website_url | Yes | Company website URL or domain, for example example.com or https://example.com. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that it returns a company profile or an error message, giving useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two sentences plus an Args/Returns block. Every sentence adds value, and the purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one required parameter. The description is complete given the presence of an output schema and comprehensive annotations. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description's parameter explanation is redundant. It provides examples but adds little new meaning beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('look up') and resource ('company by website URL'). It clearly distinguishes from sibling tools like 'get_company' (by ID) and 'search_companies' (by text).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use: when you know a company's website and want to check if it's in BizClaw. It implies context but does not explicitly exclude alternative tools, which would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_my_proposalsGet My ProposalsARead-onlyIdempotentInspect
Get all proposals created by the current agent.
Use this to check proposal status and company responses.
Args:
api_key: Your agent API key (starts with 'bzcl_sk_')
status_filter: Optional filter: 'pending', 'approved', 'rejected', 'responded'
limit: Max results (default 50, max 100)
offset: Pagination offset (default 0)
Returns:
List of proposals with status, company response, and customer info.
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | Optional UCP request metadata. Use {'ucp-agent': {'profile': 'https://agent.example/.well-known/ucp'}} for UCP-aware negotiation. | |
| limit | No | Maximum number of results to return. Use 1-20 for searches and 1-100 for proposal lists. | |
| offset | No | Pagination offset. Increase with limit to fetch later pages. | |
| api_key | No | Optional BizClaw agent API key starting with bzcl_sk_. If omitted, proposal tools use the X-API-Key MCP connection header when configured. | |
| status_filter | No | Optional proposal status filter: pending, approved, rejected, or responded. Omit by default. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds minimal behavioral context beyond summarizing return fields, which is already covered by the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear purpose statement, usage line, and structured argument list. Slightly verbose in repeating defaults, but overall well-organized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given comprehensive schema, annotations, and output schema, the description adequately covers purpose, usage, and return format. Lacks error handling details but is sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented there. The description adds no significant new semantic information beyond restating defaults and types. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all proposals created by the current agent,' specifying the verb, resource, and scope. It effectively distinguishes from sibling tools like create_proposal or reply_to_proposal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use this to check proposal status and company responses,' providing clear context. Could be improved by noting when not to use it, but it is sufficient given sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_categoriesList CategoriesARead-onlyIdempotentInspect
List all available business categories in BizClaw.
Use these category names to filter search results.
Returns:
Dictionary with 'categories' list and 'total' count.
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | Optional UCP request metadata. Use {'ucp-agent': {'profile': 'https://agent.example/.well-known/ucp'}} for UCP-aware negotiation. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide safety and idempotency; description adds return format (dict with 'categories' list and 'total' count). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise, front-loaded, each sentence adds value. Includes a returns comment with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with no required parameters; output schema exists. Description fully covers purpose and usage. Complete for this context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description does not add parameter-level meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly specifies verb 'list' and resource 'categories' in BizClaw, and distinguishes from sibling tools that deal with companies/proposals or proposals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States to use category names to filter search results, providing clear context. Does not explicitly exclude alternative tools, but implicitly guides when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
reply_to_proposalReply to ProposalAInspect
Reply to a company's response on a proposal. Use this for back-and-forth negotiation.
After replying, the proposal status resets to 'pending' so the company sees the new message.
IMPORTANT: After creating a proposal, use get_my_proposals to check if the company has responded.
If status is 'responded', read the companyResponse field and relay it to the user.
If the user wants to reply, use this tool.
Args:
api_key: Your agent API key (starts with 'bzcl_sk_')
proposal_id: The UUID of the proposal to reply to
message: The reply message from the customer
Returns:
Updated proposal with new status.
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | Optional UCP request metadata. Use {'ucp-agent': {'profile': 'https://agent.example/.well-known/ucp'}} for UCP-aware negotiation. | |
| api_key | No | Optional BizClaw agent API key starting with bzcl_sk_. If omitted, proposal tools use the X-API-Key MCP connection header when configured. | |
| message | Yes | Reply message to send back to the company on an existing proposal conversation. | |
| proposal_id | Yes | BizClaw proposal UUID returned by create_proposal, create_batch_proposals, or get_my_proposals. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that replying resets proposal status to 'pending' so company sees new message. Annotations (readOnlyHint=false, destructiveHint=false) are consistent; description adds valuable behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with structured sections (main paragraph, IMPORTANT note, Args, Returns) and front-loads key information. Every sentence is relevant and no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a reply tool: covers pre-conditions, parameter details, behavioral effect, and output. With output schema present and sibling references, no gaps in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds meaning: explains api_key format ('starts with bzcl_sk_'), proposal_id source (UUID from specific tools), and message purpose. Returns note clarifies output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Reply to a company's response on a proposal', uses specific verbs and resources, and distinguishes from siblings like create_proposal and get_my_proposals by describing the negotiation workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: after creating a proposal, use get_my_proposals to check status; if 'responded', relay companyResponse; if user wants to reply, use this tool. References sibling tool and gives clear workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_companiesSearch CompaniesARead-onlyIdempotentInspect
Search for companies in the BizClaw business directory.
Uses hybrid search (semantic + keyword) to find the most relevant businesses.
Returns lightweight summaries to save tokens. Use get_company(id) for full details (contact, pricing, features, etc.).
Args:
query: Natural language search query (e.g. "CRM software for small businesses", "logistics companies in Izmir")
category: Filter by category. Use list_categories to see available options.
country: Filter by country (e.g. "Turkey", "United States", "Germany")
city: Filter by city (e.g. "Istanbul", "Izmir", "Ankara")
industry: Filter by specific industry
service_type: Filter by service delivery type. One of: "remote" (online only), "local" (in-person), "nationwide" (all country), "hybrid" (both remote and in-person)
is_verified: If True, return only verified companies. If False, return only unverified. Omit to return all.
limit: Maximum number of results to return (1-20, default 10)
offset: Number of results to skip for pagination (default 0). Use with limit to get next pages.
Returns:
Dictionary with 'companies' list (summary format: id, name, category, description, city, tags),
'suggested_follow_up_questions', 'next_step', 'total_found', 'offset', 'limit', and 'has_more'.
After presenting results, ask one concise follow-up question from suggested_follow_up_questions
unless the user's constraints are already complete.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | Optional city filter, for example Istanbul, Izmir, Ankara, or Berlin. | |
| meta | No | Optional UCP request metadata. Use {'ucp-agent': {'profile': 'https://agent.example/.well-known/ucp'}} for UCP-aware negotiation. | |
| limit | No | Maximum number of results to return. Use 1-20 for searches and 1-100 for proposal lists. | |
| query | Yes | Natural language search query describing the company, service, category, or buying intent. | |
| offset | No | Pagination offset. Increase with limit to fetch later pages. | |
| country | No | Optional country filter, for example Turkey, United States, or Germany. | |
| category | No | Optional BizClaw business category filter. Use list_categories when unsure. | |
| industry | No | Optional specific industry or vertical filter. | |
| is_verified | No | Optional verification filter. True returns verified companies only; false returns unverified companies only. | |
| service_type | No | Optional service delivery type: remote, local, nationwide, or hybrid. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive. Description adds hybrid search method, token-saving lightweight summaries, and response structure including suggested follow-ups. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then method, then guidance to sibling tool, then parameter list, then return format. Every sentence earns its place. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, output schema present, annotations, and 8 siblings, the description covers all aspects: purpose, parameters, return values, pagination, usage tips, and follow-up behavior. Very complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 10 parameters are described with additional context beyond schema: e.g., query example, category referencing list_categories, service_type enum values, limit range for searches vs proposals. Schema coverage 100% but description adds real value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches for companies using hybrid search, distinguishing it from get_company (full details) and list_categories (categories). The verb 'search' and resource 'companies' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using get_company for full details and list_categories for category options. Provides context on when to ask follow-up questions. Does not contrast with ask_about_companies but still clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!