Skip to main content
Glama

Query the repo map

map_query
Read-only

Find files and symbols matching a question using the local skillhawk map, returning line numbers so you can read only the relevant code before opening files.

Instructions

Find the files and symbols (with line numbers) that match a question, using the local skillhawk map (built by skillhawk map). Call this before opening files; then read only the lines it points to.

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": "map_query"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMax hits (default 8)
questionYesKeywords or a short question, e.g. "where is the security scan"

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.0

TDQS

A3.8/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds the important prerequisite that results come from the "local skillhawk map (built by `skillhawk map`)." However, it does not say what happens if the map has not been built or is stale, which is the main behavioral risk for a cached-index lookup. It adds real context beyond annotations but leaves that failure mode undisclosed.

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?

Two sentences, zero filler, and the return shape (line numbers) plus the workflow instruction are both front-loaded. Every clause earns its place.

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 lookup with no output schema, the description covers purpose, the index dependency, and the intended follow-up action. The only meaningful omission is behavior when the map is absent or outdated, which is minor given the tool's simplicity.

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%, including examples for the required `question` field and a default of 8 for `limit`, so the schema carries parameter meaning. The description adds no syntax, format, or tuning guidance for either parameter, making baseline 3 appropriate.

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 pairs a specific verb ("Find") with a specific resource ("files and symbols (with line numbers)") and scopes it to the local skillhawk map. An agent can tell exactly what it returns, though the description never contrasts it with any sibling tool, so routing relies on the agent inferring that this is the only search-style tool.

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?

It gives concrete workflow guidance: "Call this before opening files; then read only the lines it points to," which tells the agent both when to invoke it and how to use the output. It stops short of naming an alternative or a when-not-to-use condition, so it is clear context rather than full routing guidance.

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