mcp-server

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds the critical authentication requirement and clarifies that inquiryType selects buyer vs seller representation. It does not describe the response format or potential side effects, but the annotations cover the mutation safety profile.

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 five sentences and mostly front-loaded with the core action in the first sentence. The final sentence about providing the slug and message is somewhat redundant with the schema and earlier phrasing, but the overall length is appropriate for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has a small parameter set and no output schema, and the description covers the key operational aspects: auth, parameter semantics, and an alternative for finding slugs. It does not state what the response will be, but for a send-style tool this is a minor gap given the annotations.

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 0% schema description coverage, the description compensates by explaining all three parameters: slug (broker slug, findable via search_brokers), message (the message to send), and inquiryType (buying default vs selling, with explicit semantics). This provides the agent with the meaning needed to construct a correct call.

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 sends a contact message to a broker identified by their profile slug. It names the specific verb ('Send') and resource ('contact message to a broker'), which distinguishes it from sibling tools like contact_seller and search_brokers.

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 instructs to use search_brokers to find broker slugs and explains how to set inquiryType for buying or selling representation. It also states the prerequisite of an authenticated account, giving the agent clear context for when to invoke the tool. However, it does not explicitly contrast with the sibling contact_seller, though the name and context make this implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate the tool is not read-only and not destructive. The description adds the requirement for an authenticated account and implies an external side effect (sending a message). It does not disclose details like rate limits, success/failure behavior, or irreversibility, but for a simple message-sending tool this is reasonable. The description 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 front-loaded with the purpose in the first sentence and is generally compact. The sentence 'Provide the listing ID and the message to send' is somewhat redundant given the schema, but the overall length is appropriate and each other sentence contributes useful context.

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 two-parameter action with no output schema, the description covers the core aspects: what it does, the authentication requirement, and how to obtain the listing ID. It does not explain differences from contact_broker or what happens after sending, but these are minor gaps given the tool's low complexity.

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 has no property descriptions and schema coverage is 0%, so the description must compensate. It names both parameters ('listing ID and the message') and provides the crucial semantic link that listing IDs come from search_businesses. This is more than just restating the schema, adding practical meaning to the parameters.

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: 'Send a contact message to a seller on Venturu by their listing ID.' It identifies both the action (sending a message) and the resource (a seller via listing ID). The use of 'seller' differentiates it from the sibling tool contact_broker, which targets brokers.

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 guidance on prerequisites ('Requires an authenticated Venturu account') and tells the user to 'Use search_businesses to find listing IDs,' which is a helpful pointer. However, it does not explicitly distinguish when to use this tool versus the sibling contact_broker, so it falls short of giving full alternatives or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds limited behavioral context beyond that, such as the source of the slug, but does not detail response format, potential errors, or other nuances. Given the low bar set by the annotations, this is adequate but not rich.

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 the primary purpose and followed by usage guidance. Every word earns its place; there is no redundant information 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 single-parameter tool with no output schema, the description covers the essential points: what it does ('full details'), for which entity ('single broker'), how to identify it ('profile slug'), and where to get the slug ('search_brokers results'). It lacks some edge-case behaviors but is adequately complete for its complexity.

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 'slug' as a string with minLength 1, offering minimal meaning. The description compensates by specifying it's a 'profile slug' and instructing to use the slug from search_brokers results, adding practical context for how to populate the parameter correctly.

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 full details for a single broker (agent) by their profile slug.' This is a specific verb+resource combination that distinguishes it from siblings like search_brokers (search) and get_business (different resource). The clarification that 'broker' is an 'agent' further disambiguates the target.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage context: 'Call this when the user asks for more information about a specific broker' and instructs to use the slug from search_brokers results. This is clear guidance on when to use the tool, though it does not explicitly mention when not to use it or name alternatives like contact_broker.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it returns 'full details' for a single business, but does not elaborate on edge cases, response format, or any special behavior, which is acceptable but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise, purposeful sentences: the first defines the action, the second specifies when to use, and the third explains parameter sourcing. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only tool with one parameter and no output schema, the description covers purpose, usage, and parameter source. 'Full details' is somewhat vague about the return structure, but this is a minor gap given the tool's simplicity and good annotations.

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 no description for 'slug' (0% coverage), so the description fully compensates by explaining slug identifies the business and directing the user to retrieve it from search_businesses results. This is clear and actionable.

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 verb ('Get') and resource ('full details for a single business (listing)') with the mechanism ('by its slug'). It distinguishes from sibling tools like search_businesses and get_broker by focusing on a single business detail 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?

