Search YOUR agency's CRM contacts by name, company, email or phone. Use to look a person up before logging a note or to check if they're already in the CRM. Requires an agency API key; only ever searches the calling agency's own contacts.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | Name, company, email or phone fragment to search for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. Description adds context about API key requirement and scoping to own contacts, which is useful 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?
Three concise sentences. First sentence states purpose, second gives use cases, third adds constraint. 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?
No output schema, but description adequately covers when and how to use. Could mention what fields are returned for completeness, but sufficient for simple search tool.
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 50% (only query described). Description reinforces query fields but doesn't mention limit parameter or its default/min/max values.
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 'Search YOUR agency's CRM contacts' with specific fields (name, company, email, phone). Distinguishes from sibling tools like create_contact and search_properties.
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 says when to use: 'before logging a note' or 'check if they're already in the CRM'. Also provides important constraint: 'only searches the calling agency's own contacts' and requirement for agency API key.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Most tools have clear, distinct purposes. Some confusion possible between search_properties and find_properties_by_description, but descriptions clearly differentiate structured vs. free-form. Also area_market_summary vs verified_valuation both provide market data, but different types (asking vs notary). Overall well-differentiated.
All tool names follow a consistent verb_noun snake_case pattern: create_contact, create_listing, find_contacts, get_property, list_agencies, log_note, search_properties, etc. Names are predictive and actions are clear.
14 tools is on the higher end of the ideal range (3-15) but appropriate for a property platform that covers both public MLS search and agency CRM functions. It could be split into two servers (public search vs. agency CRM) but still remains manageable.
Covers core flow well: location lookup, market context, search, property details, valuations, and agency CRM (contacts, listings, leads, notes). Minor gaps: no tool for updating a listing (create_listing only creates drafts), and no delete/update for contacts. But primary workflows are supported.
