Skip to main content
Glama
Sign In
references

references

by sameeeeeeep
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

references_shortlist

Presents your chosen reference directions as picture cards, strongest first, each with a one-line reason it fits the project. Call it after picking ids from a suggestions pool so the person can select one.

Instructions

Show the person the references YOU chose for this project: pass the ids you picked from a references_suggest pool (call it with pool first), strongest first, each with a one-line why saying why it fits this project for this person. They appear as picture cards above the prompt; the person picks one with their next message.

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": {
      "ids": "<ids>"
    },
    "name": "references_shortlist"
  }
}

Input Schema

NameRequiredDescriptionDefault
idsYesReference ids from the pool, best first (8 is right).
whyNoid → one line on why it fits this project (shown on the card).
intentNo
mediumNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.9/5.0
Behavior4/5

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

With no annotations, the description carries the burden and does disclose non-obvious behavior: the result renders as picture cards above the prompt, the `why` line appears on the card, and the person responds with a pick on their next message. It omits side effects or failure behavior (e.g. what happens with ids not in the pool, or the 12-item ceiling).

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

Conciseness4/5

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

Front-loaded with the action and the source pool, and every clause adds something usable (ordering, rationale, card rendering, who picks). The second sentence is a long compound with parentheticals, which slightly hurts scannability but wastes no content.

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 4-param tool with a nested `why` object and no output schema, the description compensates well by describing the rendered output and the pick flow. The remaining gap is the undocumented `intent` and `medium` parameters and the maxItems limit, which the agent must discover from the schema.

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?

At 50% schema coverage, the description meaningfully explains `ids` (taken from the pool, ordered strongest first) and `why` (one line shown on the card), matching the schema's own text. But `intent` and `medium` are never mentioned in either schema or description, leaving two parameters entirely undefined to the agent.

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?

States a specific verb+resource: showing the person the reference shortlist you chose for this project, with ordering (strongest first) and per-item rationale. It names references_suggest as the source, which separates it from that sibling, though references_pick is only implicitly differentiated via 'the person picks one with their next message'.

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?

Gives an explicit prerequisite and workflow: 'pass the ids you picked from a references_suggest pool (call it with `pool` first)'. That is clear when-to-use guidance with a named alternative, but it doesn't state exclusions (e.g. when not to shortlist, or how this differs from references_pick/references_get).

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

Deploy Server

Other Tools