mcp-server

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

Annotations indicate this is a non-destructive write operation (readOnlyHint: false, destructiveHint: false). The description adds critical behavioral context not in annotations: the authentication requirement ('Requires an authenticated Venturu account') and the functional semantics of inquiryType options (buyer vs seller representation).

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?

Five sentences efficiently structured: purpose first, then auth requirement, parameter semantics, parameter logistics, and sibling reference. No redundant or wasted content; every sentence provides essential information not available in structured fields.

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 0% schema coverage and no output schema, the description successfully documents all input parameters and their semantics. It adequately covers the tool's purpose and usage context, though it could optionally clarify the delivery mechanism (e.g., email vs notification) or success indicators.

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 fully compensates by explaining all three parameters: 'profile slug'/'broker slug' for the slug parameter, 'message to send' for the message parameter, and detailed enum semantics for inquiryType including the default value and functional meaning of each option.

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 the specific action 'Send a contact message to a broker on Venturu by their profile slug', clearly identifying the verb (send), resource (contact message), target (broker), and method (profile slug). It distinguishes from siblings by referencing search_brokers for finding slugs and implicitly differentiates from contact_seller and get_broker.

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 prerequisites ('Requires an authenticated Venturu account'), provides clear when-to-use guidance for the inquiryType parameter ('buying' for buyer representation, 'selling' for seller representation), and explicitly names the alternative tool for finding broker slugs ('Use search_brokers').

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 declare readOnlyHint=false and openWorldHint=true. The description adds valuable behavioral context not in annotations: the authentication requirement ('Requires an authenticated Venturu account'). It does not mention rate limits or idempotency, but the auth disclosure is significant added value.

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 with zero redundancy: purpose (sentence 1), prerequisites (sentence 2), parameter mapping (sentence 3), and dependency guidance (sentence 4). Information is front-loaded with the core action, and every sentence earns its place.

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

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

Given the simple 2-parameter input, lack of output schema, and clear annotations, the description provides sufficient context for invocation. It covers purpose, auth, parameter semantics, and data sourcing. It could be improved by mentioning error cases (e.g., invalid listing ID) or response confirmation, but it is functionally 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?

With 0% schema description coverage, the description compensates by mapping the parameters semantically: 'Provide the listing ID and the message to send.' It also contextualizes listingId earlier ('by their listing ID'), clarifying that this integer identifies the seller's listing. This effectively bridges the gap left by the undescribed schema properties.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Send'), resource ('contact message'), target ('seller on Venturu'), and mechanism ('by their listing ID'). It clearly distinguishes from sibling tools like contact_broker by specifying 'seller' and 'listing ID' versus broker-focused alternatives.

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 states the prerequisite ('Requires an authenticated Venturu account') and names a specific sibling tool to use for dependency resolution ('Use search_businesses to find listing IDs'). It lacks explicit 'when-not-to-use' guidance but provides clear workflow context.

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 establish the safety profile (readOnly, non-destructive). The description adds valuable scope context ('full details', 'single broker') and workflow dependencies that annotations don't cover. Does not contradict 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 efficient sentences with zero redundancy. Front-loaded with the core operation, followed immediately by usage context and data dependencies. Every word earns its place.

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

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

For a low-complexity, single-parameter read operation, the description adequately sets expectations ('full details') despite lacking an output schema. Sufficient for an agent to understand the tool's role in the broker retrieval workflow.

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 effectively by explaining that 'slug' refers to a 'profile slug' and specifying its provenance ('from search_brokers results'), giving the agent necessary semantic context for the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('Get') + resource ('full details for a single broker') + identification method ('by their profile slug'). Explicitly distinguishes from search_brokers by specifying 'single broker' and referencing the sibling tool as the source of the slug parameter.

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 invoke ('when the user asks for more information about a specific broker') and provides clear prerequisite guidance ('Use the slug from search_brokers results'), establishing the workflow relationship with the sibling search tool.

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 declare readOnlyHint=true and destructiveHint=false, covering safety profile. The description adds 'full details' indicating return scope and establishes workflow dependency with search_businesses, but does not disclose error behavior (e.g., invalid slug), rate limits, or cache policies.

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 with zero waste: first establishes purpose/mechanism, second states trigger condition, third provides data source. Front-loaded with the core action and 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?

For a single-parameter read operation with annotations present, the description adequately covers purpose, usage context, and parameter source. Lacks only error handling documentation (e.g., 404 behavior), but this is acceptable given the tool's simplicity and absence of output schema.

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 coverage (slug has no description), the description compensates effectively by explaining the parameter represents a business identifier and explicitly stating its provenance ('from search_businesses results'), clarifying both semantics and valid values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verb 'Get' with resource 'business (listing)' and clarifies the retrieval method 'by its slug'. The parenthetical '(listing)' disambiguates the domain, and mentioning 'search_businesses' distinguishes this single-item retrieval from the search sibling tool.

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

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

Provides explicit when-to-use ('when the user asks for more information about a specific business') and explicit prerequisite ('Use the slug from search_businesses results'), establishing a clear workflow dependency on the sibling search tool.

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 cover safety profile (readOnly/destructive), so description adds valuable behavioral context: scope ('all' categories), return structure (categories, types, IDs), and workflow sequencing ('Call this first'). Does not mention pagination or rate limits, but compensates well for lack of output schema.

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

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

Three sentences with zero waste: sentence 1 states purpose, sentence 2 defines integration with sibling, sentence 3 provides sequencing guidance. Well front-loaded and appropriately sized for a zero-parameter lookup tool.

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

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

