Read-only MCP for Oria CRM: properties, contacts, deals, viewings, agents, auctions.
Scored across 20 tools
Most tools target clearly distinct resource/action pairs, but fetch overlaps with get_contact/get_property/get_deal, and search overlaps with list_* for discovery. Descriptions largely clarify typed-id lookup vs detailed records and windowed vs exhaustive listing, so ambiguity remains limited.
Predominantly snake_case with consistent get_/list_/match_ prefixes, but bare fetch/search and noun-style crm_overview/social_performance/whoami introduce minor deviations. Still readable and mostly predictable.
20 tools for a multi-resource real-estate CRM spanning properties, contacts, deals, auctions, viewings, social, and publishing is somewhat heavy but each tool covers a distinct query. Reasonable, though bordering on bloated.
The surface is overwhelmingly read-only: there is no create, update, or delete for properties, contacts, deals, viewings, auctions, or listings, and several tools explicitly cannot mutate. This leaves major CRM lifecycle gaps, even though read/query coverage is broad.
Pipeline snapshot for this agency: open deals by stage with EUR value, cold-deal count, upcoming viewings (7 days), contact and published-property counts. Call this first for any 'how are we doing / what needs attention' question.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is read-only, idempotent, and non-destructive, lowering the bar. The description adds useful behavioral context beyond annotations by revealing the data scope ('this agency'), the aggregated nature of the snapshot, and the specific metrics returned, including the 7-day window for viewings.
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 sentences, both valuable and front-loaded. The first sentence lists the actual data contents concisely; the second provides a direct, actionable usage instruction. No fluff or repetition of the title or schema.
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 zero-parameter, read-only overview tool with no output schema, the description is complete enough: it states purpose, contents, data scope, and when to call it. An agent can invoke it correctly and know what to expect without needing additional return-format details.
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?
The tool has zero parameters and 100% schema description coverage, so there is no parameter semantics burden for the description to carry. The baseline for 0-parameter tools is 4, and the description appropriately focuses on output semantics instead of parameter details.
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 with a specific verb and resource: a 'pipeline snapshot' for the agency. It enumerates the exact contents (open deals by stage with EUR value, cold-deal count, upcoming viewings, contact/property counts), making it easy to identify its scope and distinguish it from the more granular sibling list/get tools.
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 explicitly tells the agent when to use this tool: 'Call this first for any how are we doing / what needs attention question.' This provides clear usage context, though it does not explicitly name alternatives or state when not to use the tool, so it stops just short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one property, contact or deal by the typed id search returned (property:, contact:, deal:). Fetching a contact: id returns that contact's e-mail and phone — the same single-record exception get_contact has; search itself never returns either.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read-only/idempotent/non-destructive behavior. The description adds the typed-id format (property:<uuid>, contact:<uuid>, deal:<uuid>) and the contact-specific email/phone exception, including the fact that search never returns those fields. This goes beyond the annotation baseline, though it doesn't describe full return shapes.
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 focused sentences, front-loaded with the core operation and input format. The qualification about contact email/phone earns its place because it explains behavior that would otherwise be surprising. 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 one-parameter, read-only fetch with strong annotations, the description is nearly complete: input format, allowed types, and the notable contact-field exception. The only minor gap is that the return shape for property and deal fetches is not explicitly described, and there is no output schema to fill that in.
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?
The schema only defines id as a string with no description (0% coverage). The description fully compensates by specifying the expected typed-id format and accepted entity types, so an agent knows exactly what to pass.
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?
States the operation ('Fetch') and resource scope ('one property, contact or deal'), and specifies the input source ('typed id search returned'). The mention of the get_contact exception and 'search itself never returns either' helps distinguish this tool from search and the typed getters.
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 clearly frames when to use this tool: after search, with a typed id from the results. It does not explicitly enumerate when-not conditions or alternatives beyond the get_contact exception, but the context is unambiguous enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One open-house auction in full: clock, current price, leading paddle, the bidders waiting for approval (pendingBidders) and the approved paddles. Read-only — a bidder cannot be approved or declined through this endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| auctionId | Yes | Exact id previously returned by a read tool — never invent one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description reinforces this while adding the specific constraint that bidders cannot be approved or declined through this endpoint. It does not contradict any annotation and provides useful behavioral nuance beyond the generic read-only flag.
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 tight sentences: the first lists the returned content and scope, the second states safety behavior. No filler, and the most decision-relevant information 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?
This is a simple one-parameter read tool with annotations covering safety and idempotency, and the description enumerates the return fields despite the absence of an output schema. Nothing needed to invoke it correctly is missing.
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?
The single parameter auctionId is fully documented in the schema with format and the important guidance 'never invent one.' The main description adds no additional parameter semantics, but with 100% schema coverage the baseline 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 uses a specific verb-resource pair ('get auction') and enumerates exactly what is returned: clock, current price, leading paddle, pendingBidders, and approved paddles. The phrase 'one open-house auction in full' distinguishes it from the list_auctions sibling, so an agent can select it confidently.
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 clearly implies use when a single auction's full detail is needed and explicitly says it is read-only, so it should not be used to approve or decline bidders. It does not name list_auctions as the alternative for browsing or searching auctions, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One contact in full, plus their deals (stage, property, offer).
| Name | Required | Description | Default |
|---|---|---|---|
| contactId | Yes | Exact id previously returned by a read tool — never invent one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds context about the return content (full contact and deals), which is beyond the schema. However, it does not disclose any additional behavior such as error conditions, authentication needs, or limitations. Given the annotations, the added value is moderate but not extensive.
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 a single sentence that front-loads the primary purpose (one contact in full) and then adds the deals detail. No filler or redundancy. It is concise and every word earns its place.
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 tool with one parameter, no output schema, and annotations covering safety, the description sufficiently communicates what is returned. It does not specify behavior when no deals exist or error scenarios, but these are minor given the simplicity and the annotations. The description is adequate for an agent to call it correctly.
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?
The input schema has 100% description coverage for the single parameter contactId, with explicit instructions about using an exact ID from a read tool. The tool description adds no additional semantic meaning about parameters. Since the schema covers all semantics, a 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 the tool retrieves a single contact in full, including associated deals with specific fields (stage, property, offer). This distinguishes it from siblings like list_contacts (which lists many) and get_deal (which focuses on deals). The verb is implicit but the resource and scope are precise.
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 context implies use when a full single contact is needed, but no explicit guidance on when not to use it or alternatives is provided. The description does not mention that this is for a known contactId or that it should be used over list_contacts when only one contact is required. The usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One deal in full: property, contact, notes, offer, commission (both sides, expected and earned, and its split between agents), and its viewings log.
| Name | Required | Description | Default |
|---|---|---|---|
| dealId | Yes | Exact id previously returned by a read tool — never invent one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered structurally. The description adds meaningful behavior beyond that by enumerating the exact payload contents (including the commission split between agents and the viewings log), which matters in the absence of an 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?
A single dense sentence that front-loads the core claim ('One deal in full') and then lists the payload. No filler, no redundancy with the title, everything earns its place.
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 no output schema, the field enumeration is exactly what an agent needs to judge whether this call returns the data it wants, and annotations plus the schema carry the rest. Only minor gaps remain (error behavior for a nonexistent or unauthorized deal id).
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% and the single dealId parameter already carries a UUID format, pattern, and the warning 'never invent one.' The description adds no additional parameter meaning, so the baseline 3 applies.
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 resource and scope: a single deal returned in full, with a concrete enumeration of the contents (property, contact, notes, offer, commission breakdown, viewings log). This clearly distinguishes it from the plural sibling list_deals, though it never names that sibling explicitly.
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?
Usage is only implied: 'One deal' suggests the single-record counterpart to list_deals, so an agent can infer the retrieval-by-id intent. However, there is no explicit when-to-use statement, no mention of alternatives (list_deals, search), and no note on what happens if the id is unknown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One property in full (facts, status, agent, owner contact id).
| Name | Required | Description | Default |
|---|---|---|---|
| propertyId | Yes | Exact id previously returned by a read tool — never invent one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read-only, idempotent, and non-destructive behavior, lowering the burden on the description. The description adds what the return value contains (facts, status, agent, owner contact id) but does not disclose behavior for missing properties, response format details, or any other edge-case behavior.
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 a single, efficient sentence that front-loads the core purpose and lists the key return components without any filler. Every word contributes to understanding the tool.
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 one-parameter, read-only getter with no output schema or nested objects, the description conveys the essential return contents and the parameter contract through the schema. It could be slightly more explicit about the full shape of the returned property, but nothing critical is missing for correct 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?
Schema description coverage is 100%, and the single parameter propertyId is already well-documented as an exact ID from a read tool that should never be invented. The description adds no additional parameter-level meaning, so the 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 identifies the resource (one property) and the scope ('in full') with a specific list of included data (facts, status, agent, owner contact id). This distinguishes it from sibling tools like list_properties (plural listings) and get_property_links (related links).
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 implies when to use the tool: when a single property's complete record is needed rather than a list or a link graph. However, it does not explicitly state exclusions, prerequisites, or compare against alternatives such as list_properties or get_property_links.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every link for a listing: the admin page, the brochure PDF (Property Report, A4), the public page (only when published on realoria.com), the agency's own listing URL if set, and the 3D tour. Return them as plain text URLs the agent can paste into WhatsApp.
| Name | Required | Description | Default |
|---|---|---|---|
| propertyId | Yes | Exact id previously returned by a read tool — never invent one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as read-only and idempotent. The description adds context beyond that: it returns plain text URLs, includes conditional availability (public page only when published, agency URL if set), and specifies the brochure PDF is A4. This enriches the agent's understanding without contradicting 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?
A single, efficient sentence that front-loads the purpose and lists all link types and the output format. No redundant words or 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 simple one-parameter read tool with a clear output description, the definition is nearly complete. It covers all link types, conditional behavior, and the output format. Minor gaps like the order of links or null handling are not essential for correct 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?
Schema description coverage is 100% and the propertyId parameter is well documented ('Exact id previously returned by a read tool — never invent one'). The tool description adds no additional parameter information, so the schema carries the burden; 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?
The description clearly states the tool retrieves all links for a listing and enumerates the exact types (admin page, brochure PDF, public page, agency URL, 3D tour). It specifies the output format (plain text URLs) and use case (WhatsApp), making it distinct from sibling tools like get_property which would return property details.
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 implies usage when the agent needs shareable URLs for a listing, and notes the public page is only available when published. It doesn't explicitly mention alternatives, but the purpose is unambiguous and self-contained, so an agent can infer when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What a listing still needs before it can go live: required gaps (blocking — e.g. no agent, no photos) and recommended ones. Item ids are stable keys (agent, photos, price, description, …). Reports the gaps only — nothing here publishes a listing or fills one in.
| Name | Required | Description | Default |
|---|---|---|---|
| propertyId | Yes | Exact id previously returned by a read tool — never invent one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context beyond the annotations: it reports gaps only and performs no publishing or mutation, and it notes that item ids are stable keys. This aligns with the readOnlyHint and idempotentHint annotations without contradicting them.
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 sentences convey the tool's purpose, gap categories, key stability, and non-mutating behavior with no filler. The most important information 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?
For a simple one-parameter read-only tool with complete annotations, the description sufficiently covers what the tool reports and what it does not do. It does not detail the exact output shape, but that is a minor gap given the straightforward nature of the 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?
The input schema already fully documents propertyId, including format constraints and the instruction to use an id returned by a read tool. The description adds no parameter-specific semantics, so the high schema coverage sets the baseline at 3.
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 purpose: determining what a listing still needs before going live, and distinguishes required blocking gaps from recommended ones. This separates it clearly from the sibling get/list tools by naming the resource and the kind of output (gaps only).
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 clearly implies when to use the tool: when checking listing readiness before publish. It also explicitly says it does not publish or fill gaps, which helps set expectations, though it does not name sibling alternatives or provide explicit when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This agency's listing agents (name, role, phone).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is established. The description adds useful output-scope details (agency-specific, name/role/phone) but does not disclose any additional behavior such as pagination, ordering, authorization requirements, or hidden filtering. This is adequate for a simple read-only list but adds only modest value beyond the 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 a single, compact sentence with no filler. The subject is front-loaded, and the parenthetical field list is the minimum needed to define the output shape. Every word earns its place.
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 tool's simplicity (no params, no nested objects, no output schema) and strong annotations, the description fully covers what an agent needs: the agency scope, the entity type, and the returned fields. Nothing critical is missing for a straightforward list operation.
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 zero parameters, schema coverage is 100% and there is nothing for the description to clarify about inputs. The baseline for zero-parameter tools is 4, and the description appropriately focuses on the output instead of inventing unnecessary parameter guidance.
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 identifies the exact resource ('this agency's listing agents') and the returned fields (name, role, phone), which clearly distinguishes it from sibling tools like list_contacts, list_properties, and get_agent-like operations. The title pairs well with the description, making the purpose immediate and unambiguous.
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 gives no guidance for when to choose this tool over alternatives among the 19 siblings. There is no mention of 'use this instead of list_contacts when...' or any context that would help an agent route between similarly named list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This agency's open-house auctions (draft, live, sold, passed, cancelled) with property, price and clock.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| status | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint). The description adds value by disclosing returned contents ('property, price and clock') and the status enum, though it omits pagination or default-filter behavior. With annotations present, this is adequate.
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?
One sentence, front-loaded with the resource and scope, followed by statuses and fields. There is no filler or redundant explanation—every phrase contributes.
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 no output schema, the description names fields but not the response shape or list behavior. It does not clarify whether all statuses are returned by default or how the status filter interacts. For a straightforward list tool, it is passable but leaves some 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 description coverage is 0%, so the description should compensate. It repeats the exact status enum values from the schema, adding limited meaning, but does not explain the limit parameter. Partial compensation for status, none for limit, so a baseline 3 is warranted.
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 verb ('List') and resource ('auctions') with scope ('this agency's open-house auctions'). It includes the statuses and fields, clearly distinguishing it from get_auction and other list_* siblings.
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 implies usage for listing auctions but does not explicitly say when to use it over get_auction or other list tools. It gives no when-not guidance or alternative recommendation, so the agent must infer from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search this agency's contacts by name/email/phone, optionally filtered by kind, status or tag. Returns ids you can use with other tools.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Free-text search over name, email, phone. | |
| tag | No | Only contacts with this tag. | |
| kind | No | ||
| limit | No | ||
| source | No | Only contacts who first came from this channel ('import' = a CSV import). | |
| status | No | ||
| ownerAgentId | No | Only contacts this agent is responsible for (id from list_agents). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is well covered. The description adds useful context: that results are ids usable with other tools, and that filtering is optional (all params optional). It does not discuss pagination or limit behavior, which would be welcome but is a smaller gap given the 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 concise sentences, front-loaded with the core action and scope, followed by the output-value note. No filler, no repetition of schema.
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 an unauthenticated, read-only list/search with no output schema, the description provides adequate context: what is searched, what filters are available, and what ids can be used for. It could note default limit or pagination behavior, but overall it is complete enough for correct 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?
Schema coverage is 57%. The description covers the main search fields (name/email/phone) and mentions kind/status/tag filters, matching several schema parameters. But it omits source, limit, and ownerAgentId, and does not explain the q parameter's max length or search scope. Baseline 3 is appropriate when the schema covers a good portion but description only partially compensates.
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 verb+resource ('Search this agency's contacts') and names the exact search fields (name/email/phone). It also distinguishes the output role ('returns ids you can use with other tools'), which separates it from get_contact. This is a clear, specific purpose.
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 implies a search/list context and mentions optional filters, but offers no explicit when-to-use versus siblings like get_contact, match_contacts_to_property, or search. The agent must infer that this is a broad lookup rather than a targeted fetch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deals with property and contact context. Default = open deals only, oldest stage-change first (most neglected first). cold marks deals sitting past their stage threshold (inquiry 3d, qualified 7d, viewing 7d, offer 5d).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| stage | No | Filter to one stage; overrides openOnly. | |
| source | No | Only deals that came from this channel. | |
| openOnly | No | Default true — only inquiry/qualified/viewing/offer. | |
| ownerAgentId | No | Only deals this agent is responsible for (id from list_agents). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond those annotations: default open-only, ordering by oldest stage-change, and concrete cold thresholds per stage. It does not contradict the 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 compact at two sentences with no filler, and the default/ordering behavior is front-loaded. The opening phrase 'Deals with property and contact context' is vague and could be clearer, but overall the structure is efficient.
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 5-parameter list tool with no output schema, the description covers defaults, ordering, and cold semantics, but it leaves ambiguous what 'property and contact context' means in the response and does not mention how to request closed deals via openOnly=false or pagination via limit. The schema covers the filters, so this is adequate but not fully 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?
Schema description coverage is 80%, so the schema carries most parameter meaning. The description adds the cold/stage-threshold concept, which helps clarify stage semantics, but it does not explain limit, source, or ownerAgentId beyond what the schema already provides.
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 title supplies the verb ('List deals') and the description adds scope ('with property and contact context') plus default filtering and ordering behavior. However, the first sentence is phrased ambiguously and the tool is not explicitly differentiated from get_deal or other list tools.
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 gives default behavior but no when-to-use guidance or alternatives. It never states when to prefer this over get_deal for a single deal, or over list_properties/list_contacts for those entities, and there are no exclusions or routing conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A listing's gallery photos in display order (first = cover), one mediaId and file name per photo. File names and order only: no image content is returned, and neither the cover nor the order can be changed from here.
| Name | Required | Description | Default |
|---|---|---|---|
| propertyId | Yes | Exact id previously returned by a read tool — never invent one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it returns only file names and order, no image content, and cannot change the cover or order. This goes beyond the annotations and helps set expectations.
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 sentences, front-loaded with the key purpose and output format, followed by explicit exclusions. Every sentence earns its place with zero waste.
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 read-only list tool with one parameter and full schema coverage, the description is nearly complete. It clearly states what is returned (file names and order) and what is not (image content, cover/order changes). The only minor gap is not describing the exact output structure, but since there is no output schema and the tool is simple, this is a small omission.
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 the schema already fully documents the single parameter (propertyId). The description doesn't add parameter-level detail beyond what the schema provides, but it does clarify the output context (gallery photos for a listing). 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?
The description states a specific verb ('list'), a resource ('a listing's gallery photos'), and the exact scope ('display order (first = cover)'). It also distinguishes itself from sibling tools by clarifying it returns only file names and order, not image content. This is clear and unambiguous.
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 implies when to use this tool: when you need gallery photo file names and order for a listing. It explicitly states what it does NOT do (no image content, no cover/order changes), which helps an agent avoid misusing it. However, it doesn't explicitly name alternative tools for those other operations, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This agency's property listings with status and asking price.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Matches title or address. | |
| city | No | ||
| kind | No | ||
| limit | No | ||
| status | No | ||
| transactionType | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnly, idempotent, non-destructive behavior. The description adds that results include status and asking price, which is mild useful context. However, it does not disclose default filtering behavior (e.g., whether archived/draft statuses appear), ordering, or pagination limits.
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?
A single, front-loaded sentence with no filler. It conveys the tool's core purpose immediately and every word earns its place.
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 tool with six optional parameters, no output schema, and minimal schema descriptions, the description is incomplete. An agent knows it lists properties but gets no guidance on filtering, result size limits, or what response shape to expect, making correct invocation and interpretation partially guesswork.
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 very low (17%), and the description does little to compensate. It mentions 'status' as an output field but does not clarify how q, city, kind, limit, status, or transactionType affect the query, even though those are the main ways to shape results.
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?
States a clear verb-resource pairing: 'list' + 'property listings', with scope ('This agency's') and key fields ('status and asking price'). It is distinguishable from siblings like list_agents, list_contacts, and get_property, though it does not explicitly contrast with the generic 'search' 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?
No guidance on when to use this tool versus alternatives. The description implies it lists agency properties, but does not say when to prefer it over search, get_property, or other list_* siblings, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Viewings in a date window (default: the next 7 days), with property and contact. Times are Europe/Bucharest.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| toIso | No | ISO datetime, default from + 7 days. | |
| fromIso | No | ISO datetime, default now. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive. The description adds operational details beyond annotations: the default date window, inclusion of property and contact, and the Europe/Bucharest timezone. It does not mention ordering or limit handling, but the safety profile is fully covered.
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?
One sentence, 16 words, front-loads the core purpose, and includes only necessary specifics: the default window, related entities, and timezone. Every word earns its place.
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 tool's simplicity (3 optional parameters, no output schema, read-only annotations), the description covers what it returns (viewings with property and contact), the defaults, and timezone. Minor omissions like sort order and pagination behavior are not critical to correct 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?
The schema documents fromIso and toIso with defaults, and limit has type/min/max. The description adds the combined default window and timezone context, but it does not explain limit or the exact ISO format beyond the schema. With 67% parameter coverage, the description provides some, but not complete, semantic support.
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 'Viewings in a date window (default: the next 7 days), with property and contact,' clearly identifying the resource (viewings), the operation (retrieval), and the scope. It is the only tool about viewings among siblings, so there is no ambiguity or confusion with other list_* tools.
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 clear context: this tool retrieves viewings within a date window, defaulting to the next 7 days, and specifies the timezone. It does not explicitly mention when-not-to-use or alternatives, but no sibling tool covers viewings, so the context is sufficient for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Which contacts with a recorded brief fit a listing — best first, with the reasons (budget, surface, rooms, zone). The call list for a new listing.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| propertyId | Yes | Exact id previously returned by a read tool — never invent one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds significant behavioral detail beyond annotations: it explains the ranking order ('best first'), the reasons included (budget, surface, rooms, zone), and the filter condition (contacts with a 'recorded brief'). This gives the agent a clear picture of what the call does and what the response looks like, going well beyond the structured metadata.
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 crisp sentences totalling about 25 words. The core action and output are front-loaded, and the second sentence adds a practical use context. Every word earns its place with no fluff or repetition.
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 read-only tool with two parameters and no output schema, the description conveys the essential return information: contacts ranked best-first with reasons. It also specifies the filter (recorded brief) and the use case. It does not mention pagination or limit defaults, but these are minor given the readOnlyHint and idempotentHint. The description is complete enough for an agent to call the tool correctly and interpret the result.
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?
The schema description for propertyId is explicit and useful ('Exact id previously returned by a read tool — never invent one'), but the tool description itself adds no parameter-specific information. The limit parameter is self-evident from its name and min/max, and the schema coverage is 50%. Since the description does not compensate for the undocumented limit, but the schema partially does, a 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 states a specific action (matching contacts to a property), defines the input (listing) and the output (contacts ranked best-first with reasons such as budget, surface, rooms, zone). It clearly differentiates from the sibling match_properties_to_contact (reverse direction) and from generic list tools like list_contacts. The verb 'which contacts fit' is active and precise.
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 phrase 'The call list for a new listing' gives a concrete use case, implying the tool is for when you have a listings and want to identify which contacts to call. It does not explicitly name alternatives or state when NOT to use it (e.g., for the reverse match), but the purpose is clear enough from the description alone. A score of 4 reflects solid contextual guidance without explicit exclusion of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Which of this agency's listings fit a contact's recorded brief — best first, with reasons. Needs a brief on the contact (get_contact shows it).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| contactId | Yes | Exact id previously returned by a read tool — never invent one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses useful behavior: it is scoped to this agency's listings, it requires a recorded brief, and it returns results ranked best-first with reasons. This adds meaningful context that annotations alone do not convey.
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 a single tightly-worded sentence that packs in function, scope, ordering, output rationale, and a prerequisite. There is no redundant or filler content; every element earns its place.
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 read-only tool with two parameters and no output schema, the description covers the core behavior, ranking, and prerequisite. It lacks explicit mention of the limit parameter and potential alternatives, but the provided context is otherwise sufficient for correct 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?
Schema description coverage is only 50%; contactId is well documented in the schema, but limit has no schema description. The tool description does not mention limit or how it affects results, so it fails to compensate for the undocumented parameter.
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, query-like phrasing ('Which of this agency's listings fit a contact's recorded brief'), clearly identifying both the resource (listings) and the target (contact's brief). It adds behavioral specificity with 'best first, with reasons' and naturally distinguishes itself from the inverse sibling match_contacts_to_property.
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 gives a clear prerequisite: 'Needs a brief on the contact (get_contact shows it).' This tells the agent when the tool is applicable and points to the right tool to verify the precondition. It does not explicitly name alternatives or exclusion cases, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search this agency's properties, contacts and deals by free text. Returns typed ids (property:, contact:, deal:) — pass one to fetch for the full record. Windowed, not exhaustive: properties are matched over the 100 most recently updated listings only, then title/address-filtered; deals are matched over the 50 oldest-in-stage OPEN deals only (inquiry/qualified/viewing/offer) — a won, lost or archived deal never appears here. Contacts are matched exhaustively (name/email/phone). For anything outside these windows, or an exhaustive list, call list_properties / list_contacts / list_deals directly. Never returns e-mail or phone — only fetching a contact: id does. incomplete, when present, names every kind ("properties"/"contacts"/"deals") whose own read failed — treat those kinds as not searched, not as "no matches".
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds important behavior beyond annotations: results are typed ids, properties/deals are windowed rather than exhaustive, won/lost/archived deals never appear, contacts are always fully matched, email/phone are never returned, and the 'incomplete' field semantics are explicitly spelled out.
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 dense but every sentence earns its place: it states the action, the output shape, the windowing rules, the exclusions, alternative tools, and the incomplete-field contract. The most important usage constraint ('Windowed, not exhaustive') 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?
There is no output schema, so the description must carry the return-format burden. It does: typed ids, incomplete-field behavior, scope limits for each record kind, and explicit exclusions. An agent has enough context to invoke this tool correctly and interpret its results.
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 0%, so the description must compensate. It adds that the single 'query' parameter is free text and that results are matched against names, addresses, emails, phones, and deal fields. It does not describe query syntax or case sensitivity, but for one free-text parameter this is reasonable.
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 opens with a specific verb and resource: 'Search this agency's properties, contacts and deals by free text.' It clearly distinguishes itself from sibling fetch/get/list tools by explaining it returns typed ids (property:<uuid>, contact:<uuid>, deal:<uuid>) rather than full records.
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 gives explicit routing guidance: for anything outside the windowed searches, or for an exhaustive list, call list_properties / list_contacts / list_deals directly. It also tells the agent to pass a typed id to fetch for the full record, and notes that contacts are matched exhaustively while properties and deals are windowed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The organization and user this connection reads for. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds only 'Read-only,' which is redundant with the readOnlyHint. No additional behavioral context is provided, such as authentication requirements, side effects, or output characteristics. The description carries minimal added value beyond the 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 a single sentence with no filler words. It is appropriately sized for a simple, parameterless tool and conveys its purpose in a compact form.
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 that there is no output schema, the description should clarify what the tool returns. It only says 'The organization and user this connection reads for,' which does not specify the return format or content. The description is cryptic and relies heavily on the title for meaning. For a tool with no parameters, this is incomplete guidance for an agent.
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?
The tool has zero parameters, and the schema fully documents this with an empty properties object. There is nothing for the description to add about parameters. The baseline of 4 is appropriate because there is no ambiguity to resolve.
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 'The organization and user this connection reads for' but lacks a clear verb like 'returns' or 'gets'. It reads as a noun phrase describing context rather than an explicit action, leaving the tool's function ambiguous. The title 'Who am I' provides some hint, but the description itself is not self-explanatory.
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 offers no guidance on when to use this tool versus alternatives. It does not mention any conditions, prerequisites, or exclusions, and there is no reference to sibling tools. An agent has no basis to decide when to call this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
list_contacts2 fields changedInput schema / properties / statusAdded value: +{
+ "enum": [
+ "new",
+ "contacted",
+ "active",
+ "client",
+ "inactive"
+ ],
+ "type": "string"
+}Input schema / properties / tagAdded value: +{
+ "description": "Only contacts with this tag.",
+ "maxLength": 200,
+ "type": "string"
+}list_contacts2 fields changedInput schema / properties / source / descriptionPrevious value: -"Only contacts who first came from this channel."New value: +"Only contacts who first came from this channel ('import' = a CSV import)."Input schema / properties / source / enumPrevious value: -[
- "manual",
- "website",
- "storia",
- "imobiliare",
- "auction"
-]New value: +[
+ "manual",
+ "website",
+ "storia",
+ "imobiliare",
+ "auction",
+ "import"
+]list_contacts1 field changedInput schema / properties / sourceAdded value: +{
+ "description": "Only contacts who first came from this channel.",
+ "enum": [
+ "manual",
+ "website",
+ "storia",
+ "imobiliare",
+ "auction"
+ ],
+ "type": "string"
+}list_deals1 field changedInput schema / properties / sourceAdded value: +{
+ "description": "Only deals that came from this channel.",
+ "enum": [
+ "manual",
+ "website",
+ "storia",
+ "imobiliare",
+ "auction"
+ ],
+ "type": "string"
+}list_contacts1 field changedInput schema / properties / ownerAgentIdAdded value: +{
+ "description": "Only contacts this agent is responsible for (id from list_agents).",
+ "format": "uuid",
+ "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+ "type": "string"
+}list_deals1 field changedInput schema / properties / ownerAgentIdAdded value: +{
+ "description": "Only deals this agent is responsible for (id from list_agents).",
+ "format": "uuid",
+ "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+ "type": "string"
+}crm_overviewfetchget_auctionget_contactget_dealget_propertyget_property_linksget_publish_checklistlist_agentslist_auctionslist_contactslist_dealslist_gallerylist_propertieslist_viewingsmatch_contacts_to_propertymatch_properties_to_contactsearchsocial_performancewhoamiRead-only MCP for Copart and IAA/IAAI search, history, filters, locations, shipping, and usage.
MCP server for SmartAgent CRM: leads, tasks, sales pipelines, property listings
Read-only property facts, indicative availability, authorised booking links and guest-safe support.
Read-only MCP server for interior design studios: projects, overviews, weekly activity. No writes.
Add one secure layer between your agents and this server.
social_performanceSocial performanceARead-onlyIdempotent Inspect
Which listings performed best on social: lifetime views/likes/comments/shares/saves per network for posts published in the last N days, ranked by views. Figures are the newest snapshot (totals to date), not a per-day sum.
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description's added value is the data semantics: 'Figures are the newest snapshot (totals to date), not a per-day sum.' This is a meaningful behavioral note that prevents misreading the metrics as daily activity. It also clarifies that metrics are lifetime totals per network, adding context beyond the structured fields.
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 no redundant filler. It front-loads the core purpose, then provides essential scoping and interpretation details. Every clause adds useful information, making it an efficient and well-structured definition.
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 no output schema, the description must convey the return shape, and it does: it lists the metrics, ranking order, and time filter. It also flags the snapshot semantics to set expectations. Minor gaps remain, such as not specifying the response format or whether platform is filtered, but these are inferable from the schema and the nature of the 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 description coverage is only 33% (only the 'days' parameter has a default noted). The description compensates partially by referencing 'last N days' (mapping to the 'days' parameter) and 'per network' (mapping to the 'platform' parameter), but it does not explain the 'limit' parameter or enumerate the supported platforms. The schema's enums and min/max provide some structure, so the gap is moderate rather than severe.
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 specifies the query ('Which listings performed best on social'), the resource (listings), and the exact metrics (lifetime views/likes/comments/shares/saves per network). It also defines the ranking criterion ('ranked by views') and the time window ('last N days'), making the tool's function unmistakable. This also differentiates it from sibling list tools like list_properties and search, which handle broader listing retrieval.
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 gives clear context for when to use the tool: when needing social performance for listings, with a defined time window and per-network breakdown. It does not explicitly name alternatives or exclusions, but the use case is unambiguous for an agent. The snapshot vs. per-day clarification also guides correct interpretation of results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.