Skip to main content
Glama

GetProposal

Read-onlyIdempotent

Read one schema proposal by its ID: title, description, status, author, the source variant, and the proposal variant with the ID of its latest launch. Also returns the latest revision (its ID, summary, schema check, and launch), every review with its decision and comment, and whether the source variant changed since the proposal was created. hasUpstreamChanges does not say which subgraphs changed upstream. The proposal variant starts as a copy of every subgraph on the source variant and is not updated automatically; it picks up upstream changes only when the author pulls them in. So a diff of the two variants also shows changes published to the source since the proposal was created or last pulled upstream, reversed as if the proposal made them. hasUpstreamChanges is always false for proposals created before Nov 15, 2024. To see what the proposal itself changes, read its latest check with latestRevision.checkWorkflow.id and GetCheckResults: the check's changes cover every revision of the proposal and leave out upstream changes. If you diff the variants, compare each source subgraph's updatedAt with when the proposal was created or last pulled upstream, and do not treat a subgraph that is on only one side as added or removed by the proposal. GetVariantDetails lists the subgraph names on each variant. The write tools for a proposal take the graph ID and the proposal variant name from this response. ReviewProposal and AddProposalComment take latestRevision.id, and PublishProposalRevision takes backingVariant.latestLaunch.id as previousLaunchId. Provide the proposal ID, which GetProposals returns.

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": {
      "proposalId": "<proposalId>"
    },
    "name": "GetProposal"
  }
}

Input Schema

NameRequiredDescriptionDefault
proposalIdYes

Output Schema

NameRequiredDescriptionDefault
dataNo
errorsNo
extensionsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds substantial semantics: the proposal variant is a non-auto-updating copy of the source variant, so a diff can show reversed upstream changes; hasUpstreamChanges never identifies which subgraphs; and it is always false for proposals created before Nov 15, 2024. These are real interpretation traps that structured fields do not convey. Minor gap: no statement about response size or pagination of reviews.

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 purpose and return contents, then caveats, with no filler sentences. However, the upstream-change caveat is spread across several sentences and the diff-comparison advice restates the same idea twice, so a bulleted structure would have improved scanability for a fairly long block.

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

Completeness5/5

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

For a complex read tool with an output schema, the description covers the non-obvious interpretive semantics (variant copy behavior, upstream-change flag limitations, legacy-cutoff date) and the downstream ID handoffs to ReviewProposal, AddProposalComment, and PublishProposalRevision. An agent has everything needed to call it and read the result correctly.

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

Parameters4/5

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

Schema coverage is 0% with one required string parameter, so the description must compensate; it does by telling the agent the proposalId comes from GetProposals. It adds no format or validation detail (e.g., ID shape), so it is helpful but not exhaustive.

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

Purpose5/5

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

Opens with a specific verb and resource ('Read one schema proposal by its ID') and immediately enumerates the returned facets (title, description, status, author, source variant, proposal variant, latest revision, reviews, hasUpstreamChanges). It is unambiguously distinct from GetProposals (the list tool) and from GetVariantDetails/GetCheckResults, which it names.

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

Usage Guidelines5/5

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

Explicitly routes the agent: use GetCheckResults with latestRevision.checkWorkflow.id to see what the proposal itself changes, use GetVariantDetails to get subgraph names, use GetProposals to obtain the proposalId, and this response supplies graph ID, variant name, latestRevision.id, and backingVariant.latestLaunch.id for the write tools. That is concrete when-to-use-this-vs-alternative guidance.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources