Find HubSpot contacts by name, email, or company to retrieve matching profiles and core properties when you lack a contact ID.
Search HubSpot contacts by name, email, or company. Returns up to limit matches with their core properties. Use this before get_contact when you don't already have an ID.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | Free-text search — matches against name, email, company, and phone. |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses the return behavior ('Returns up to limit matches with their core properties') but does not clarify match semantics (fuzzy vs exact), sorting, empty-result behavior, or any access/permission requirements. This is adequate but leaves meaningful gaps.
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 two sentences, with the primary purpose first and usage guidance second. Every sentence adds distinct value and there is no filler.
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 low-complexity two-parameter tool, the description covers search scope and return count, but 'core properties' is vague and no output schema exists to fill that gap. It also does not specify match behavior or mention the search_deals/search_tickets alternatives, though the contact-specific focus partially compensates.
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 only 50%, so the description must compensate. It adds meaning to the limit parameter by explaining that it caps the number of returned matches, and it reiterates the query's field scope (though omitting phone, which the schema mentions). This is a useful addition over 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 states a specific action ('Search'), a concrete resource ('HubSpot contacts'), and explicit search criteria ('by name, email, or company'). It further clarifies the tool's role relative to get_contact by saying to use it when an ID is not already available.
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?
It explicitly directs the agent to use this tool before get_contact when no ID is available, which is a clear when-to-use rule. This also implicitly defines when not to use it (when an ID is known) and names the relevant alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.