It explicitly says 'Call this when the user asks for more information about a specific business' and instructs to 'Use the slug from search_businesses results', giving clear when-to-use and input sourcing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds useful context beyond annotations: it specifies the return content (all industry categories and their business types with IDs) and the intended use as a discovery mechanism. It does not mention potential edge cases like pagination or locale, but for a simple read-only list tool this is reasonably 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 three sentences, each earning its place: first states the function and output, second explains the primary usage connection to search_businesses, third provides a 'call this first' instruction. No fluff or redundancy, and the key 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 parameterless, read-only list tool with good annotations. The description covers what it returns (categories, business types, IDs), how to consume the output (use businessTypeIds in search_businesses), and when to call it (first, when discovering IDs). Since there is no output schema, the description adequately explains the return semantics, making the tool complete for the agent to select and invoke 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 tool has zero parameters, so schema coverage is trivially 100% and no parameter explanation is needed. The description still adds semantic value by explaining how the output IDs connect to the businessTypeIds parameter in search_businesses, which helps the agent understand the meaning of the returned data even though there are no input parameters.

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 'Returns all industry categories and their business types with IDs,' using the specific verb 'Returns' and naming the resource (industry categories/business types). It also distinguishes itself from sibling tools by explicitly noting the IDs are used in search_businesses, so its purpose is well-scoped and differentiated.

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 when-to-use guidance: 'Call this first when you need to discover which IDs to use for a given industry or business type.' It also directs the user to the dependent tool search_businesses with the parameter name, effectively naming an alternative/complementary tool and how this one fits into the workflow.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that it returns 'all' languages, implying a complete list without pagination, but it does not describe the response format or any additional behavioral nuances. This is similar to the get_calls calibration example: it adds some context but lacks rich behavioral detail.

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 three sentences, each earning its place: it states the output, gives a concrete usage example with a sibling tool, and specifies when to call it. There is zero wasted verbosity, and the structure is logical.

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 parameters, no output schema), the description is complete. It answers what the tool does, what is returned (languages with IDs), and how to use the result. It also integrates with the sibling tool landscape, making it fully actionable 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, so the schema is fully self-explanatory (100% coverage). The description doesn't need to add parameter details. Per the rubric, a baseline of 4 is appropriate for a zero-parameter tool, and the description provides no conflicting or redundant information.

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: 'Returns all languages with their IDs.' It identifies the resource (languages) and the output (IDs), and distinguishes itself from sibling tools by its focus on language reference data, not brokers or businesses.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'Use these IDs in search_brokers (languageIds) to find brokers who speak specific languages' and 'Call this when you need to discover which language IDs to use.' It tells the agent when and how to invoke the tool, which is exactly what the dimension asks for.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is known. The description adds valuable behavioral detail: it returns 'verified brokers' and states that 'email and phone' are redacted. This goes beyond annotations and gives the agent useful expectations about the response content.

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 and front-loaded with the core purpose. Every phrase earns its place: the search criteria, the platform, and the redaction behavior. 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?

The tool is relatively complex (12 params, nested object, no output schema). The description explains the high-level input categories and the redacted output, but it omits details about pagination, sorting, result structure, or what 'verified' means. Given the annotations provide safety context, this is adequate but with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It mentions 'location, name, languages' — mapping to several parameters — and 'and more' covers the rest, though vaguely. It does not explain specific parameters like opportunityScore, page, sort, or limit, but the property names in the schema are largely self-descriptive, so this is a minimal viable score.

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 verb ('Search') and resource ('business brokers (agents) on Venturu'), with specific search criteria ('location, name, languages, and more'). It distinguishes itself from siblings like get_broker (which implies fetching a single broker) and contact_broker (contact action).

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 that this tool is for finding brokers by various filters, which implies when to use it. It does not explicitly mention alternatives or exclusions, but the context is sufficient given the sibling tool names. A slightly more explicit 'use get_broker for a specific broker' would push it to 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context by noting that results are 'censored listing data' and that titles/addresses are handled according to listing visibility settings, going beyond annotation coverage.

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 four sentences: purpose first, then location/bbox guidance, range parameters, and output behavior. Every sentence adds necessary information with no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (38 optional parameters, no output schema), the description covers core search behavior and return characteristics but omits pagination (cursor/limit), ordering, and many filter categories, leaving notable gaps for a robust search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates by explaining the location parameter's natural-language support and the flat min/max range pattern. However, many of the 38 parameters (e.g., statuses, saleTypes, businessTypeIds) are not addressed, so the compensation is only partial.

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 'Search for businesses (listings) for sale on Venturu,' which clearly states the tool's purpose with a specific verb and resource. This differentiates it from sibling tools like search_brokers and get_business.

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 provides clear context on when to use the tool (searching businesses for sale) and how to use location/bbox and range fields. However, it does not explicitly mention alternative tools or exclusions, so it stops 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds 'Requires authentication' and the purpose of verification, which are behavioral traits not covered by the annotations. No contradictions exist.

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: the first states the core function, the second gives a concrete use case. Every word adds value with no redundancy or irrelevant detail.

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 parameters, no output schema, strong annotations), the description sufficiently covers its purpose, usage, and authentication requirement. Return format details are not essential for the stated verification use case.

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, so the schema fully covers parameter semantics. The description correctly does not attempt to explain non-existent parameters, and the baseline for 0 params is 4.

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 'Returns the identity of the currently authenticated user' with a specific verb and resource. It distinguishes itself from sibling tools like get_broker and search_businesses, which focus on external entities rather than the authenticated user.

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 provides explicit usage context: 'Use this to verify that the connection is correctly authenticated (e.g. in the voice agent).' However, it does not explicitly name alternatives or when-not-to-use, though the sibling tools make the distinction clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.