Skip to main content
Glama
Sign In
Align CLI

Align CLI

Official
by aligndottech
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

align_ask

Read-only

Ask natural language questions about past decisions and get answers with stated reasons and commit SHAs from the Align decision graph. Use it to understand how something works or what was decided.

Instructions

Ask a natural language question and get answers from the decision graph. Use this when the user asks "how", "what was decided about", or any question about past decisions. Each result carries reason: the stated reason extracted from the commit message, up to two sentences quoted as written. It may be null when the commit states no reason, and a null is not a claim that no reason exists. sha is the commit, when the result is one. Searches the hosted Align graph at https://api.align.tech.

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": {
      "question": "<question>"
    },
    "name": "align_ask"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMax answers (default: 8)
questionYesNatural language question about decisions (e.g. "do we use postgres", "how does auth work", "what was decided about caching")

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?

Annotations already declare a safe read-only operation, yet the description adds real value beyond them: it explains that results carry a `reason` field quoted from the commit message, that `reason` may be null and that null is not proof of absence, and that `sha` identifies the commit. It also discloses that queries hit a hosted graph at a specific endpoint. It omits result ordering and what `limit` truncation implies, keeping it short of a 5.

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?

Purpose is front-loaded, followed by usage triggers, then result-field semantics. The return-field sentences are earned because no output schema exists, though the phrasing around null `reason` is slightly repetitive. No filler sentences.

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 two-parameter read-only search with no output schema, the description covers purpose, triggers, response field meanings, and the hosted endpoint. Missing pieces like result ordering or how many results exist beyond `limit` are minor. Nothing essential to correct invocation is absent.

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?

Schema description coverage is 100%, so both `question` and `limit` are already documented with defaults and examples. The description adds no syntax, format, or interpretation guidance for either parameter. Baseline 3 applies when the schema does the explanatory 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?

States a specific verb and resource: ask a natural-language question, get answers from the decision graph. This is clearly distinct from write-oriented siblings like align_capture or align_backfill. It does not explicitly name a sibling such as align_search, so an agent cannot be certain how it differs from that tool without opening both schemas.

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 concrete trigger phrasing ('how', 'what was decided about', any question about past decisions), which is strong positive guidance. It offers no exclusions and does not point to alternatives, so the agent gets a clear context but no routing rule against align_search or align_get_decision_rationale.

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