Search commercial real estate listings. Reads need no token; authoring is self-serve OAuth (DCR).
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.
Average 4.4/5 across 15 of 15 tools scored. Lowest: 2.9/5.
Each tool has a clearly distinct purpose: listing CRUD, attachment upload workflow, search with interpret, geocoding, saved searches, and registry retrieval. No two tools overlap significantly; even the upload-related tools (sign, confirm, attach) are sequential and distinct.
All tools follow a consistent verb_noun pattern in snake_case (e.g., create_listing, get_registry, search_listings). The naming is predictable and clear, with no mixing of conventions.
With 15 tools, the server covers the core functionalities of a commercial real estate listing system without being bloated. Each tool serves a necessary role, and the count feels well-scoped for the domain.
The tool set is missing critical lifecycle operations: there is no way to delete or archive a listing, nor any tool to publish/unpublish a listing. This leaves an obvious gap in the basic CRUD workflow, which will cause agent failures when users need to remove or finalize listings.
attach_listing_photoAttach Listing Photo ToolAInspectAttach a photo to a listing you own directly from its public URL — one call, no separate sign/upload/confirm. The server fetches the image and ingests it with auto-generated thumbnail/hero/full variants. Only https image URLs whose host is publicly routable are accepted. The photo is content-moderated (must be real-estate related and safe) before it can appear publicly — the returned snapshot includes the moderation_status (approved / rejected / escalated) and moderation_reason. A rejected or escalated photo will not be publicly visible and will block publishing until removed or replaced.
| Name | Required | Description | Default |
|---|---|---|---|
| hashid | Yes | Hashid of the listing to attach the photo to. | |
| source_url | Yes | Public https URL of the image to fetch and attach. Must point directly at an image (jpeg, png, webp, gif, avif, heic/heif) on a publicly-routable host. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even without annotations, the description thoroughly discloses behavioral traits: server-fetched image, auto-generated variants, content moderation, acceptance criteria (https, publicly routable host), and moderation effects (rejected photos block publishing).
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 (4 sentences), front-loaded with the essential purpose, and every sentence provides distinct value without 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?
Given the tool's complexity (single-step, moderation, constraints), the description covers all key aspects—fetching, ingestion, variants, moderation, and visibility impact—even without an output schema, it explains the returned snapshot fields.
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 parameters are documented. The description adds meaningful context beyond schema, such as accepted image formats and the requirement for publicly routable hosts for source_url.
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 attaches a photo to a listing from a public URL in one call, distinguishing it from sibling tools like 'sign_attachment_upload' and 'confirm_attachment_upload' by noting no separate sign/upload/confirm steps.
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 explains when to use this tool (direct URL attachment) and implicitly contrasts with multipart upload flows, but does not explicitly name alternative tools or provide when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
confirm_attachment_uploadConfirm Attachment Upload ToolAInspectFinalize an out-of-band upload after the file bytes have been PUT to the presigned URL. Verifies the stored object matches what was signed (size and content-type) and marks the attachment ready. Returns the attachment snapshot with its public variant URLs. Idempotent: confirming an already-confirmed upload returns the same snapshot.
| Name | Required | Description | Default |
|---|---|---|---|
| attachment_id | Yes | The attachment_id (ULID) returned by sign_attachment_upload. Confirm only after the file bytes have been successfully PUT to the presigned URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses verification of size and content-type, marking attachment ready, return of snapshot with URLs, and idempotency. Missing error behavior for mismatches, but overall transparent.
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, no redundant words, front-loaded with key action. Every sentence adds essential information.
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 one parameter and no output schema, the description covers purpose, usage timing, verification behavior, return content, and idempotency. Complete for this simple 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 100%, baseline 3. Description adds value by specifying the parameter comes from sign_attachment_upload and should be used only after successful PUT, which goes beyond the schema's description.
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 function: finalize an out-of-band upload after PUTting bytes to a presigned URL. It specifies the verb 'finalize' and the resource 'attachment upload', and distinguishes from the sibling 'sign_attachment_upload'.
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 when to use this tool (after PUT to presigned URL) and notes idempotency. Does not explicitly mention alternatives or when not to use, but the context is sufficient given sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_listingCreate Listing ToolAInspectCreate a new draft listing. Returns the full created listing exactly as stored, including its hashid and status. Pass an idempotency_key (any client-generated string, e.g. a UUID) to make the call safe to retry — re-sending the same key returns the original listing instead of creating a duplicate.
| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | City. | |
| unit | No | Unit or suite number, if applicable. | |
| state | Yes | State (2-letter abbreviation). | |
| county | Yes | County. | |
| latitude | Yes | Latitude coordinate. | |
| place_id | No | Place ID from geocoder. | |
| longitude | Yes | Longitude coordinate. | |
| postal_code | Yes | ZIP/postal code. | |
| listing_type | Yes | Listing type: sale or lease. | |
| property_type | Yes | Property type. Allowed values are listed under the property_type attribute returned by get_registry (e.g. industrial, office, retail, land). | |
| street_address | Yes | Street address of the property. | |
| idempotency_key | No | Optional client-generated key (e.g. a UUID) making this create safe to retry: re-sending the same key within 24 hours returns the originally created listing instead of a duplicate. | |
| formatted_address | No | Full formatted address string from geocoder. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the tool returns the full listing and is idempotent with a key, but lacks details on error handling, permissions, or side effects.
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 purpose. No redundant 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?
Despite no output schema, the description covers the return format. It addresses idempotency but omits error conditions and authorization needs. For a 13-parameter tool, it is reasonably 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 coverage is 100%, so parameters are well-documented. The description adds value by explaining the idempotency_key parameter and stating the return value includes hashid and status, going 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 creates a new draft listing, specifying the action and resource. It differentiates from sibling tools like update_listing and get_listing by focusing on 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 provides clear guidance on when to use the idempotency key for safe retries, but does not explicitly state when not to use the tool or how it relates to other tools like update_listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_attachmentDelete Attachment ToolADelete an attachment you own by its ULID. Soft-deletes the row so it no longer appears on the listing. Use this to clean up an abandoned upload (one you signed but never finished) or a photo you no longer want. Idempotent: deleting an already-deleted attachment succeeds.
| Name | Required | Description | Default |
|---|---|---|---|
| attachment_id | Yes | The attachment_id (ULID) of the attachment to delete, as returned by sign_attachment_upload / confirm_attachment_upload or listed in get_listing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond destructiveHint=true, the description discloses soft-delete behavior (row no longer appears on listing) and idempotency (deleting already-deleted succeeds). This adds meaningful context about consequences and 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?
Four sentences, each purposeful: operation, soft-delete behavior, use cases, and idempotency. The description is front-loaded with the core action and wastes no 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?
For a simple single-parameter deletion tool with no output schema, the description covers purpose, usage, behavior, and edge cases (idempotency). An agent has all needed context to invoke 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?
Schema description already covers the parameter thoroughly (ULID and source). The description adds no new meaning beyond 'by its ULID', so baseline 3 applies due to high schema coverage.
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 deletes an attachment by ULID, using a specific verb and resource. It distinguishes from sibling delete_saved_search by targeting attachments and adds ownership scope.
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 identifies use cases: cleaning up an abandoned upload or an unwanted photo. No alternatives are named because none exist, but the context is clear, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_saved_searchDelete Saved Search ToolADelete a saved search by its ID. Only the owner may delete their own searches. Requires authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The numeric ID of the saved search to delete (from list_my_saved_searches). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. Description adds that only the owner can delete and authentication is needed, which provides useful behavioral context beyond the annotation.
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 concise sentences with no wasted words. The action is front-loaded ('Delete a saved search by its ID').
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 delete tool with one parameter and no output schema, the description covers the core action, ownership restriction, and authentication. It could mention return behavior, but is otherwise sufficient.
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 parameter already has a descriptive comment ('The numeric ID... from list_my_saved_searches'). The description does not add further parameter details, so 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 explicitly states 'Delete a saved search by its ID', clearly identifying the verb (delete) and resource (saved search). It distinguishes from sibling tools like save_search and list_my_saved_searches.
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?
Description specifies that only the owner may delete and authentication is required, providing clear context for when to use. It does not explicitly state when not to use, but the ownership condition serves as an implicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
geocode_addressGeocode Address ToolAGeocode a free-form US address into coordinates and structured components (street_address, city, county, state, postal_code) plus a formatted address and place_id — exactly the identity fields create_listing requires. Use this first, then pass the result straight into create_listing instead of supplying your own coordinates.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | Free-form address to geocode, e.g. "3763 Imperial St, Frederick, CO 80516". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds useful behavioral context about output structure and integration with create_listing. Does not mention potential failure cases but overall helpful.
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, each earning its place: first defines purpose, second adds usage guidance. No wasted words, 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 no output schema, the description covers purpose, output components, and usage workflow. Sufficient for agent decision-making.
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% with an example in the parameter description. The tool description does not add additional semantic value 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?
Description clearly states the verb 'geocode' and resource 'free-form US address', listing specific output components and tying it to the sibling tool create_listing. 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?
Explicitly instructs to use this tool first before create_listing, and to avoid supplying own coordinates, providing clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_listingGet Listing ToolARetrieve the full details of a single listing by its hashid. Returns the complete ListingResource projection including parcel data, all attribute details, and attachments. Broker contact is included only when the requesting user is authorised.
| Name | Required | Description | Default |
|---|---|---|---|
| hashid | Yes | The short hashid of the listing (e.g. "a1b2c3d4"). Found in listing URLs and search hits. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds value by disclosing that broker contact is included only when authorized, providing 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?
Two sentences with no wasted words. Purpose is front-loaded, and essential information is provided efficiently.
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 exists, but description sufficiently describes return shape (ListingResource projection with parcel data, attributes, attachments) and conditional behavior. Adequate for a single get 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?
Schema has 100% description coverage for the only parameter (hashid), including format and source. Description does not add extra meaning beyond the schema, so 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 retrieves full details of a single listing by hashid, listing specific returned data (parcel data, attributes, attachments) and a conditional element (broker contact). This is specific and distinguishes from sibling tools like search_listings or create_listing.
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?
Clearly states when to use (get full details by hashid). Does not explicitly mention when not to use alternatives, but the context of sibling tools implies it is for single listing retrieval. Could be improved with explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_publish_statusGet Publish Status ToolAGet the status of your listing publishes. Pass a listing hashid for the detailed status of that listing's latest publish run — overall state (pending/running/completed/failed), current phase, per-step progress, and any failure reason. Omit the hashid to list your recent publish runs across all your listings. Use this to track a publish_listing call to completion.
| Name | Required | Description | Default |
|---|---|---|---|
| hashid | No | Optional. Hashid of a listing to get its latest publish run in detail. Omit to list your recent publish runs across all your listings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds valuable context about the tool's behavior: detailed status includes overall state (pending/running/completed/failed), current phase, per-step progress, and failure reason. It also clarifies the dual mode (detail vs. list) beyond the schema. No contradiction 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 front-loaded with the primary purpose, followed by concise explanations of both invocation modes and the usage context. Every sentence contributes useful information, 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?
Given the tool's simplicity (one optional parameter, no output schema, read-only annotation), the description is complete. It explains both modes, the kind of data returned (state, phase, progress, failure reason), and when to use it. No critical 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 100%, and the schema already explains the hashid parameter (optional, used for detailed status, omit for listing recent runs). The tool description essentially restates this, adding no new parameter meaning beyond 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: 'Get the status of your listing publishes.' It specifies two modes (with and without a hashid) and what each mode returns. This distinguishes it from siblings like publish_listing and get_listing.
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 usage guidance: 'Use this to track a publish_listing call to completion.' It names the related sibling tool (publish_listing) and indicates the intended scenario, though it does not explicitly list when-not-to-use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_registryGet Registry ToolAReturns the full attribute registry — every searchable and filterable field, its type, allowed values, and display label. Read this first to understand the schema before calling search_listings with attribute filters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly states it's a read operation that returns registry data. It goes beyond the annotation (readOnlyHint) by detailing the content (fields, types, allowed values, labels), which adds useful behavioral context.
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 core purpose. Every sentence earns its place with no redundant information.
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 no parameters and no output schema, the description is complete. It explains what the tool returns and provides the use case (prerequisite for search_listings), fitting well within the toolset.
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?
There are no parameters, so baseline is 4. The description doesn't need to add parameter info; the tool's purpose is fully conveyed without them.
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 ('Returns') and identifies the resource ('the full attribute registry') with details on what it contains (fields, types, allowed values, display label). It distinguishes itself from siblings by stating it's the schema to read before using search_listings with filters.
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 tells when to use: 'Read this first to understand the schema before calling search_listings with attribute filters.' This provides clear context and guidance, effectively directing the agent's workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
interpret_searchInterpret Search ToolATranslate a natural-language property-search sentence into a structured filter payload compatible with search_listings. Use this as a transparent intermediate step: pass the user's raw query here, then forward the returned filters — and the returned bounds, when present (they carry the "near " intent) — to search_listings.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | A natural-language property search sentence from the end user. Example: "industrial with rail access in Denver under $5m". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds behavioral context: it is a 'transparent intermediate step' that returns filters and bounds carrying 'near <place>' intent. No contradictions. The description enriches the agent's understanding of the tool's non-destructive transformation role.
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 long, front-loaded with the main purpose, and every sentence earns its place. No redundant or filler content.
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 low complexity (1 parameter, no output schema), the description is complete. It explains the input (raw query), the output (filters and bounds), and how to use the output (forward to search_listings). 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 parameter 'prompt' is well-described in the schema itself. The description adds further value by stating the parameter should be 'the user's raw query,' reinforcing its purpose and tying it to the usage instructions.
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 that the tool translates a natural-language property-search sentence into a structured filter payload compatible with search_listings. It uses a specific verb ('Translate') and resource ('natural-language property-search sentence'), and distinguishes itself from siblings by explaining its role as an intermediate step before search_listings.
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 when to use the tool ('pass the user's raw query here') and what to do with the returned data ('forward the returned filters... to search_listings'). It provides clear context, though it does not explicitly mention when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_my_listingsList My Listings ToolAList all listings owned or brokered by the authenticated user. Optionally filter by status. Requires authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by listing status. One of: draft, pending_payment, active, suspended, sold, leased, withdrawn. Omit to return all statuses. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, and the description adds behavioral context by specifying authentication needs and the scope (owned/brokered). This goes beyond the annotation, but lacks details like response format or pagination.
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, front-loaded with purpose, and no unnecessary words. It efficiently covers scope, filter option, and auth requirement.
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 low complexity (single optional param, no output schema, read-only), the description covers key aspects: scope, auth, filter. It could mention return format or pagination, but it's reasonably complete for a simple listing 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 100% with the status parameter fully described including allowed values. The description only repeats that filtering is optional, adding no new 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?
The description clearly states the tool lists listings owned or brokered by the authenticated user, using specific verbs and resource. This distinguishes it from sibling tools like search_listings, which is for broader 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 specifies authentication is required and that filtering by status is optional, providing clear context for usage. However, it does not explicitly mention when not to use this tool or suggest alternatives like search_listings for non-user listings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_my_saved_searchesList My Saved Searches ToolAList the authenticated user's saved searches, including their filters and alert schedule. Requires authentication.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true. The description adds that the operation requires authentication and includes details about the response (filters and alert schedule), providing 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 two sentences, no wasted words. The purpose is front-loaded: 'List the authenticated user's saved searches' immediately conveys the action.
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 no parameters and annotations covering read-only, the description is complete for a list tool. It could mention pagination or ordering, but the core functionality is well-covered.
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 and 100% schema coverage, the baseline is 4. The description adds meaning by specifying that the output includes filters and alert schedule, compensating for no output 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 lists the authenticated user's saved searches, including filters and alert schedule. It uses the specific verb 'List' and resource 'saved searches', distinguishing it from sibling tools like 'save_search' (create) and 'delete_saved_search' (delete).
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 requires authentication, a clear prerequisite. It does not explicitly state when to use versus alternatives, but given the tool's simplicity (no parameters), the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
publish_listingPublish Listing ToolAInspectKick off the publish pipeline for a draft listing. Enriches with AI, gathers market data, then transitions the listing to Active. Returns the pipeline ID to track progress. Fails with the unmet readiness checklist if the listing is not ready (including any photo that has not cleared content moderation).
| Name | Required | Description | Default |
|---|---|---|---|
| hashid | Yes | Hashid of the listing to publish. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description thoroughly discloses the pipeline steps (AI enrichment, market data, transition to Active), return value, and failure mode. Lacks mention of side effects or idempotency but still provides substantial behavioral insight.
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-load the main purpose, then efficiently convey process, return, and error behavior. No redundant 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?
For a single-parameter tool with no output schema, the description fully covers the return value (pipeline ID) and error condition (readiness checklist). No critical gaps remain.
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 covers the sole parameter fully with a description. The tool description adds no new parameter detail beyond restating its purpose, so 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?
Specific verb 'Kick off the publish pipeline' clearly identifies the action, and the resource is scoped to a draft listing. This distinguishes it from siblings like get_publish_status or update_listing.
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 it applies to draft listings and warns it fails if readiness checklist is unmet, including photo moderation. Does not explicitly name alternatives but the context is clear enough for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
save_searchSave Search ToolAInspectSave the current search as a named alert. The user will receive email digests when new matching listings appear. Requires authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | A human-readable name for the saved search. If omitted, a name is derived from the filters. | |
| query | No | The free-text query string, if any. | |
| filters | No | The structured filter map to persist (same shape as search_listings filters). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: it saves a search, triggers email digests, and requires authentication. It does not mention potential side effects like duplicate handling or mutability, but coverage is strong given the lack of 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 (three sentences) and front-loaded with the core purpose. Every sentence adds value without 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?
The description covers the main purpose and auth requirement but does not explain return values (e.g., no output schema). For a tool with three optional parameters, it 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 100%, so the parameters are already well-documented in the schema. The description adds no additional meaning beyond what the schema provides, warranting a baseline score of 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 clearly states the action ('Save the current search'), the resource ('search'), and the outcome ('as a named alert' with email digests). It distinguishes from siblings like list_my_saved_searches and delete_saved_search.
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 includes a prerequisite ('Requires authentication') but does not specify when to use this over alternatives like search_listings or list_my_saved_searches. Usage context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_listingsSearch Listings ToolASearch commercial real estate listings. Returns paginated hits with facet counts. For AI-driven search, call interpret_search first to convert a natural-language query into structured filters, then pass those filters — and its bounds, when present — here.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Defaults to 1. | |
| sort | No | Sort key. Valid values from get_registry sort_options (e.g. "listed_at:desc", "price:asc"). | |
| query | No | Free-text search query (street address, city, or keyword). Omit or pass null for no text filter. | |
| bounds | No | Geographic bounding box (degrees) limiting hits to an area. Forward the bounds returned by interpret_search verbatim to honour "near <place>" intent; omit for a nationwide search. | |
| filters | No | Structured filter map keyed by Typesense field name. Ranges as {min?, max?}, multi-select as string[], booleans as true/false. Call get_registry to see valid field names and allowed values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, which is consistent. The description adds that results are paginated and include facet counts, providing useful behavioral context beyond the annotation alone.
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 tightly-written sentences with no wasted words. First sentence states purpose and key features; second provides essential usage guidance. Front-loaded and 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?
Given 5 parameters, no output schema, and moderate complexity, the description is fully adequate. It covers functionality, pagination, facets, and integration with interpret_search and get_registry. No missing information needed for correct 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 covers all 5 parameters (100% coverage). Description adds value by explaining how to use bounds (forward from interpret_search) and filters (consult get_registry), which goes 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?
Description clearly states the tool searches commercial real estate listings and returns paginated hits with facet counts. It distinguishes itself from sibling tools like interpret_search (which converts natural language to filters) and get_registry (which provides valid fields).
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 instructs to call interpret_search first for AI-driven search, then pass its output filters and bounds here. This provides clear when-to-use guidance and differentiates from alternative workflows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
send_feedbackSend Feedback ToolAInspectFile feedback or a support ticket with the SPACEXPLORATION team: a bug report, feature request, question, or anything you would improve about the app or the MCP experience. Works anonymously — include a contact email if you want a reply.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Optional contact email if you or your human want a reply. Authenticated callers default to their account email. | ||
| message | Yes | The feedback itself — what happened, or what you would improve about the app or the MCP experience. Plain text, max 5000 characters. | |
| category | No | What kind of feedback this is. Defaults to "other". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the full burden. It discloses the key behavioral trait of anonymity ('Works anonymously') and explains the email condition for a reply. This goes beyond the schema by setting user expectations about privacy. A minor gap is the lack of any statement about what happens after submission (e.g., confirmation, ticket ID), but overall the essential behavior is transparent.
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 exactly two sentences, front-loaded with the action verb 'File' and clear subject matter. Every clause adds value: the first states the purpose and scope, the second explains anonymity and reply conditions. No wasted words or redundant elaboration.
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 feedback tool with full schema coverage and no output schema, the description covers the core purpose, acceptable content, and a key behavioral constraint. It doesn't describe the return value, but since no output schema is declared and the action is simple, this is a minor omission. The slight dual phrasing 'feedback or support ticket' could be seen as ambiguous but does not impair usability.
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 provides 100% parameter coverage, with detailed descriptions for email (optional, default to account email), message (plain text, max 5000 characters), and category (enum with default). The description adds only a restatement of the email-reply connection, which does not meaningfully extend the schema's clarity. 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 uses the specific verb 'File' with a clear resource ('feedback or a support ticket' with SPACEXPLORATION team) and enumerates acceptable content types (bug report, feature request, question, anything to improve). This clearly distinguishes send_feedback from sibling tools like search_listings or create_listing, which are all listing-related operations.
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 when to use the tool by listing the kinds of feedback that belong (bug, feature request, question, or any improvement). There are no alternative feedback tools among the siblings, so no explicit 'when-not-to-use' guidance is needed. The context is clear and immediately actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_listing_attributesSet Listing Attributes ToolASet broker-authored attributes on a listing you own. Pass attributes as a map of registry field name to value (the field names get_registry returns, e.g. {"attr_parking_spaces": 40, "attr_office_class": "Class A"}). Only fields get_registry marks "writable":true can be set; publish-time computed fields and hot columns (use update_listing for those) are rejected with guidance. Enum fields take the allowed value (or an array for multiselect); send null to clear a field. Returns the full updated listing.
| Name | Required | Description | Default |
|---|---|---|---|
| hashid | Yes | Hashid of the listing to update. | |
| attributes | Yes | Map of registry field name to value, e.g. {"attr_parking_spaces": 40, "attr_office_class": "Class A", "attr_industrial_rail_access": true}. Only fields get_registry marks "writable":true are accepted. Multiselect enum fields take an array of allowed values. Send null to clear a field. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true. Description adds that it returns the full updated listing and rejects non-writable fields with guidance. No contradictions, but could mention permission requirements if any.
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?
Four sentences, each conveying essential information: purpose, parameter format, constraints, and return value. No fluff, well organized.
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 two parameters and no output schema, the description adequately covers input and output (returns updated listing). Annotations cover idempotency. Could mention error cases but not essential for completeness.
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 value by explaining the map format (registry field names), enum handling (array for multiselect, null to clear), and acceptance criteria (writable). This goes beyond raw 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?
Description clearly states it sets broker-authored attributes on a listing one owns. It specifies the verb 'Set' and the resource 'listing attributes', and distinguishes from sibling tools by referencing update_listing for hot columns.
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 when to use: only for writable fields from get_registry. Also tells when not to use: for hot columns, use update_listing. Provides guidance on enum fields and clearing fields, helping agent decide correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sign_attachment_uploadSign Attachment Upload ToolAInspectBegin an out-of-band file upload. Returns a presigned R2 PUT URL and the headers to use; the file bytes are uploaded directly to storage, never through this channel. After PUTting the file, call confirm_attachment_upload with the returned attachment_id. Supports listings (photos, documents), users (avatar), and pages (cover, photos).
| Name | Required | Description | Default |
|---|---|---|---|
| size | Yes | Exact byte size of the file. Verified against the uploaded object at confirm time, so it must be accurate. | |
| filename | Yes | Original filename including extension, e.g. "front-elevation.jpg". Used to derive the storage key and extension. | |
| collection | No | Optional explicit collection: "photos", "documents", "avatar", "logo", or "cover". Omit to auto-route by MIME (images→photos, docs→documents). Singleton slots (avatar/cover/logo) must be set explicitly. | |
| content_type | Yes | MIME type of the file, e.g. "image/jpeg" or "application/pdf". Must match the collection whitelist. | |
| attachable_id | Yes | Identifier of the attachable resource. For "listing" pass the listing hashid (e.g. "d5yqqgoa") — the same id every read tool returns. For "user" pass "me" to attach to yourself. For "page" pass its numeric id. | |
| attachable_type | Yes | Morph alias of the resource to attach to: "listing", "user", or "page". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description fully carries the behavioral burden. It discloses that file bytes never pass through this channel, size is verified at confirm, and collection auto-routes by MIME. Could mention expiration of presigned URL or idempotency, but core behavior is 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?
Three sentences, each essential. First sentence states the action, second explains the follow-up, third lists supported types. No filler, front-loaded with key result.
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?
Describes the two-step flow and return of presigned URL/headers, but lacks details about the response structure (e.g., the attachment_id field hinted at), error conditions, size limits, or URL expiration. Adequate but not comprehensive.
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 significant value: examples for attachable_id (hashid, 'me', numeric id), explains collection auto-route logic, size verification at confirm time, and filename used for storage key. Goes well beyond 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?
Describes the tool as initiating an out-of-band file upload, returning a presigned URL and headers. Clearly distinguishes from confirm_attachment_upload and lists supported attachable types (listings, users, pages).
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 the two-step process: PUT to the presigned URL then call confirm_attachment_upload. Explains collection auto-routing and explicit setting. Lacks explicit when-not-to-use or alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_listingUpdate Listing ToolAUpdate a listing's parcel, pricing, or marketing data. Pass at least one group (parcel, pricing, marketing); send each group whole, not just the changed field. Returns the full updated listing exactly as stored.
| Name | Required | Description | Default |
|---|---|---|---|
| hashid | Yes | Hashid of the listing to update. | |
| parcel | No | Parcel/address fields to update: street_address, city, county, state, postal_code, latitude, longitude, and optionally unit, lot_acres, year_built, property_type. | |
| pricing | No | Pricing fields to update: listing_type (sale|lease); for a sale set sale_price (dollars), for a lease set lease_rate (per the lease_rate_period basis, default per_sqft_year) and optionally lease_rate_period (per_sqft_year|per_sqft_month|per_month|per_year). Omit the price and set price_on_request=true for "price upon request". Optionally expires_at (ISO date). | |
| marketing | No | Marketing copy to update: headline, summary, title_override, highlights (string[]). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint: true, which the description reinforces implicitly. The description adds value by stating the return behavior ('Returns the full updated listing exactly as stored'), but does not disclose potential side effects, auth requirements, or error scenarios.
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, no redundancy. First sentence identifies action and affected data groups; second sentence provides the key usage rule and return contract. 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 4 parameters (1 required) and no output schema, the description covers what can be updated, how to format input, and what is returned. Minor omissions: prerequisites (listing must exist), permissions, error handling. Still above average.
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%, but the description adds critical usage details: whole-group requirement, pricing logic (sale vs. lease, price_on_request), and field lists. This goes beyond the raw schema, justifying a score above baseline 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 clearly states the tool updates a listing's parcel, pricing, or marketing data. It uses a specific verb ('update') and resource ('listing'), and the clear data groups distinguish it from sibling tools like create_listing, get_listing, etc.
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 actionable guidance: 'Pass at least one group (parcel, pricing, marketing); send each group whole, not just the changed field.' This tells the agent how to structure input. While it doesn't explicitly list when not to use, the sibling set provides context for alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
withdraw_listingWithdraw Listing ToolAWithdraw a listing, removing it from public search. This is a terminal status — the listing cannot be re-activated; create a new listing instead.
| Name | Required | Description | Default |
|---|---|---|---|
| hashid | Yes | Hashid of the listing to withdraw. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint, but the description adds extra context: the operation is terminal and irreversible. This goes beyond the annotation by explaining the consequence, which is valuable for an agent deciding to invoke it.
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, each earning its place: the first states the core action and effect, the second explains the terminal consequence and alternative. No fluff or 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 one-parameter mutation tool with no output schema, the description covers the key aspects: what happens, the harsh consequence, and the fallback action. It is complete for the agent's needs.
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 hashid parameter is already defined as 'Hashid of the listing to withdraw' in the schema. The description does not add further detail about the parameter format or constraints, so it relies on 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 action ('Withdraw a listing'), the resource, and the immediate effect ('removing it from public search'). It distinguishes from siblings by emphasizing the terminal nature, which separates it from update/publish operations.
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 guidance: the status is terminal and the listing cannot be re-activated, with a clear alternative ('create a new listing instead'). This tells the agent when to use this tool and what to do if re-activation is needed.
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.
No comments yet. Be the first to start the discussion!