Codna

Official

Overview Schema Source Related Servers Discussions Admin

codna_recall

Read-onlyIdempotent

Recall code behind a concept by searching the local on-device memory index, returning matching symbols and ranking explanations. Runs fully offline with zero LLM tokens and zero network calls.

Instructions

Recall relevant code from the local on-device Telys memory — semantic + lexical search over the symbols this machine has already indexed, with zero LLM tokens and zero network calls.

Use when you need the code behind a concept ("where is SARIF provenance validated?") rather than a whole-repo map (codna_triage) — and when you want it offline. The index is built on first use (an empty index auto-indexes the repo, once) and is stored outside the git checkout. On a fresh machine, first use requires the one-time free codna login device authorization (free community license); the on-device memory runtime arrives via the login-gated runtime install. After that, recall is fully offline with no key and no network calls.

repo: a local path or git URL (default: current directory, or the server default set by codna mcp start --repo). query: what to recall (required — an empty query returns an error string). service: optional service name to scope recall to one service in a monorepo (default: all services). language: optional language filter such as "python" (default: all indexed languages). final_k: maximum number of symbols to return (default: 8). Returns matching symbols, the ranking explanation, and the candidate count as JSON. Failure modes (missing query, Telys memory not installed, unreadable repo) come back as "codna_recall error: ..." text — the tool never raises.

Input Schema

TableJSON Schema

Name	Required	Default
`repo`	No	.
`query`	No
`final_k`	No
`service`	No
`language`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 23, 2026

TDQS

A5/5.0

Behavior5/5

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

Annotations already mark readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral context: zero LLM tokens/network calls, auto-index on first use, storage outside git, login requirement, and the explicit failure-mode contract ('never raises', returns error text). This goes well beyond the structured annotations.

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 organized in clear blocks: core purpose, usage guidance, parameter list, return format, and failure modes. While long, every sentence adds value and the critical scoping statement is front-loaded. No filler or redundancy.

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 tool's complexity (5 params, setup requirements, failure modes), the description covers everything an agent needs: return JSON shape, error handling, login flow, and default behaviors. The output schema exists but the description still summarizes the return structure, making it self-sufficient.

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 is the sole source of parameter meaning. It explains every parameter with concrete semantics: repo (path/URL, default), query (required, empty error), service (scoping), language (filter), final_k (count, default). This fully compensates for the schema's bare titles.

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?

The description opens with a clear, specific verb and resource: 'Recall relevant code from the local on-device Telys memory' with the mechanism 'semantic + lexical search'. It explicitly differentiates from codna_triage by contrasting 'code behind a concept' vs 'whole-repo map', so an agent can distinguish siblings without inspecting schemas.

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?

It provides explicit guidance on when to use it ('Use when you need the code behind a concept... and when you want it offline') and names the alternative (codna_triage). It also covers prerequisites like first-use login and the default repo behavior, leaving no ambiguity about invocation context.

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

Deploy Server