Given zero parameters and good annotations, the description is complete. It compensates for missing output schema by describing return contents (categories, business types, IDs) and sufficiently explains the discovery pattern workflow for tool selection.

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?

Zero parameters present, establishing baseline 4. Description appropriately focuses on return value semantics rather than parameters, explaining what IDs are returned and their purpose in lieu of an 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?

Description uses specific verb 'Returns' with clear resource 'industry categories and their business types with IDs'. It distinguishes from siblings like search_businesses by positioning itself as a discovery/lookup tool rather than a search or action tool.

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

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

Explicitly states when to use ('when you need to discover which IDs to use') and provides the exact workflow ('Call this first'). It names the specific sibling tool (search_businesses) and parameter (businessTypeIds) that consumes these IDs, creating clear usage boundaries.

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 value by emphasizing 'all languages' (confirming closedWorldHint=false with completeness guarantee) and explaining the ID workflow context, though it doesn't specify rate limits or caching.

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 with zero waste: first establishes purpose, second defines workflow with sibling tool, third specifies trigger condition. Perfectly front-loaded and appropriately sized for the tool's simplicity.

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?

Without an output schema, the description adequately explains the return value structure ('languages with their IDs'). For a zero-parameter lookup tool with clear annotations, this is sufficient, though explicit mention of return format (array vs object) would improve it further.

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?

Tool has zero parameters, establishing baseline 4 per rubric. Description correctly implies no filtering is needed or available, which aligns with the empty input 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 uses specific verb 'Returns' with clear resource 'all languages with their IDs'. It clearly distinguishes this lookup tool from sibling operations like search_brokers or get_broker by focusing on language metadata discovery.

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 call ('when you need to discover which language IDs to use') and provides exact downstream usage instruction ('Use these IDs in search_brokers (languageIds)'). Names the sibling tool directly, creating clear workflow 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?

The description adds valuable behavioral context beyond annotations by disclosing that returned brokers are 'verified' and that 'email and phone [are] redacted'—critical privacy and data quality information not indicated in annotations. No contradiction with readOnlyHint=true.

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 consists of two efficient sentences with zero redundancy: the first establishes purpose and filter capabilities, the second discloses return value characteristics. Every word contributes necessary 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 the rich parameter set (12 optional filters including nested objects) and lack of output schema, the description provides adequate but incomplete coverage. It establishes the core function and data redaction policy but leaves significant semantic gaps regarding parameter usage and return structure.

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 across 12 parameters, the description provides minimal compensation by grouping parameters into 'location, name, languages, and more'. It fails to explain complex parameters like the nested 'opportunityScore' object, pagination behavior (page/limit), or the 'sort' enum options.

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), resource (business brokers/agents), platform (Venturu), and primary filter categories (location, name, languages). It implicitly distinguishes from sibling 'get_broker' (single retrieval vs. search) and 'search_businesses' (brokers vs. businesses), though explicit differentiation would strengthen it further.

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 no explicit guidance on when to use this tool versus alternatives like 'get_broker' (when ID is known) or when to prefer 'contact_broker'. Usage context must be inferred from the tool name and parameter schema alone.

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?

Beyond the readOnlyHint annotation, the description adds crucial behavioral context that listings are 'censored' with visibility-controlled titles/addresses, and explains the flat range field convention (minX/maxX) which governs how to structure financial filter parameters.

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 tightly constructed sentences: purpose statement, location input options with examples, range field pattern with examples, and return data behavior. Every sentence earns its place with concrete examples and zero 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?

While it covers the primary search dimensions (location, financial ranges) and describes return behavior (censorship), it leaves many of the 38 parameters (visaQualified, sbaPrequalified, saleTypes, businessTypeIds, etc.) completely undocumented given the lack of schema descriptions.

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 across 38 parameters, the description compensates significantly by explaining the natural-language capability of the location parameter, its relationship with bbox, and the min/max range pattern that applies to numerous financial fields (price, revenue, profit, etc.).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Search') and resource ('businesses/listings') on a specific platform ('Venturu'), clearly distinguishing it from sibling tools like get_business (single retrieval) and search_brokers (different entity type).

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 two alternative input methods for location (natural language vs. bbox) and establishes the flat min/max pattern for ranges, but does not explicitly state when to use this tool versus get_business or other siblings, nor does it mention prerequisites.

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 declare readOnlyHint=true and destructiveHint=false, confirming safe read behavior. The description adds crucial behavioral context not in annotations: 'Requires authentication' - an important prerequisite for a tool that returns identity information. No contradictions with annotation hints.

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 earning its place: (1) purpose definition, (2) authentication requirement, (3) usage scenario. No redundancy or waste. Information is front-loaded with the core action in the first sentence.

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

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

For a zero-parameter identity tool with good annotation coverage, the description is complete. It covers what the tool returns (identity), prerequisites (authentication), and intended use case (verification), which is sufficient without an output schema.

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?

Input schema has zero parameters. Per scoring rules, 0 parameters establishes a baseline of 4. The description appropriately does not attempt to invent parameter semantics where none exist.

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 specific verb 'Returns' and clear resource 'identity of the currently authenticated user'. It clearly distinguishes from siblings (contact_broker, get_business, etc.) which operate on external entities rather than the current user's identity.

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 when-to-use guidance ('Use this to verify that the connection is correctly authenticated') with a concrete example scenario ('e.g. in the voice agent'). Lacks explicit when-not-to-use, though none is strictly necessary given the tool's unique self-referential purpose among siblings.

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