repowise

get_why

Uncover the reasoning behind code structure with decision records and commit evidence, before refactoring or deviating from established patterns.

Instructions

Why this code is shaped this way — decision records + evidence commits.

Call before refactors or pattern divergences. Query modes: a question
("why is auth using JWT?"), a file path (governing decisions + origin
story + alignment score), a question anchored to targets, or no query
(decision health dashboard). Falls back to git archaeology when no
decisions exist for a path — never empty. Evidence-bearing rows carry an
explicit ``provenance`` and self-contained ``evidence_refs``; matching ids
mean shared evidence, not independent corroboration. Every decision row
carries ``authority``: ``accepted`` means somebody signed it, ``candidate``
means nobody has yet. ``answer_basis`` names the strongest lane the response
rests on (decision, episode, rationale, archaeology, documentation,
candidate); only ``decision`` is a ruling, and ``candidate`` is the weakest
-- it means nothing cleared that bar.

Args:
    query: question, file/module path, or omit for the dashboard.
    targets: optional file paths to anchor the search, or to ask about on
        their own when there is no query.
    repo: usually omitted.
    id: decision or ``ev_...`` evidence id emitted by this or another tool.
    reference: structured evidence reference. Its id and repository are
        accepted together without caller translation.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`id`	No
`repo`	No
`query`	No
`targets`	No
`reference`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.48.0Sep 3, 2026

addedInput schema / properties / id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Id"
+}

addedInput schema / properties / reference

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Reference"
+}

First observedv0.1.0Jul 12, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly discloses fallback behavior ('Falls back to git archaeology when no decisions exist for a path — never empty'), evidence semantics ('matching ids mean shared evidence, not independent corroboration'), and the meaning of authority and answer_basis fields. This is rich, transparent behavioral context.

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?

The description is long but every sentence earns its place. It is front-loaded with purpose and usage, followed by behavioral nuances, then a structured Args section. The information density is high without redundancy, making it well-suited for an AI agent.

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?

Given the complexity (5 optional parameters, no annotations, 0% schema coverage), the description is remarkably complete. It covers all parameters, explains output semantics (authority, answer_basis, provenance), and describes fallback behavior. The presence of an output schema further relieves the need to detail return values, so nothing critical is missing.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate entirely. It does so admirably, explaining each parameter in the Args block: query (question, path, or omit), targets (anchor or standalone), repo (usually omitted), id (decision or ev_... format), and reference (id and repository accepted together). This goes far beyond the bare schema.

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 clearly states the tool's purpose: it retrieves decision records and evidence commits explaining why code is shaped a certain way. It also gives a specific use case ('Call before refactors or pattern divergences'). However, it does not explicitly differentiate from sibling tools like get_context or get_answer, so it falls short of a 5.

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?

The description provides clear usage context with 'Call before refactors or pattern divergences' and explains the various query modes (question, file path, anchored targets, no query). It does not, however, mention when not to use the tool or explicitly compare to alternatives, so it earns a 4 rather than a 5.

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

Deploy Server