Diamonds Expert

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds substantial context beyond annotations: USD reference output, shape-specific calculator behavior, preservation of table metadata, no invented shape discount, market variability, and explicit non-offer/non-transaction caveats. It does not discuss auth or rate limits, but the annotations lower that burden.

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 return value is front-loaded, but the description is longer than needed and includes multiple disclaimer/business-context sentences that do not directly help an agent decide how to invoke the tool. Some statements, such as the service/delivery sentence, are tangential to the tool call.

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

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

With no output schema, the description does a reasonable job explaining that it returns a Rapaport TABLE reference in USD and preserves related table metadata. It covers the main limitations and shape behavior, though it leaves usage routing and detailed output semantics somewhat underspecified.

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

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

Schema description coverage is only 20%, but the description clarifies important semantics for shape (round vs other named shapes using the Pear table) and origin (natural diamonds). It adds little meaning for carat, color, and clarity beyond their enums, so it only partially compensates for the low 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 states a specific verb and resource: it returns a Rapaport TABLE reference in USD for a natural diamond. It also clarifies that round uses the Round calculator while other named shapes use the imported Pear table. It does not explicitly differentiate itself from sibling tools.

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

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

It does not say when to use this tool instead of prepare_selection_request or get_expert_profile. The caveats about it not being an offer or guaranteed discount provide context, but not actionable when-to-use guidance or alternatives.

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, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds a useful boundary claim (the profile is 'verified' and 'author-approved', and no sales/catalogue activity or discount guarantees are involved), which sets expectations beyond the annotations. It says nothing about whether access is restricted, whether content changes over time, or how the data is sourced.

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

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

Two tight sentences with no filler, and the identity of the subject is front-loaded. The second sentence is a clipped list whose phrasing ('professional sourcing, certificate matching and delivery') is slightly opaque, but it stays compact and never buries the point.

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

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

For a zero-parameter read tool with no output schema, the description should give a clearer picture of what the returned profile contains. It names two broad artifacts (profile, service model) and some service facets but never enumerates the fields or sections an agent would receive. Combined with annotations that cover safety, this is adequate but leaves a real gap around return content.

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 takes zero parameters, so per the baseline there is nothing for the description to disambiguate. The description correctly makes no claims about inputs that could conflict with the empty schema. No additional value is possible or needed here.

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 resource: a verified public profile plus an author-approved service model belonging to a named expert. It is specific enough that an agent knows this returns descriptive information about a person and his services rather than an estimate or a request, though it never explicitly contrasts itself with the siblings. The hardcoding of a single individual is a slightly odd fit with the generic tool name.

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?

There is no 'use this when' statement and no reference to the alternatives estimate_rapaport or prepare_selection_request. At best, the exclusions ('no catalogue sales or guaranteed discount') imply an informational rather than transactional role, which the agent must infer on its own. The natural workflow of reading the profile before preparing a selection request is left unstated.

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 critical context: draft is AI-assisted, Telegram URL is for manual send, never contacts anyone, missing details returned as questions, reference_id expires after 30 minutes, and never invent a table price or discount. This goes well beyond what annotations provide.

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?

Description is front-loaded with core purpose, then constraints and workflow. It is appropriately sized for a complex 16-parameter tool, though slightly dense; could be bulleted for clarity. Every sentence adds useful 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?

Covers purpose, safety, key behavioral rules, and some workflow (show draft, missing details). But with 16 parameters and near-zero schema descriptions, it leaves many parameters unexplained and does not describe the return shape (no output schema) beyond 'returns questions' and 'draft'. Adequate but with clear gaps for an agent to call correctly without guessing.

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

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

Schema description coverage is only 6% (only origin has a note), so the description must compensate. It adds meaningful detail for reference_id (source, matching, 30-min expiry) and mentions budget/country missing details, but does not explain the other 13 parameters (e.g., cut, polish, symmetry, fluorescence, budget_scope, budget_currency, destination_country) beyond their enum values. Most parameter semantics are left to the schema names.

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

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

States a specific verb 'Prepares' and outputs 'draft marked as AI-assisted' and 'Telegram URL' for client review and manual send. Explicitly says it never submits, reserves, buys, or contacts anyone, distinguishing it from transactional tools and clarifying that it is a preparation step. Names estimate_rapaport as the source for reference_id, indicating sibling relationship.

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?

Instructs to show the full draft to the client before opening Telegram, and that missing budget/country details are returned as questions. Indicates reference_id must come from estimate_rapaport and match the stone, implying that tool should be used first. However, no explicit when-not-to-use or alternatives beyond estimate_rapaport are stated.

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