Skip to main content
Glama

tree_find

Locate nodes in the Quern tree by identifier, field, kind, links, payload value, or rule condition without walking the tree; returns matching paths and summaries for follow-up retrieval.

Instructions

Search the Quern instead of walking it — when the user names an element, locate it in one call. query is a case-insensitive substring over a node's prose — id, name, kind, meta, every string in its payload and the sources its params cite — so the external identifier, definition or field name a user arrives with resolves to its node without knowing the path; kind/has_param match exactly; links_to finds every node referencing a path; payload matches payload FIELDS by value — {"state": "Opened"}, or {"state": ["Opened", "Proposed"]} for any of several — which is how you scope by state without a substring also matching the word in a description; under scopes to a branch; current_only drops nodes another node supersedes (the "what do we hold now?" query); where is a condition in the rule grammar, with self the node it is asked of — kind == 'state' nodes where len(linked(self, 'deadline')) == 0 — keeping the nodes it holds for, read-only, without writing a rule; unjudged counts the nodes it read something absent on. Returns paths + a one-line summary each; then tree_get the one you meant. Purely structural.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "tree_find"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindNo
limitNo
queryNo
underNo
whereNo
payloadNo
links_toNo
has_paramNo
current_onlyNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.13
    • addedInput schema / properties / where
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Where"
      +}
  2. First observedv0.1.2

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations supplied, the description carries the full behavioral burden and largely meets it: it declares the operation is non-mutating ("Purely structural", "read-only, without writing a rule") and specifies matching semantics precisely — case-insensitive substring for query, exact match for kind/has_param, payload matched by FIELD value rather than free text. It stops short of stating permission requirements or what happens when limit truncates results.

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?

The purpose is front-loaded in the first clause and the remaining text is a dense but purposeful enumeration keyed by backticked parameter names, sized reasonably against 9 undocumented parameters. It loses a point for being a single unbroken paragraph with no line breaks or grouping, and for spending a full clause on the non-existent `unjudged`.

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?

An output schema exists, so the description only needs to set expectations lightly, which it does ("Returns paths + a one-line summary each"). For a 9-parameter, zero-annotation tool it covers the matching model and read-only nature well; the residual gaps are the unexplained `limit`/pagination behavior and the dangling `unjudged` reference.

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 description coverage is 0% across 9 parameters, so the description must compensate, and it does for eight of them with real semantic detail (query scope, exact vs substring matching, payload's {"state": ["Opened","Proposed"]} any-of form, under's branch scoping, where's rule grammar with `self`). Two gaps: `limit` is never explained despite defaulting to 20, and `unjudged` is described at length but does not exist as a schema property, which is actively misleading.

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?

"Search the Quern instead of walking it — when the user names an element, locate it in one call" gives a specific verb (search/locate), a specific resource (nodes in the tree), and the trigger condition for reaching for it. It also closes the loop by naming the hand-off target ("then tree_get the one you meant"), so an agent can distinguish this from the sibling without opening either schema.

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?

"Search the Quern instead of walking it" states the alternative it replaces, and "then tree_get the one you meant" tells the agent which tool to call next with the returned path. Per-filter guidance is implicit in the parenthetical glosses (e.g. current_only is flagged as the "what do we hold now?" query), but there is no explicit statement of when this tool is the wrong choice beyond the tree_get hand-off.

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