Skip to main content
Glama

rr_preview_recommendation

Read-onlyIdempotent

Preview a recommendation before acting on it: check its kind, status, products, supplier, locations, and updated_at, then use that timestamp for safe draft, retry, or close actions.

Instructions

Preview a recommendation before acting on it: its kind, status, products, supplier and locations, and its current updated_at. Pass that updated_at as expected_updated_at to rr_create_draft_from_recommendation, rr_retry_recommendation_draft or rr_close_recommendation. Changes nothing; refused for an action that is already finished.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action_id": "<action_id>"
    },
    "name": "rr_preview_recommendation"
  }
}

Input Schema

NameRequiredDescriptionDefault
action_idYesThe recommendation id, from rr_list_recommendations.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.3.1

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 'Changes nothing' is largely redundant with structured data. The description does add genuine behavioral context beyond the annotations: the preview is refused when the action is already finished, which tells the agent about a failure mode it could not infer from readOnly/idempotent hints. It also names the returned fields, useful since no output schema exists.

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

Conciseness5/5

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

Two compact sentences, front-loaded with the purpose and the returned fields, followed by the operational hand-off. There is no filler, and the conditional clause about finished actions is placed last where it belongs.

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

Completeness4/5

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

For a one-parameter read-only tool with an output schema absent, the description covers what is returned, that nothing mutates, the downstream chaining contract, and a refusal condition — enough to invoke it confidently. The only meaningful omission is how it differs from rr_get_recommendation, which matters given the overlap in sibling names.

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

Parameters3/5

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

There is a single parameter with 100% schema description coverage, and the schema already says it is 'The recommendation id, from rr_list_recommendations.' The description repeats that provenance rather than adding new meaning to the parameter itself. Baseline 3 applies since the schema does the work.

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

Purpose4/5

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

The description gives a specific verb ('Preview') plus the resource ('a recommendation') and enumerates exactly what is returned: kind, status, products, supplier, locations, and updated_at. That is well beyond a tautology. It does not, however, distinguish itself from the sibling rr_get_recommendation, which an agent could plausibly choose for the same intent.

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

Usage Guidelines4/5

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

It states a concrete usage pattern: call this first, then forward the returned updated_at as expected_updated_at to rr_create_draft_from_recommendation, rr_retry_recommendation_draft, or rr_close_recommendation. That is explicit when-to-use guidance tied to named alternatives. The gap is that it never says when this is the wrong choice (e.g., versus rr_get_recommendation for a full record), so no exclusion is offered.

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