agentmako

by drhalto

Overview Schema Related Servers Score Discussions

TypeScript

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.4.3
Disambiguation4/5
The tool set is large but each tool's description clearly distinguishes its purpose. However, the sheer number of tools with overlapping categories (e.g., multiple reef_* tools for inspection, multiple trace_* tools) could still cause misselection in an agent, even with detailed descriptions.
Naming Consistency5/5
All tool names follow a consistent snake_case pattern, typically comprising a noun or verb followed by descriptive terms (e.g., `agent_feedback`, `apply_patch`, `db_table_schema`). The naming convention is uniform and predictable.
Tool Count2/5
95 tools is an extreme number for an MCP server. While each tool may serve a specific purpose, the volume overwhelms the agent's ability to efficiently select among them. Most servers have fewer than 20 tools, making this count far above typical.
Completeness5/5
The tool surface is extremely comprehensive, covering the full lifecycle of code investigation, editing, database introspection, linting, verification, and feedback. There are no obvious gaps in the stated domain of a development agent.
Average 3.7/5 across 95 of 95 tools scored. Lowest: 2.5/5.
See the Tool Scores section below for per-tool breakdowns.
- 1 of 1 community issues answered or closed in the last 6 months
- 6 commits in the last 12 weeks
- Last stable release on July 2, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'label facts and findings', implying a write operation, but annotations declare readOnlyHint=true, creating a direct contradiction. No additional behavioral context is provided beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence but somewhat verbose with domain jargon ('Reef 10 evidence-confidence view'). Could be more concise without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description does not specify what the tool returns. It covers the labeling intent but omits details on parameter usage, side effects, or output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain any of the 5 parameters. No value is added beyond the schema definition.
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 labels facts and findings with specific confidence levels, distinguishing its function as an evidence-confidence viewer. However, it does not explicitly differentiate from the sibling tool 'evidence_conflicts'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'evidence_conflicts'. The description implies usage for labeling evidence but lacks explicit context or when-not cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds some context beyond annotations by mentioning 'expose watch/surface metadata'. Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. However, the description does not detail what happens to the watch mode or the nature of exposed metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is single-sentence and front-loaded, but it is too brief for a complex tool with 13 parameters. It sacrifices necessary detail for brevity, making it less useful than a slightly longer, more informative description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's high complexity (13 parameters, many enums, nested objects), the description is severely incomplete. It does not explain what a 'typed workflow packet' is, how watch mode works, or how to use the output schema. The description fails to provide enough context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, yet the description provides no information about any of the 13 parameters. It fails to explain what parameters like 'family', 'queryKind', or 'scope' mean or how to use them, leaving the agent without essential guidance.
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 identifies the tool's action (generate) and resource (typed workflow packet) and mentions key features (expose watch/surface metadata). However, it does not distinguish from sibling tools like 'context_packet' or 'verification_bundle_artifact', which may have overlapping purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description implies it is for generating workflow packets from query answers, but does not specify preconditions, exclusions, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds context about 'bounded change scope' and 'path-derived' computation but no deeper behavioral details beyond what annotations imply.
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?
Single sentence, 14 words, no fluff. However, conciseness sacrifices completeness given tool complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, nested objects, enums, and a large sibling set, the description is too brief. It does not explain key terms like 'direct surfaces' or 'one-hop dependent surfaces', and omits any guidance on required parameters or typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description does not explain any parameters. Parameters like startEntity, targetEntity, direction, traversalDepth have no additional meaning provided. The description fails to clarify the complex nested object parameters.
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 returns 'path-derived direct surfaces, one-hop dependent surfaces, and an explicit dependency order' for bounded change scope. It is specific but does not explicitly differentiate from sibling tools like graph_path or flow_map.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., graph_neighbors, graph_path). No exclusions or context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is clear. The description adds that it summarizes with evidence, but does not disclose potential costs or depth of analysis beyond that.
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?
Single sentence is concise and front-loaded with 'Answer tool for file questions'. Could be slightly more structured to separate input and output expectations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters and no schema descriptions, the description is insufficient. It omits parameter explanations and does not clarify what 'evidence' means, making the tool harder to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/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 explain parameters. It does not mention projectId, projectRef, or file at all, leaving agents to infer their meaning from context.
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 it summarizes a file's role, dependents, and notable risks with evidence. It distinguishes from sibling tools like file_facts or file_findings by focusing on a holistic summary, though it could be more explicit about what 'evidence' entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like file_facts or file_preflight. Without exclusion criteria or context, agents may misuse it when a more specific tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only, non-idempotent, and open-world. The description confirms persistence of findings and metadata, adding context beyond annotations. However, it does not disclose failure modes, rate limits, or other behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph of about 50 words. It front-loads the main purpose but uses jargon (canonicalHelper, Reef, AnswerSurfaceIssue) that may reduce clarity. It is somewhat concise but could be restructured for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, no descriptions, multiple sibling lint tools), the description is incomplete. It does not explain how to use parameters or when to select this tool over alternatives. The output schema exists but the description only vaguely mentions typed findings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no information about any of the 7 parameters, including the enum for verbosity. The description fails to compensate for the lack of parameter documentation, leaving agents without guidance on how to set inputs.
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 runs diagnostics on indexed files using rule-packs, including canonicalHelper checks and TS-aware diagnostics. It differentiates from siblings by noting it powers the answer loop and review_bundle, but does not explicitly distinguish from other lint tools like biome_diagnostics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit when-to-use or when-not-to-use guidance compared to alternative tools. It mentions consistency with answer loop and review_bundle, but lacks practical usage guidance or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds that it summarizes derived project state, which aligns with read-only behavior. No contradictions, but no further behavioral details beyond annotations.
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 description is a single sentence of 15 words, efficiently conveying the core purpose. It is front-loaded and avoids unnecessary verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description omits details about parameter distinctions, the nature of the handoff output, or any prerequisites. Given three parameters and no schema descriptions, the description is insufficient for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage, and the description does not explain any parameter's meaning or usage. Without clarifying projectId, projectRef, or limit, the agent lacks guidance on how to correctly invoke the tool.
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: summarizing recent answer traces, active unresolved focus, and recorded follow-up momentum for project-state handoff. It distinguishes from siblings by focusing on derived project state rather than raw artifacts or context packets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives. It only says 'Operator tool for derived project-state handoff,' implying use during handoffs but lacking when-not or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds the concept of tracing file dependencies through the import graph, confirming read-only nature. It does not contradict annotations and provides minimal additional 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the core purpose. It is concise but omits important details, making it not overly verbose but slightly under-informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters with 0% schema description coverage and the presence of sibling tools, the description fails to provide complete context. Missing parameter details and usage guidance make it inadequate for full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain the meaning or usage of any parameter. It only implies the 'file' parameter as the entry point, leaving projectId, projectRef, and depth undefined.
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 states it traces downstream impacts via import graph, using specific verb 'trace' and resource 'downstream impact'. It distinguishes from siblings like imports_cycles, imports_deps, imports_hotspots through its focus on dependency direction, but does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives or when not to use it. The description implies its use for finding dependents but lacks explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint, so the tool is safe and repeatable. The description adds that it derives issues from traces, which is consistent but does not elaborate on behavior beyond annotations. No contradiction.
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 description is a single sentence, concise and front-loaded. However, it uses abstract phrasing ('operator tool') that could be clearer. No unnecessary words, but slightly under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters, output schema exists), the description provides basic context about the output (current issue + follow-ons) but does not explain input constraints or the notion of 'recent unresolved project traces'. Completeness is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the meaning of any parameters (projectId, projectRef, limit). This is a critical gap; the agent cannot infer how to use these parameters from the description alone.
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 it derives the current issue plus follow-on issues from recent unresolved project traces, which specifies the verb and resource. However, the phrase 'operator tool for queue-oriented recommendations' is somewhat jargon-heavy and doesn't fully distinguish from sibling tools like 'suggest' or 'ask'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies it is for queue-based issue recommendations, but does not mention when not to use it or compare to siblings. This leaves the agent without clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. The description adds that the tool avoids broad lint/typecheck commands, which is behavioral context. There is no contradiction with annotations, and the description adds some value beyond the annotations.
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 description is a single sentence that is concise and front-loaded with the tool's purpose. There is no wasted text, though it could be structured with more detail if space allowed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description is minimal (one sentence) and does not cover parameter semantics, return value expectations, or usage constraints. With 8 parameters and zero schema descriptions, the description is incomplete for effective tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 8 parameters (e.g., projectId, files, severities). With no parameter information, the description fails to add meaning beyond the schema, which is a critical gap.
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 answers 'have any errors?' from maintained Reef findings and diagnostic readiness state, which is specific. It distinguishes from 'broad lint or typecheck commands' but could better differentiate from sibling tools like 'reef_agent_status' or 'reef_inspect'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for querying known issues without launching broad commands, providing some context. However, it does not explicitly state when not to use or list alternatives among the many sibling tools, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and idempotentHint, and the description reinforces that it is read-only and does not run diagnostics. No contradictions. Adds behavioral context about combining multiple state elements, but no additional depth beyond 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?
Two sentences, front-loaded with the core purpose. No wasted words. Efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters with no description coverage, the description is incomplete. An output schema exists, but without parameter semantics or usage guidance, the tool cannot be confidently invoked correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain any of the 9 parameters, leaving their semantics entirely unclear. Even though schema provides constraints, the lack of textual description forces the agent to guess parameter purposes.
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: 'Thin Reef verification query' that combines multiple state elements. It distinguishes itself from other tools by specifying it is read-only and does not run diagnostics, but does not explicitly differentiate from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description mentions it is read-only, implying no side effects, but lacks context on typical usage scenarios or when to prefer it over similar tools like verification_state.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and idempotentHint=true. The description adds that the basis is stable and identical inputs yield the same artifactId, reinforcing idempotency. No contradiction with annotations, and adds useful context beyond them.
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 description is two sentences, concise and front-loaded with the purpose. The second sentence adds a useful property without redundancy. Slightly more detail could be added without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (16 parameters, nested objects, output schema) and numerous sibling tools, the description is insufficient. It does not explain the output, the role of parameters, or how this tool fits among alternatives like verification_bundle_artifact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 16 parameters. The brief mention of components (implementation brief, change plan, etc.) does not map to specific parameters or their meanings, leaving agents with no guidance.
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 composes a review bundle from components (implementation brief, change plan, etc.) for reviewer-facing change inspection. However, it does not explicitly differentiate from sibling artifact tools like verification_bundle_artifact or task_preflight_artifact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that identical inputs produce the same artifactId for deduplication but provides no guidance on when to use this tool versus alternatives or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, covering safety traits. The description adds the context of internal import graph and cycle detection, but does not disclose any additional behavioral characteristics beyond what annotations provide.
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?
One short sentence with no redundancy. Could be slightly more structured (e.g., front-loading 'Detect circular dependencies...' but it remains concise and immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While outputs are presumably defined by the output schema (not shown), the description omits parameter semantics and does not clarify input requirements. For a tool that requires project identification, this leaves a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description does not mention or explain the two parameters (projectId, projectRef). The agent receives no guidance on what these parameters represent or how to fill them.
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 clearly states it detects circular dependencies in the indexed internal import graph, specifying the verb 'detect' and the resource 'circular dependencies'. This distinguishes it from sibling tools like imports_deps (dependency listing) and imports_impact (impact analysis).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or context. It lacks explicit 'when to use' or 'when not to use' instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to restate safety. It adds no additional behavioral context (e.g., rate limits, scope limitations). Baseline 3 is appropriate.
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?
Description is a single sentence, efficiently listing the reported categories with a front-loaded summary ('Thin Reef status query'). No wasted words, though listings could be more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations provide safety context, the description offers a reasonable overview of the tool's output categories. However, the lack of parameter semantics leaves a gap in usability, especially for a tool with 5 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only lists high-level status categories without explaining any of the 5 parameters (limit, projectId, focusFiles, projectRef, freshnessPolicy). This forces the agent to rely solely on parameter names, which is insufficient.
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?
Description uses clear verb 'report' and lists specific status categories (known issues, changed files, etc.), distinguishing from sibling tools like reef_known_issues or reef_scout. However, the term 'thin' is ambiguous, slightly reducing clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides no guidance on when to use this tool versus alternatives. No mention of context, prerequisites, or exclusions. The agent must infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it 'trace[s] a route,' consistent with the readOnlyHint=true and idempotentHint=true annotations. It adds context about matching files and nearby evidence, which goes beyond the annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise but slightly vague. It front-loads 'Answer tool for route questions,' which is helpful but lacks structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters (0% schema coverage) and an output schema present, the description is too brief. It omits parameter details and does not leverage the output schema context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/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 explain parameters. It does not mention projectId, projectRef, or route at all, leaving the agent to guess their meaning.
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 it is an 'Answer tool for route questions' that 'trace a route to the indexed handler, matching files, and nearby evidence.' It specifies the verb (trace) and resource (route), but does not differentiate from siblings like route_context or trace_edge, which also deal with routes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only says 'Answer tool for route questions,' implying its use for route-related queries. However, it provides no explicit guidance on when to use this tool over alternatives like route_context or trace_* tools, nor does it mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent. The description adds that it does not execute hidden planner logic, which reassures about side effects. This adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks detail on inputs and outputs. It front-loads the purpose but omits critical parameter guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters and no schema descriptions, the description is severely incomplete. It does not cover parameter roles, return type (though output schema exists), or constraints. The agent would struggle to use it correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fails to explain any of the 9 parameters, including 'question' which is required. The agent cannot infer correct parameter usage from the description alone.
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 states it as a workflow tool for tool-chain recommendations, specifying it selects a canonical workflow or short ordered sequence. It clearly distinguishes from siblings by its unique recommendation purpose, though it could be more explicit about the output format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It mentions 'without executing hidden planner logic', suggesting it is for static recommendations. However, it doesn't provide explicit when-to-use or alternatives, leaving the agent to infer from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds that symbols are indexed and declared, but no additional behavioral traits like error handling or scope. Adequate but not enriched.
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?
Single sentence, 12 words, no wasted text. However, it is too brief to cover needed information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values not needed. But description omits parameter guidance and context for optional params. Acceptable for a simple tool but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanation of parameters, only implicitly mentioning 'file'. No details on projectId or projectRef meaning or usage.
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 clearly states the tool lists indexed symbols declared in a file, using a specific verb and resource. It distinguishes from sibling tools like exports_of or imports_* which handle different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no exclusions or context. The description only states what it does, not when to choose it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint true, so the description need not restate safety. However, the description adds no behavioral traits beyond the annotation scope; it only describes scope of audit. It does not mention potential performance impact, permission requirements, or side effects like advisory acknowledgement. Scores 3 because annotations cover safety but description adds minimal 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?
A single sentence that front-loads 'Operator tool for tenant-boundary review' and efficiently specifies the audit targets. Every word adds value; no fluff. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having six parameters and an output schema, the description is extremely sparse. It does not explain the required acknowledgeAdvisory parameter, nor the optional parameters, nor when to invoke this tool. The agent is left uninformed about inputs, outputs, and context. Completeness is low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage, requiring the description to explain parameters. The description fails to mention any of the six parameters (projectId, projectRef, acknowledgeAdvisory, freshen, includeFullResults, maxPerSection). No parameter purpose is indicated, leaving the agent without guidance on how to set them.
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 uses a specific verb ('audit') and clearly specifies the resources audited: tenant-keyed tables, RLS posture, and RPC/code touch points. It explicitly distinguishes itself from generic security-score tools by stating 'without making generic security-score claims'. This clearly defines the tool's purpose and differentiates it from siblings like db_rls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives is provided. The phrase 'Operator tool for tenant-boundary review' suggests a niche but does not include when-not-to-use or alternative scenarios. There is no mention of prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds the behavioral nuance of 'indexed' symbols, indicating that only indexed exports are listed, which is valuable context beyond the annotations.
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 description is a single concise sentence that front-loads the core purpose. It is efficient, though it could expand slightly without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters and an output schema, the description fails to explain how to use the parameters (e.g., that 'file' is required) or what the output contains. The agent lacks essential context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage and the tool description does not mention any parameters, their purposes, or how they relate to the function, leaving the agent with no guidance.
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 uses the specific verb 'list' and clearly identifies the resource as 'indexed symbols that a file exports'. It distinguishes this tool from the sibling 'symbols_of' by narrowing to exports only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when needing a file's exported symbols, but it does not explicitly state when not to use it or suggest alternative tools like 'symbols_of' for all symbols.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description describes composing an artifact, suggesting a write operation, but annotations set readOnlyHint=true. This creates a contradiction as to whether the tool is read-only or produces new artifacts. The description adds some behavioral context about artifactId shifting, but the inconsistency undermines transparency.
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 description is short and front-loaded but could be more concise. It effectively communicates the core purpose and a critical caveat about artifactId, though the mismatch with parameters reduces overall clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, nested objects, and no schema descriptions, the description is insufficient. It does not cover parameters, output, or how to use the tool, leaving significant gaps despite having an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 8 parameters with 0% description coverage, and the description fails to explain any parameter. The parameters listed (projectId, queryKind, etc.) appear unrelated to the described purpose of composing an implementation brief and session handoff, causing confusion.
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 clearly states the tool composes an implementation brief and current session handoff into a typed handoff artifact, with specific verb 'compose' and resource identification. It distinguishes itself from sibling artifact tools by emphasizing session-scoped behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for capturing session state in an artifact and explicitly warns against deduplication on artifactId, but does not explicitly state when to use this tool versus alternatives like session_handoff or other artifact tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint and idempotentHint true, so the description is not required to restate those. However, the description adds no further behavioral traits (e.g., cost, permissions, failure modes). It only describes the composition, which is informational, not behavioral.
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 description is a single concise sentence with no fluff. It is front-loaded with the purpose. However, the dense technical jargon ('db_rpc-equivalent schema snapshot signature/body') may reduce clarity for some agents, but it is not excessive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, output schema present) and many siblings, the description is incomplete. It does not explain parameters or provide any usage context beyond the bundle composition. The output schema exists, so return values are covered, but parameter guidance is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description must compensate, but it does not explain any of the six parameters. Only rpcName is indirectly referenced. No semantic meaning is added for projectId, projectRef, schemaName, argTypes, or maxPerSection.
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 clearly states the tool combines multiple data sources (db_rpc-equivalent schema snapshot, schema_usage callers, trace_rpc refs, db_rls policies) into one bundle for a single RPC. It is specific and distinguishes from sibling tools like db_rpc, schema_usage, trace_rpc, and db_rls by being an aggregator.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for composing a neighborhood bundle but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or prerequisites. The context is clear but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly states that this is an 'Advisory Reef mutation' and lists what facts are persisted (size, mtime, line count, sha256, deleted state) and what is NOT done (no AST, imports, routes, schema). This adds meaningful behavioral context beyond the annotations (which only provide flags), though it could mention whether the mutation is reversible or has side effects.
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 description is concise (two sentences) and front-loads the purpose. However, it could be more structured to include parameter roles, which would improve usability without adding much length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 5 parameters, 0% schema description coverage, and an output schema that is not described, the description is incomplete. It lacks parameter explanations, output format, prerequisites, and side-effect details, forcing the agent to rely on external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the five parameters (projectId, projectRef, files, includeUnindexed, maxFiles). The mention of 'explicit files, watcher-dirty paths, or non-fresh indexed paths' alludes to filtering but does not map to the schema parameters. This is a critical gap.
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 uses a specific verb ('snapshot') and resource ('working-tree file facts'), clearly distinguishing it from siblings by stating what it does not do (AST, imports, routes, schema). It explicitly lists the fact types (size, mtime, etc.) and the scope (explicit files, watcher-dirty, non-fresh indexed).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like file_facts or file_edit. There are no explicit when-to-use or when-not-to-use statements, leaving the agent to infer usage context from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description confirms read-only nature and mentions pg_catalog, but adds little beyond annotations which already include readOnlyHint, idempotentHint, and openWorldHint. No additional behavioral traits disclosed.
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?
Single sentence, front-loaded with key purpose information. No fluff, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 undocumented parameters and many sibling tools, the description is insufficient for an agent to correctly select and invoke the tool. Output schema exists but does not mitigate parameter gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and description provides no information about parameters (projectId, projectRef, table, schema). The description does not compensate for missing schema descriptions.
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?
Description clearly states read-only tool for inspecting columns and primary-key details via pg_catalog, using specific verbs and differentiating from sibling tools like db_table_schema and db_fk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use for column questions but does not explicitly state when to use versus alternatives or provide exclusions. It lacks concrete guidance on context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds context about the output content (explicit facts and derived candidates), but does not disclose behavioral details like pagination, filtering behavior, or performance characteristics.
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 description is a single, information-dense sentence that front-loads the core purpose and lists examples. It is concise but could be slightly clearer by reducing jargon (e.g., 'Reef 9 convention view').
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 optional parameters and an output schema, but the description does not cover parameter usage or output structure. While the output schema provides return value details, the description should clarify how parameters affect results. Overall, it is adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description provides no information about the 5 parameters. While parameter names (projectId, kind, status, limit) are somewhat self-explanatory, the description fails to explain how they influence the tool's behavior or output.
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 clearly states the tool's purpose: surfacing explicit convention facts plus derived candidates, with concrete examples like auth guards and route patterns. It distinguishes itself from sibling tools by focusing on conventions specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention when to prefer this over other tools like reef_inspect or reef_instructions, nor does it specify any conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. The description adds context about ranking by connectivity but does not disclose other behavioral traits such as data freshness or limitations. With annotations covering safety, the description adds some value but not extensively.
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 a single, concise sentence that front-loads the purpose. Every word is necessary, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the output schema covers return values, the description does not specify what 'most connected' means (e.g., incoming vs outgoing imports). The lack of required parameters in the schema could lead to confusion about whether projectId and projectRef are needed. More context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the purpose of projectId, projectRef, or limit. The names and constraints imply project identification, but without explicit documentation, the agent lacks clarity on how to set these parameters correctly.
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 clearly states the tool ranks the most connected files in the import graph, using a specific verb and resource. It distinguishes from sibling import tools like imports_cycles and imports_deps by focusing on connectivity ranking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like imports_deps or imports_impact. The description does not provide context for when this tool is appropriate or when to choose another.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds 'Snapshot-strict', indicating a point-in-time snapshot, but does not disclose further behavioral traits like response size or error conditions. With annotations present, the description adds some value but remains limited.
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 description is a single, dense sentence that conveys a lot of information without verbosity. However, it lacks front-loading of key purpose (e.g., 'Returns preflight data') and could be restructured for faster scanning.
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?
Given the presence of an output schema (not shown), the description successfully lists the major components returned. It does not mention error handling or optional items, but for a snapshot tool, the completeness is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameters are described in the description. The schema itself has 4 parameters with basic constraints (minLength), but the description adds no meaning beyond what the schema provides. For a tool with multiple parameters, this is insufficient compensation.
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 uses specific verbs ('Return') and identifies a clear resource ('full preflight surface for a table') with a detailed list of components (columns, primary key, indexes, etc.), distinguishing it from sibling tools like 'db_table_schema' or 'table_neighborhood'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. It only describes what the tool returns without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and openWorldHint=true, and the description adds that the tool persists ProjectFinding rows, records run statuses, and operates only on specified files. This provides useful behavioral context beyond annotations, though details about side effects (e.g., overwriting previous findings) are missing.
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 a single, well-structured sentence that front-loads the main purpose and adds crucial constraints. Every clause serves a purpose, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters with no schema descriptions and an output schema (not shown), the description covers core behavior but lacks parameter guidance. For a tool with side-effects and multiple sibling diagnostics, more parameter context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description only mentions 'project-relative files' and does not explain parameters like projectId, projectRef, scriptName, or maxFindings. The description adds minimal meaning beyond the schema's names and types.
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?
Description clearly states it is an ESLint diagnostics ingestion tool that runs local ESLint on specific files, persists findings, and records run status. It distinguishes from broad-project lint tools by stating 'File-mode only; does not run broad project lint.' However, it does not explicitly differentiate from sibling diagnostic tools like biome_diagnostics or oxlint_diagnostics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for specific project-relative files and notes it does not run broad project lint, giving context for when to use. However, it does not explicitly mention when not to use this tool or suggest alternatives, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds value by explaining it computes a file subject fingerprint and returns facts across overlays, providing behavioral context beyond the annotations. No contradictions.
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, front-loaded with purpose, no wasted words. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. However, with 8 parameters and no parameter descriptions in either schema or description, the tool is incomplete for proper use. The description covers purpose and behavior but omits essential parameter guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no parameter details despite having 8 parameters with 0% schema description coverage. It mentions 'overlays' but does not explain the overlay parameter or any other required/optional parameters, forcing reliance on 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 it is a read tool for one file's durable facts, computes a file subject fingerprint, and returns specific facts like working_tree_overlay file_snapshot rows. It is specific about verb and resource, but does not differentiate from sibling tools like file_findings or file_health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Use this to inspect what Reef currently knows about a file across overlays,' providing clear context for usage. However, it does not discuss when not to use this tool or mention alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, covering safety. The description adds context about output format (ordered steps, transitions, boundary crossings) but does not disclose additional behavioral traits like auth needs or rate limits.
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 a single concise sentence that conveys the core purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, nested objects, output schema exists) and 0% schema coverage, the description is insufficient. It does not explain required parameters, how to construct input objects, or interpret results, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the tool description does not describe any parameters. The schema provides names and enums, but the description fails to add meaning or clarify usage of the 8 parameters, leaving the agent without guidance on how to specify start/target entities, direction, depth, etc.
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 clearly states the tool's purpose: converting a graph path into ordered flow steps, transitions, and boundary crossings. It distinguishes from siblings like graph_path and graph_neighbors by specifying the transformation into a structured flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for 'end-to-end flow questions' but does not explicitly state when to use this tool over alternatives or provide exclusion criteria. No explicit guidance on prerequisites or usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent. The description adds that it runs a 'short sequential tool chain' and returns 'typed step history', providing behavioral context beyond 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 a single, well-structured sentence that front-loads the core purpose and key constraints without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having many parameters and an output schema, the description only covers high-level behavior. It fails to explain key parameters like projectId, projectRef, startEntity, targetEntity, direction, etc., and does not describe the return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about the 9 parameters. The parameter names and types are left entirely to the schema, with no guidance on how to use them.
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 clearly defines the tool as a read-only investigation workflow that runs a sequential tool chain and returns typed step history, distinguishing it from many sibling tools that are more targeted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for bounded read-only investigation but does not explicitly state when to use this tool versus alternatives like cross_search or graph_path. The term 'investigation' is broad.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds value beyond annotations: lists return contents (bounded summaries, matchCount, truncation signal, optional markdown) and clarifies it does not run answer loop. Annotations already declare readOnlyHint=true and idempotentHint=true.
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?
Single front-loaded sentence with key action and filters, then two concise sentences on return and behavior. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters with 0% schema description coverage, description covers main filtering dimensions but omits project identifiers and limit. Output description is present but could be more detailed. Adequate for a tool with annotations but leaves gaps.
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 0%, so description must compensate. It mentions filtering by text, query kind, support level, trust state, and ISO time window, but does not explain projectId, projectRef, limit, or output schema. Parameter names are somewhat self-explanatory, but description could be more complete.
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?
Description clearly states it searches prior answer traces by multiple filters. Specific verb+resource. Does not explicitly distinguish from sibling 'recall_tool_runs' but purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. Only states it does not run answer loop or infer freshness, which implies a read-only use case but lacks direct context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by listing the combined data sources but does not disclose additional behavioral traits such as performance implications or authentication requirements beyond the annotations.
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 description is a single sentence that front-loads the key idea ('Neighborhood composer for one route') and lists components concisely. However, it could benefit from slight restructuring for easier parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so the lack of return value description is acceptable. However, the description does not cover how parameters affect the output, error conditions, or what happens when data is missing. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description does not explain any of the parameters (projectId, projectRef, route, maxPerSection). The agent must rely solely on parameter names, which is insufficient for correct invocation.
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 clearly states the tool's purpose as a 'neighborhood composer for one route' and lists the specific components it combines (route_trace, file_health, imports_deps, etc.), making it distinct from sibling tools like route_trace or imports_deps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a comprehensive overview of a route's context is needed, but it does not provide explicit guidance on when to use this tool versus alternatives like rpc_neighborhood or route_trace, nor does it mention exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint. The description adds value by stating that identical inputs produce the same artifactId for deduplication, reinforcing deterministic behavior. No contradictions with 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?
Two sentences with no fluff. The first defines purpose, the second adds important dedup info. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the output concept is explained, the description fails to cover the input parameters (12 params, 4 required) and usage context. The presence of an output schema does not compensate for the lack of parameter semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention any parameters. With 12 parameters including nested objects, the agent receives no guidance on parameter meaning, which is a critical gap.
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 clearly states the tool composes an implementation brief, verification plan, change plan, and flow map into one typed preflight artifact for start-of-work preparation. It distinguishes itself from siblings like file_preflight or flow_map by specifying the combination of multiple documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for start-of-work preparation but does not provide explicit when-to-use or when-not-to-use guidance. No alternatives or exclusions are mentioned, leaving the agent to infer context from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent. Description adds 'Snapshot-strict' and reveals internal mechanisms (getSchemaTableSnapshot, listFunctionTableRefs, FTS, ast-grep), giving insight into its behavior beyond annotations.
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 description is concise (3 sentences) and front-loaded with the purpose. However, the first sentence is a dense list of components, which slightly reduces clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity and presence of output schema, the description covers scope and internal methods but lacks prerequisites, error conditions, or output format details. Adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters. It does not mention projectId, projectRef, or schema, leaving their purpose unclear. Only 'table' is implied by the context.
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 uses the verb 'Trace' on resource 'table' and lists specific components (columns, indexes, foreign keys, RLS, triggers, RPC edges, app-code call sites). It clearly distinguishes from sibling tools like trace_edge, trace_rpc, etc., by focusing on a single table end-to-end.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does comprehensively but lacks explicit guidance on when to use it over siblings like 'table_neighborhood' or 'trace_edge'. No conditions or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so no contradiction. The description adds the 'conservatively fall back' behavior, which provides some transparency beyond annotations, but overall adds limited 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 a single, concise sentence that immediately conveys the tool's purpose. It is well front-loaded with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a router tool and the presence of many sibling tools, the description is minimal. It does not explain what 'canonical named tool' means or provide enough context for an agent to use it effectively, though an output schema may exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the parameters (question, projectId, projectRef). It adds no meaning beyond the schema, failing to compensate for the lack of parameter descriptions.
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 clearly states it is a router tool that maps a natural-language engineering question to a canonical named tool or falls back to free_form. It distinguishes from sibling tools that are not routers.
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 implies when to use (when you have a question that might map to a tool) and mentions the conservative fallback to free_form. However, it does not explicitly state when not to use it or list alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral details about what data is surfaced (platform, version, schemas, transaction state), going beyond the annotation hints.
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 a single concise sentence that efficiently conveys the tool's purpose and scope without extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with annotations and the presence of an output schema, covers the core behavior. However, the lack of parameter explanation leaves a notable gap in completeness for a tool with two required-looking parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for its two parameters (projectId, projectRef). The description offers no explanation of what these parameters represent or how they affect the call, leaving the agent without necessary context to provide correct values.
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?
Description clearly states it is a read-only database tool for verifying connectivity and surfacing platform, version, schemas, and transaction state. This is a specific verb-resource pair that distinguishes it from sibling tools like db_columns or db_table_schema which have more specific functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for initial connectivity checks and metadata retrieval, but does not explicitly state when to use it versus other database-related sibling tools, nor does it provide exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, idempotentHint=false, and the description adds valuable context: 'append-only', writes to 'Mako's local project store', and 'never mutates the live database'. This is clear and helpful, though it could mention whether it can delete or modify existing comments.
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 description is a single, well-structured sentence that front-loads the purpose. It is concise, but could be expanded to cover key parameters without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (13 parameters, 3 enums, 0% schema description coverage) and presence of an output schema, the description covers behavioral transparency well but fails to document parameter semantics, leaving significant gaps for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/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 explain parameters. It only mentions database object types but does not explain any of the 13 parameters (e.g., projectId, preview, category, severity, tags). The agent must infer meaning from parameter names and enums, which is insufficient.
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 clearly states it is an 'append-only DB review note tool' for leaving comments on database objects, and explicitly lists supported object types. It distinguishes from siblings by emphasizing it writes only to local store, unlike potential sibling tools that might read or mutate the live database.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for leaving comments on database objects and highlights it never mutates the live database, but it does not explicitly contrast with sibling tools like db_review_comments (for reading). No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds value by mentioning 'surfacing' (retrieval) and 'suggested cross-check actions' (actionable output), beyond what annotations provide. No contradiction.
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 description is a single concise sentence that front-loads the key concept. However, the jargon 'Reef 10 conflict view' may reduce accessibility. Still, it is efficient with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters with no descriptions and an output schema, the description fails to explain parameter roles or output structure. It lacks sufficient detail for an AI agent to use the tool correctly without extra inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/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 but does not mention any parameters by name or purpose. The meaning of projectId, projectRef, filePath, etc. is left entirely to the schema names and constraints.
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 clearly states the tool surfaces stale evidence, conflict facts, and contradictory findings, with cross-check actions. It uses specific verbs and resources, and distinguishes from similar siblings like evidence_confidence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for viewing conflicts but does not explicitly state when to use this tool vs alternatives, nor does it provide exclusionary conditions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. The description adds that it finds one shortest path and that heuristic edges are explicit and opt-in, which provides behavioral context beyond the annotations.
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 description is a single front-loaded sentence that efficiently communicates core purpose. However, it could be more specific about 'connection questions'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 params, nested objects, enums, output schema), the description omits crucial details such as entity kinds, direction semantics, and traversal depth, making it incomplete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not clarify any of the 9 parameters. The only hint is about includeHeuristicEdges via 'opt-in', but no details on startEntity, targetEntity, direction, etc.
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 clearly states it finds one shortest typed path between two entities, specifying typed edges and opt-in heuristic edges. This distinguishes it from sibling tools like graph_neighbors or auth_path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for connection questions' implies usage context but does not explicitly state when to use this tool vs alternatives like graph_neighbors or auth_path. No exclusions or conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, covering safety. The description adds no new behavioral traits beyond the purpose. It is consistent with annotations, no contradiction.
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?
A single sentence that is front-loaded with purpose. No wasted words, though it could be clearer about the scope. Efficient but minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 undocumented parameters and an output schema present but not described, the description leaves significant gaps. The agent cannot infer parameter roles or return format, making the tool hard to invoke correctly without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 6 parameters. While parameter names like projectId and limit are somewhat self-explanatory, the agent lacks guidance on required fields or effects, hurting usability.
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 clearly states the tool lists unresolved findings, stale facts, and failed diagnostic runs, specifying the resource and verb. It distinguishes itself from siblings by focusing on open loops for attention without rerunning broad checks.
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 implies when to use: to get pending items without rerunning diagnostics. It provides context but does not explicitly mention alternatives or when not to use, though the purpose is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint. The description adds value by detailing the report's contents and reinforcing the non-editing behavior, but does not cover error conditions or additional behavioral traits beyond what annotations provide.
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 description is a single sentence with a clear list of report items, front-loading the purpose. It effectively summarizes the tool's output without excess, though it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and annotations, the description lacks guidance on parameter usage. With 5 parameters and 0% schema description coverage, the agent cannot determine how to correctly invoke the tool (e.g., what parameters are typical, which are optional).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about the 5 parameters (projectId, projectRef, focusFiles, freshnessPolicy, limit). The description does not compensate for the lack of schema descriptions, leaving parameter semantics entirely to the schema field names.
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?
Description clearly defines the tool as a status summary for the reef agent-loop, listing specific report items like maintained known issues, changed files, stale diagnostics, etc. It explicitly states it never edits files, distinguishing it from mutation tools. The verb 'report' and resource 'status' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for getting an overview of agent health, but does not specify when to use this tool versus alternatives like 'reef_known_issues' or 'reef_inspect'. No explicit when-not or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description reinforces this by stating it reads existing state and does not refresh or mutate, adding clarity about what it does not do. This goes beyond annotations by specifying the exact data sources (working_tree_overlay facts, import graph state).
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 two sentences long, front-loading the core purpose and then adding behavioral notes. Every sentence adds unique value without unnecessary detail, making it highly concise and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the high-level purpose and behavioral traits, it lacks details about the input parameters and the exact format of the return value (though an output schema exists). For a tool with 8 parameters, this is a significant gap, making it only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 8 parameters with 0% description coverage, and the tool description does not explain any parameter meanings. For a complex tool with many parameters, the description should provide context for parameters like projectId, depth, or freshnessPolicy, but it does not.
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 clearly states the tool's purpose: to return affected import callers, findings, and conventions for changed working-tree files. It uses specific verbs ('return') and resources ('import callers', 'caller findings', 'conventions'), and differentiates itself from sibling tools like imports_impact and cross_search by focusing on mid-edit impact analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for changed working-tree files during mid-edit, but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. No alternative tools are mentioned, though the context suggests it is for impact analysis without mutation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds scope (full table shape) but no additional behavioral traits beyond what annotations provide, so it meets the baseline.
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 a single sentence that front-loads the key concept ('Read-only database tool') and lists details efficiently without extraneous wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite an output schema existing, the description lacks parameter guidance and usage context for a tool with four parameters (one required) and no parameter descriptions. It is incomplete relative to the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain any parameter meanings. Parameter names (projectId, projectRef) are not self-explanatory, and the description fails to compensate for the lack of schema descriptions.
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 clearly states 'Read-only database tool for full table shape' and lists specific aspects (columns, indexes, constraints, foreign keys, RLS, triggers), which distinguishes it from more focused sibling tools like db_columns or db_rls.
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 implies a comprehensive schema inspection tool, but does not explicitly state when to use versus alternatives like db_columns or db_rls. Context from sibling names provides some guidance, but no explicit when-not-to-use statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a mutating operation (readOnlyHint=false, idempotentHint=false). The description confirms this: 'this is a mutation tool because it refreshes Reef state.' It also adds context about file-mode skipping and persistence, which goes beyond the annotations. No contradiction.
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 description is two sentences, concise, and front-loaded with the action. It wastes no words but could be slightly more structured (e.g., separating conditions). Still effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, nested objects) and presence of an output schema, the description covers the core purpose and a key condition (file-mode skipping). However, it lacks details about output format or parameter usage, making it adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 9 parameters, the description provides no explanation for parameters like projectId, maxFindings, or tsconfigPath. It only references 'sources' and 'files' briefly. This is insufficient for an agent to understand parameter roles.
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 clearly states the tool's purpose: it invokes selected diagnostic sources and persists findings, returning a summary. It lists the exact sources (lint_files, programmatic_findings, etc.) and distinguishes itself from individual diagnostic tools by being an aggregation runner. This is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly says when to use this tool (for refreshing multiple diagnostic sources) but does not explicitly guide when not to use it or suggest alternatives like single-source tools. The note about file-mode sources is useful but incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral context by detailing the traversal behavior with direction, depth, and edge filters. It does not contradict annotations and provides sufficient insight for a safe read operation.
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 description is a single concise sentence that front-loads the purpose. No unnecessary words, but it could be slightly more structured by listing key parameters or usage notes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, output schema exists), the description provides a high-level understanding but lacks detail on parameter usage and interpretation. An output schema covers return values, but the description could be more complete regarding parameter semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/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. It only hints at 'direction, depth, and edge filters' but does not describe all 9 parameters, such as startEntities, nodeKinds, limit, etc. The added value is minimal.
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 clearly states the tool's purpose: 'Graph tool for adjacency questions: traverse outward from one or more start entities with explicit direction, depth, and edge filters.' It specifies the verb 'traverse' and the resource 'graph neighbors', and distinguishes from sibling tools like graph_path by focusing on neighbor exploration rather than path finding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for adjacency exploration but does not explicitly state when to use this tool versus alternatives like graph_path or other graph tools. No exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. Description adds contextual detail about aggregating descriptors and history, but does not disclose additional behavioral traits like auth requirements or data freshness.
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?
Single sentence that efficiently conveys purpose and usage context with no redundancy. Every word adds value despite some internal jargon ('Reef 9').
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and 4 parameters with no descriptions in schema or description, the tool lacks essential information about parameter semantics. The description does not explain how to invoke the tool (e.g., which parameters are needed). This is a significant gap for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description offers no information about any of the 4 parameters (projectId, projectRef, sourceNamespace, limit). Description fails to compensate for missing schema descriptions, leaving agents without guidance on how to use parameters.
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?
Description clearly states the tool aggregates rule descriptors and finding history to show rule states (active, acknowledged, resolved, suppressed). It distinguishes from siblings like list_reef_rules by focusing on memory/state before changes.
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?
Explicitly says 'before making changes' providing clear usage context. However, it does not mention when not to use or suggest alternative tools, slightly limiting guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and openWorldHint. The description reinforces these by calling itself 'Read-only' and adds specific behavioral traits: it validates without running diagnostics or writing state, and returns counts and schema errors. Although consistent, the annotation coverage is high, so the description adds moderate extra value.
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 a single, well-structured sentence that front-loads key information ('Read-only') and efficiently conveys the tool's purpose, scope, and limitations with no extraneous words. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the output schema exists and the description mentions what is returned (counts, errors, optional descriptors), it completely omits parameter guidance. For a tool with three parameters and no parameter descriptions, this makes the description insufficient for correct invocation, reducing contextual completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has three parameters (projectId, projectRef, includeDescriptors) with 0% description coverage in the schema. The description does not explain the purpose or usage of any parameter, leaving the agent to guess how to fill them. This is a critical gap that severely impacts usability.
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 clearly identifies it as a read-only validation tool for rule packs, specifying the file types (.mako/rules), the scope (cross-file declarations), and the outputs (pack/rule counts, schema errors, optional descriptors). It effectively distinguishes itself from siblings by explicitly stating it does not run diagnostics or write Reef state.
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 implies usage during rule-pack authoring and clearly states what the tool does and does not do (no diagnostics, no writing). However, it does not explicitly mention alternatives or when to choose this over other rule-related tools, so guidance on tool selection is indirect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent hints. The description adds valuable behavioral context beyond annotations: 'FTS narrows the ast-grep pass' and 'Snapshot-strict' indicate query optimization and consistency guarantees.
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 description is concise, consisting of two sentences with no wasted words. However, it lacks structure for parameter explanations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core functionality and behavioral traits, but misses parameter semantics and usage guidelines. Given an output schema exists, return values are not needed, but the description could be more complete regarding input parameters and comparative usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage. The description mentions only the 'term' parameter implicitly ('error term'), but does not explain the optional projectId and projectRef parameters, leaving their semantics unclear.
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 specifies exactly what the tool does: trace an error term across throw sites (with ast-grep patterns), catch handlers, and PL/pgSQL bodies. It clearly distinguishes from sibling trace tools (e.g., trace_edge, trace_file) by focusing on error-specific constructs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for error term tracing but provides no explicit guidance on when to use this tool versus other trace tools (e.g., trace_edge for control flow). No 'when-not' or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds specific details about the trace content (symbols, imports, dependents, routes, evidence), providing useful behavioral context beyond annotations.
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 description is a single sentence that front-loads the main purpose and lists key capabilities. It is concise but lacks parameter documentation, which would improve structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values are covered. However, with three parameters and no schema descriptions, the description should explain projectId and projectRef to be complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has three parameters (projectId, projectRef, file) with 0% schema description coverage. The description does not explain any parameters, leaving agents to infer their meaning from names alone.
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 clearly states the tool traces a file end-to-end, listing specific aspects like declared symbols, imports, dependents, and routes. This differentiates it from sibling tools like exports_of, imports_deps, or trace_edge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. While the list of traced elements helps infer usage, no guidance on exclusions or prerequisites is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds important context beyond annotations: 'Snapshot-strict' indicating consistency, and internal steps (searchSchemaObjects, etc.). No contradiction with readOnlyHint=true and idempotentHint=true.
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?
Well-structured with a front-loaded purpose and colon-separated details. Slightly dense but efficient; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main outputs but lacks detail on output schema (though it exists) and parameter relationships. Does not explain how argTypes disambiguates overloads or when schema is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain the purpose of individual parameters (projectId, projectRef, schema, argTypes). Only mentions the function name placeholder, leaving agent to guess parameter roles.
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?
Clearly defines 'Trace an RPC end-to-end' with specific sub-components (definition, bodies, table refs, app-code). Distinguishes from sibling tracing tools like trace_table or trace_edge by focusing on RPC-specific aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for tracing an RPC but provides no explicit when-to-use or when-not-to-use guidance. Does not compare with sibling tools like rpc_neighborhood or trace_error.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint: true. Description adds valuable behavior: 'Snapshot captures the bytes for undo', indicating the deletion is potentially reversible. No contradictions.
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 short, front-loaded sentences with no wasted words. Essential information is presented efficiently.
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 simple 1-param destructive tool with an output schema, the description covers the primary action and undo behavior. Missing info on error handling (e.g., file not found) but acceptable for this complexity.
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 coverage is 100% and already documents 'path' with its description. The tool description adds no additional semantic meaning beyond the schema, so baseline score applies.
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?
Description clearly states the verb 'Delete' and the resource 'file at a project-relative path'. It is specific and distinct from sibling tools like create_file or file_write.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., file_edit or other deletion methods). No when-not-to-use or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds value by noting that it returns a snapshot id for undo, providing behavioral context beyond the 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?
Two concise sentences front-load the purpose and outcome. No redundant information.
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?
Given the presence of an output schema and annotations, the description covers the key behavior and return value (snapshot id). It could mention error handling or directory creation, but overall adequate for a write tool.
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 baseline is 3. The description repeats 'project-relative path' already in schema and does not add semantic meaning beyond what the schema provides.
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 explicitly states 'Create or overwrite a file at a project-relative path', using a specific verb and resource. It distinguishes itself from sibling tools like 'create_file' and 'file_edit' by specifying overwrite behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool over alternatives. No comparison to sibling tools or conditions for exclusion is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it is not read-only and not idempotent. The description adds that it persists findings to Reef (unless disabled), never edits the index or worktree, and uses discovered auth guards and allowlists. This goes beyond annotations by detailing side effects and constraints.
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 description is front-loaded with the main purpose and actions in the first sentence. It is detailed but not overly verbose; each sentence adds value. A slight reduction in length could improve conciseness, but it remains efficient.
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?
Given the tool's complexity and the presence of an output schema, the description covers inputs, actions, side effects, and constraints reasonably well. It does not detail output format (likely covered by output schema) or required permissions, but overall it is adequate for understanding the tool's role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/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. It mentions using 'discovered project-profile auth guards/server-only modules' and 'optional allowlists', which maps to some parameters (authGuardSymbols, serverOnlyModules, possibly publicRouteGlobs), but the core parameters projectId, projectRef, and includeExtensions are not explained. Only partial value added.
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 clearly states it is a pre-commit guard for staged TS/TSX files that checks auth guards and boundary mistakes, persists findings, and returns hook-friendly output. It uses specific verbs and resources, distinguishes itself from sibling tools by focusing on git pre-commit checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it is for use in git pre-commit hooks but does not explicitly state when to use it versus alternatives or when not to use it. No cross-references to sibling tools or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe, idempotent operation. The description adds a critical behavioral detail: it avoids fabricating trend lines when history is thin, which is not captured by annotations. This enhances transparency beyond what annotations provide.
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 a single, well-structured sentence that efficiently conveys the tool's purpose, action, and a key constraint. Every word adds value, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (which may clarify return values), the description omits details about trace window definition, parameter usage, and how the tool fits among many similar sibling tools. For a tool with three optional parameters, this leaves gaps that could confuse an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description does not explain any of the three parameters (projectId, projectRef, limit). The schema documents their types but the description adds no semantic context, leaving the agent to infer their roles from names alone.
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 clearly states the tool's purpose: comparing recent and prior trace windows for trend review. The specific phrase 'without fabricating trend lines when history is thin' distinguishes it from other trace-related tools and provides a unique behavioral nuance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for trend comparisons when sufficient history exists, but does not explicitly mention when not to use or suggest alternatives among the many sibling tools. No exclusion criteria or comparative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds context about output: it lists imports and flags unresolved internal edges, which the annotations do not provide. No contradictions.
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 a single sentence that immediately states the tool's purpose. It contains no redundant information and is efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values need not be detailed. However, the description does not explain prerequisites (e.g., project indexing), the meaning of 'unresolved internal edges', or how projectId/projectRef affect behavior. It covers basic purpose but lacks operational context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/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. It explains the 'file' parameter by mentioning 'a file's indexed imports', but projectId and projectRef are not described at all. Their optionality and effect remain unclear, leaving significant gaps.
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 clearly states the tool lists a file's indexed imports and flags unresolved internal edges, using specific verbs ('list' and 'flag') and a specific resource (file's direct dependencies). It distinguishes from sibling tools like imports_cycles, imports_hotspots, and imports_impact by focusing on direct dependencies and internal edges.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for analyzing direct dependencies and internal edges within a project, but it does not explicitly state when to use this tool versus alternatives (e.g., imports_cycles for cycles). No exclusions or when-not guidance are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint both true. The description adds value by explaining that the result contains descriptors which explain facts consumption and rule IDs, and mentions filtering parameters. No contradictions.
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?
Two sentences front-load the purpose and add detail about descriptor content. Efficient, but could optionally mention the other parameters briefly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, reducing need to describe return format. But with 5 parameters and 0% schema coverage, the description should explain all parameters or at least projectId/projectRef. Missing usage guidance. Adequate but with gaps.
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 0%, so the description must compensate. It mentions filtering by sourceNamespace and enabledOnly, but does not explain projectId, projectRef, or limit. Partial coverage of parameters; leaves some meaning unclear.
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?
Clearly states it is a read tool for rule metadata, listing durable rule descriptors, with optional filtering by source namespace or enabled-by-default status. This distinguishes it from sibling tools (e.g., reef_agent_status, reef_inspect).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing rule descriptors with filtering, but does not explicitly state when to use this tool versus alternatives like reef_inspect or reef_scout. No exclusion or comparison to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is read-only (consistent with annotation), returns grade counts and bounded recent entries, and is filterable, adding useful behavioral context beyond the 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?
Two sentences efficiently convey the tool's purpose and usage, with no wasted words and a clear, front-loaded structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema exists but the description omits many parameters and does not mention pagination or sorting, leaving significant gaps for a tool with 7 parameters and 0% schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description only mentions 'referencedToolName, grade, and ISO time window', missing many parameters like projectId, projectRef, and limit, leaving meaning unclear.
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 clearly states the tool returns grade counts and recent entries for agent feedback, with specific mention of filtering by tool name, grade, and time window, distinguishing it from the sibling 'agent_feedback' 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?
The description explicitly suggests using the tool to review which tools agents found helpful, noisy, wrong, or incomplete, providing clear use context but lacking explicit exclusion or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are present (readOnlyHint=false, idempotentHint=false, openWorldHint=true) and the description adds behavioral context: it runs external executables, persists ProjectFinding rows, and records run status (unavailable/error/succeeded). This goes beyond annotations without contradiction.
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 description is reasonably concise and starts with a clear purpose statement. It packs several details (executable, reporter, persistence, status tracking) without excessive verbosity. Minor improvement could be breaking parameter-related content into a clearer structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, 0% schema description coverage, and existence of an output schema (not shown), the description covers the main workflow but lacks detail on parameter specifics and the output format. It is adequate but not comprehensive for a tool with side effects and multiple inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description only implicitly relates parameters: 'files' are mentioned as 'project-relative files', 'scriptName' is hinted but not explicitly explained. Parameters like 'projectId', 'projectRef', and 'maxFindings' are not described at all. The description fails to add sufficient semantic meaning for the majority of parameters.
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 clearly states the action ('run', 'persist', 'record'), the resource ('Biome diagnostics', 'files'), and the specific behavior (uses `check --reporter=gitlab`, persists ProjectFinding rows under source 'biome'). It distinguishes from siblings like eslint_diagnostics by specifying 'Biome' and 'GitLab-reporter package script'.
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 guidance by stating 'File-mode only' and 'deliberately avoids Biome's experimental JSON reporter', implying it is for deterministic file-by-file checking. However, it does not explicitly mention when to use this tool over sibling diagnostic tools (e.g., eslint_diagnostics) or provide conditions for avoidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint. The description adds value by stating the tool is read-only, does not refresh the index, uses deterministic providers, exposes retrieval diagnostics, and mentions a rollback path. No contradictions with annotations.
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 description front-loads the core purpose and adds necessary technical details. Sentences are dense but each adds value. Could be slightly more concise, but overall efficient for a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a thorough explanation of the tool's role, behavior, and outputs (retrieval diagnostics, enrichments). However, it lacks detail on most input parameters and does not leverage the existing output schema to reduce the burden. Adequate for high-level understanding but incomplete for precise invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description only mentions one parameter (risksMinConfidence) explicitly. With 17 parameters, the description fails to compensate for the lack of schema-level parameter documentation, leaving most inputs unexplained.
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 clearly defines the tool as a first-mile context scout for coding agents, using deterministic providers to produce ranked, source-labeled context. It distinguishes itself from siblings by stating its role before normal harness loops, making the purpose highly specific and unambiguous.
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?
Explicitly says 'Use as the first-mile packet before normal harness read/search/edit loops', providing clear usage context. However, it does not specify when to avoid this tool or mention alternative tools for different scenarios, leaving some gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint; the description reinforces read-only nature and adds context about inspecting RLS state via pg_catalog, without contradiction.
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?
A single, concise sentence front-loads the key purpose with no superfluous words.
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?
With an output schema present and a focused inspection task, the description covers the main purpose. However, lack of parameter detail slightly reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description only mentions 'table', leaving projectId, projectRef, and schema unexplained. This is insufficient given the low baseline coverage.
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 clearly states the tool is for inspecting row-level security state and policies via pg_catalog, using specific verb 'inspect' and resource 'security questions'. It distinguishes itself from sibling database tools like db_columns and db_fk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for security questions but does not provide explicit guidance on when not to use or alternatives among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description states read-only, matching annotations, and adds that it returns signatures, return shape, language, and security, which goes beyond annotation hints. It also describes two modes of operation.
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?
Single sentence is concise and front-loaded with the core purpose. No waste, though could benefit from clearer separation of modes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main usage modes and mentions return shape, language, security, but lacks explanation of many parameters. Output schema exists but not detailed. Adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 'name' and 'list' are explained in the description, leaving 7 other parameters (e.g., limit, schema, argTypes) completely undocumented. With 0% schema description coverage, this is insufficient.
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?
Description explicitly states the tool inspects stored procedure/function signatures or enumerates routines, with specific verb 'inspect' and 'enumerate'. This clearly distinguishes it from siblings like rpc_neighborhood and trace_rpc.
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?
Clearly implies usage for function questions (inspecting signatures or listing routines), but does not explicitly exclude other cases or mention alternatives. Context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds important behavioral context: it is read-only, does not persist findings, uses direct_evidence/weak_signal honesty strength, and always returns a full 10-category coverage section. No contradictions.
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 description is a single dense paragraph that front-loads the main purpose and then details. Every sentence adds value, though it could be slightly more concise. Well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 8 parameters and an output schema, the description adequately covers purpose, scope, and advisory nature. However, missing parameter explanations for 6 of 8 parameters leave gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/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 explain parameters. It only covers categories and acknowledgeAdvisory. It does not explain freshen, maxFiles, projectId, projectRef, maxPerSection, or includeFullResults. This is a significant gap.
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 clearly states it is for OWASP Top 10 (2025) review of TS/JS files, listing specific categories and explicitly naming those it does not check. This distinguishes it from sibling tools like tenant_leak_audit.
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 explicit usage guidance: it is advisory/heuristic, requires acknowledgeAdvisory:true, and is not a replacement for dedicated SAST/SCA. It does not mention alternative tools but gives clear when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as readOnlyHint=true and idempotentHint=true, so the description adds little behavioral context. It mentions 'cache freshness/age' which hints at caching behavior, but overall, the description does not go beyond what annotations provide.
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 two sentences: the first states functionality, the second provides usage guidance. Every word is essential, no redundancy. It is well-structured and front-loaded.
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?
Given the tool's complexity, annotations (readOnlyHint, idempotentHint), and presence of an output schema (implied by 'including...'), the description covers most aspects. The missing parameter explanations lower the score, but the overall context is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/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. It mentions filtering by 'source' and 'status' implicitly ('by source and status'), but does not explain projectId, projectRef, limit, or cacheStalenessMs. With 6 parameters, this is insufficient for an agent to understand all inputs.
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 clearly states it lists recent diagnostic runs with specific fields like state, duration, counts, command, etc. It includes a specific scope ('diagnostic source runs') and the verb 'list' makes the action unambiguous. Among siblings like biome_diagnostics or eslint_diagnostics, this tool is unique in focusing on run history, not current diagnostics.
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 a clear use case: 'Use this to distinguish no findings from a diagnostic source that did not run or ran too long ago.' This helps the agent decide when to use it. However, it does not explicitly mention when not to use it or suggest alternative tools (e.g., diagnostic_refresh for triggering a run).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint. The description adds behavioral context by characterizing the tool as a 'reef read tool' and the facts as 'durable' and the 'calculated substrate behind findings.' No contradiction with 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?
Two sentences, front-loaded with purpose, no redundant words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite an output schema existing, the input schema lacks descriptions and the description covers only half the parameters. Important context about project identification, freshness, and limits is missing. The description is insufficient for an 8-parameter tool with 0% schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no descriptions). The description lists only 4 out of 8 parameters (overlay, source, kind, subjectFingerprint), providing meaning for those but omitting projectId, projectRef, freshnessPolicy, and limit. This leaves critical parameters undocumented.
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 clearly identifies the tool as a read operation for 'durable project facts' and lists the query dimensions (overlay, source, kind, subject fingerprint). It distinguishes itself from sibling tools by emphasizing that it returns 'calculated substrate behind findings without rerunning analysis.'
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 explicitly states when to use the tool: 'when an agent or shell needs the calculated substrate behind findings without rerunning analysis.' It does not list alternative tools by name, but the context is clear enough to guide selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate mutation and not read-only. The description adds behavioral context beyond annotations: handling of unknown freshness in if_stale mode, counting unindexed files as stale, and returning freshness summaries. No contradiction with annotations.
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?
Three sentences with no wasted words. The first sentence efficiently packs the main purpose, conditions, and output. The second adds mode specifics. Slightly dense but still clear. Could benefit from more structured presentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 optional parameters and an output schema (not shown), the description covers main behavior and modes. However, parameter semantics are missing, limiting completeness. Output schema existence mitigates need to detail return fields, but parameter descriptions are needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the individual parameters (projectId, projectRef, mode, reason). Only 'mode' is implicitly referenced. With zero coverage, the description should compensate but fails to add meaning for 3 of 4 parameters.
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 clearly states it is a mutation tool for index freshness, specifies conditions (stale, unknown, deleted, unindexed), and lists output (before/after summaries, new index run). This distinguishes it from siblings like project_index_status.
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 explains when to use the tool (when snapshot is stale, unknown, deleted, or has unindexed files) and the behavior of 'if_stale' mode. However, it does not explicitly contrast with sibling project_index_status or provide when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description expands on the readOnlyHint, explaining it is read-only and uses internal modules. It details default compact evidence mode, options to get full evidence (evidenceMode, includeTrace), and special question handling. This adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but front-loads the main purpose. It includes necessary details for a complex tool, but some sentences could be trimmed without losing clarity. Adequate but not maximally concise.
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?
Given the tool's complexity and no schema descriptions, the description covers the output format, evidence modes, and question type handling. It does not detail every parameter but provides enough context for effective use, especially with an output schema present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains only a few parameters (evidenceMode, includeTrace) and the general question type. Most of the 22 parameters (e.g., projectId, focusFiles, budgetTokens) are not described, leaving incomplete understanding.
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 clearly states it is the 'Primary Reef query engine facade' and lists its output: a compiled codebase and database evidence packet with specific elements. It distinguishes itself by mentioning internal handling of various question types and its read-only nature, matching the annotation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the main query tool but does not explicitly compare to sibling tools like 'ask', 'reef_verify', or 'reef_where_used'. It lists question types it handles, suggesting when to use it, but lacks explicit when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and idempotent, so the description adds value by explaining the behavioral nuance: 'With files, runs only count when project-wide or scoped to those files.' This clarifies how file filtering affects the result, going beyond the 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?
Two well-structured sentences, front-loaded with purpose, no redundant or extraneous information. Every sentence contributes to understanding.
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 read-only state-view tool with an output schema, the description is fairly complete. It explains the core summary and the file-scoping behavior. However, it lacks guidance on when to use this tool vs siblings like diagnostic_refresh, and does not mention any prerequisites or limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only minimally addresses one parameter ('files') by describing its effect. The other five parameters (projectId, projectRef, sources, limit, cacheStalenessMs) receive no explanation, leaving the agent to infer their semantics from names alone.
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 clearly states it is a 'verification state view' that summarizes coverage of cached diagnostic runs over the working-tree overlay. It lists specific aspects like file-scoped recent runs, watcher diagnostic state, and suggested actions, which distinguishes it from sibling tools that produce artifacts or perform updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like diagnostic_refresh or verification_bundle_artifact. It implies usage for checking coverage but provides no exclusions or comparative guidance, which is a gap given the many siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true and idempotentHint=false. The description adds behavioral context: hunks must apply cleanly with exact context, clarifying the strict matching requirement. No contradiction with 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?
Two succinct sentences with no filler. Every sentence conveys essential information: what it does and a critical constraint. Ideal structure for quick agent comprehension.
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?
With one parameter and an output schema not shown, the description covers the key behavioral constraint (exact context). It could mention that this mutates files (implied by destructiveHint) but is mostly complete. No mention of error behavior, but that may be in the output schema.
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 coverage is 100% with a detailed parameter description for 'diff' specifying format and file headers. The tool description adds no additional semantic value beyond the schema, so a baseline of 3 is appropriate.
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 clearly states the tool applies a multi-file unified diff and specifies the requirement for exact context matching. The name 'apply_patch' is self-explanatory and distinguishes it from siblings like 'file_edit' or 'file_write' which handle single file modifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives (e.g., file_edit for single files, shell_run for custom patches). It implies usage for applying diffs but lacks when-not-to or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint, so the description adds value by disclosing the 'without overclaiming' philosophy and the specific fallback behavior (matched:false with suggestedNext). It does not contradict annotations. Minor gaps: unclear behavior when multiple parameters are provided.
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, front-loaded with purpose, no wasted words. Efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description doesn't need to detail returns, but it does cover the fallback. However, given 5 optional parameters and sibling tools, more context on parameter interactions and when to choose this over other tools would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/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. It mentions only three of five parameters (route, file, feature) with no details on their meaning or constraints. missing semantics for projectId and projectRef.
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 clearly states it is an 'Answer tool for auth questions' that 'trace likely auth boundaries for a route, file, or feature', specifying the verb and resources. It also distinguishes itself from sibling tools like cross_search by describing the fallback behavior of returning matched:false with a suggestedNext for cross_search instead of throwing.
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 tells when to use (for auth questions about a route, file, or feature) and implies when not (if no exact match, use cross_search). It also mentions that the tool's non-throwing behavior is beneficial for batches and agent workflows. However, it does not explicitly exclude other sibling tools like route_trace.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds the method 'via pg_catalog' and the scope of inspection, enhancing transparency beyond the 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 a single concise sentence that front-loads the key information ('Read-only database tool for relationship questions'), with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the purpose is clear and annotations cover behavioral aspects, the description omits explanations for projectId and projectRef parameters, which are needed for complete context in a tool with multiple siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description does not explain any of the four parameters (projectId, projectRef, table, schema). It only implies the 'table' parameter by mentioning 'for a table', leaving others undocumented.
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 uses a specific verb 'inspect' and clearly identifies the resource as 'inbound and outbound foreign-key references for a table', distinguishing it from sibling tools like db_columns or db_table_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?
It states the tool is for 'relationship questions', providing clear context for when to use it, but does not explicitly mention when not to use it or suggest alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds 'Does not write files or mutate Reef state' and explains the specific mining behavior, providing context beyond 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 a single, well-structured sentence that front-loads the purpose ('Read-only Reef rule-pack mining tool') and packs in key details without redundancy. Every word adds value.
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?
Given the tool's complexity (8 parameters, output schema exists), the description covers core inputs and outputs. However, it lacks context on prerequisites (e.g., project setup) and what 'related durable findings' entails. Almost complete.
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 0%, so the description must compensate. It mentions 'git fix diff' (implying fixCommit, baseCommit, filePath) and 'YAML templates' (relating to output), but does not systematically explain all 8 parameters. Partial compensation but not complete.
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 clearly states the tool's purpose: 'inspect a local git fix diff and propose .mako/rules YAML templates from removed TS/JS anti-pattern shapes'. It uses specific verbs and resources, and distinguishes from siblings like file editors or database tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for rule mining from diffs but does not explicitly state when to use this tool over alternatives like `reef_scout` or `reef_diff_impact`. No guidance on when not to use or how it compares to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by confirming it returns a 'read-only packet' and listing the contents, but does not disclose error behavior or edge cases. No contradiction with annotations.
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 description is concise, using three sentences to convey purpose and usage. It is front-loaded with the core function and avoids redundancy, though could be slightly more compact.
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?
Given the tool's complexity (10 parameters, composite output) and the presence of annotations and an output schema, the description adequately covers the operational context. It omits error handling and prerequisites but is sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 10 parameters with 0% description coverage. The description only mentions the return items and not the parameters like freshnessPolicy, cacheStalenessMs, or limits. The description does not compensate for the missing schema descriptions, providing minimal parameter guidance.
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 clearly identifies the tool as a pre-edit composer for one file, listing the specific data it returns (findings, freshness, runs, etc.) and distinguishing it from sibling tools like file_findings, verification_state, etc., by stating it replaces multiple separate calls.
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 tool explicitly states when to use it ('Use before editing a file when an agent needs the operational gate') and mentions what it replaces, but does not provide explicit when-not-to-use scenarios or prerequisites, slightly reducing clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as a mutation, and the description adds valuable behavioral details: append-only, deduplication at query time, and emission of a RuntimeUsefulnessEvent. No contradictions with annotations.
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 description is front-loaded with the purpose and reasonably concise. It uses technical but accurate language. Slightly verbose in the middle, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 14 parameters and no output schema, the description covers the main operation, duplicate behavior, and event emission. However, it omits explanation of several optional parameters and does not fully describe the return value, leaving some gaps.
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?
With 0% schema description coverage, the description adds meaning for key parameters (category, fingerprint, subjectKind) but leaves many optional parameters (e.g., acknowledgedBy, sourceToolName) unexplained. The core required ones are clarified.
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 clearly states the verb (append), resource (finding_acks ledger), and purpose (filter out matches for subsequent callers). It differentiates from sibling tools like finding_ack_batch and finding_acks_report.
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 context on when to use which fingerprint based on source (ast_find_pattern vs lint_files) and mentions the default category for lint findings. It does not explicitly compare with the batch variant, but the guidance is sufficient for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly details behavioral traits: runs local Oxlint executable or script with JSON format, persists ProjectFinding rows, records run status. This adds significant context beyond the annotations which only indicate non-readonly and open world.
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?
Two sentences convey the core purpose and key constraints, but the description is slightly verbose and could be more streamlined while retaining clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters with no schema descriptions and an output schema, the description lacks information about parameter semantics and return values, making it incomplete for effective tool usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description only adds meaning for the 'files' parameter (project-relative, JSON format). Other parameters like projectId, projectRef, scriptName, and maxFindings are left undocumented.
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 clearly states it is a tool for running Oxlint diagnostics on specific files, persisting findings, and recording status. It distinguishes itself from sibling diagnostic tools by specifying it is file-mode only and not a broad project lint.
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 implies usage context (file-mode, not broad lint) and indicates it is an 'Explicit Reef ingestion tool', but does not explicitly state when to use it over alternatives like eslint_diagnostics or biome_diagnostics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds behavioral context by specifying 'query' and listing return types (callers, findings, conventions). No contradiction with 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?
Two concise, front-loaded sentences that convey the essential purpose and relationship to a sibling tool without any waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides high-level purpose and output types, but with 8 parameters and no parameter details in the description or schema, the agent lacks sufficient context to use the tool correctly. An output schema exists but is not described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no information about any of the 8 parameters. It does not compensate for the lack of schema documentation, leaving agents without guidance on parameter usage.
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?
Description clearly states the verb ('query'), resource ('impact of changed files'), and the outputs ('affected import callers, invalidated findings, and convention risks'). It also distinguishes from sibling tool 'reef_diff_impact' by noting equivalence with a smaller name.
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?
Explicitly mentions equivalent calculation to reef_diff_impact, providing a clear alternative. However, it does not elaborate on when to prefer this tool over other siblings or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only and idempotent; the description reinforces this as a read tool and adds the default overlays, adding value beyond 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?
Two efficient sentences: first explains functionality and defaults, second gives usage advice. Front-loaded and compact, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. The description explains the core diff and usage context, but given the schema's 0% coverage and 10 parameters, more parameter documentation would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 10 parameters and 0% schema description coverage, the description only mentions filePath, kind, source filters. Many important parameters (projectId, projectRef, includeEqual, includeFacts, limit) are not explained, requiring the agent to infer or look elsewhere.
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 clearly states the tool diffs durable facts between overlays, with a default of indexed vs working_tree. This distinguishes it from siblings like reef_diff_impact and reef_inspect.
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?
Explicitly advises using after working_tree_overlay or before edits to see changes without rerunning diagnostics, giving clear context for when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint: true and idempotentHint: true, indicating safe, read-only behavior. The description reinforces this by stating 'not an editing agent' and describes the output as 'intent-weighted, explainable candidates.' It adds context about the nature of the returned data (from durable Reef facts, etc.), which goes beyond the 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 extremely concise: three sentences that front-load the main purpose, provide usage guidance, and set expectations. Every sentence adds unique value without redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description adequately covers purpose, usage, and behavioral context, it lacks parameter-level details for a tool with 6 parameters and 0% schema description coverage. The presence of an output schema partially compensates for return value explanation, but the missing parameter descriptions leave a notable gap. Considering the tool's complexity, the description is not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema provides no descriptions for any of the 6 parameters. The tool description does not compensate: it only generically mentions 'query' and types of queries, but does not explain projectId, projectRef, focusFiles, limit, or includeRawEvidence. Given this gap, the description fails to add sufficient meaning beyond the schema's structural definitions.
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 clearly states the tool's purpose: 'turn a messy request into intent-weighted, explainable candidates from durable Reef facts, findings, rules, and diagnostic runs.' It distinguishes from siblings by emphasizing it's a scout view, not an editing agent, and advises using other tools after obtaining the packet. The verb 'scout' and resource 'Reef model-facing scout view' are specific and unique among siblings.
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 context for when to use the tool: 'App-flow queries prefer files/routes/findings; RLS/schema queries prefer database evidence.' It also states what not to use it for: 'This is a context scout, not an editing agent; use normal harness read/search after the packet.' However, it does not explicitly name alternative sibling tools for specific scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. The description adds behavioral context: it does not run grep, coverage explains limits, and returns fallback tool args. This adds value beyond annotations.
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 description is a single dense sentence that front-loads purpose. It is efficient but could be split for readability. Every part adds value, but it is slightly verbose.
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?
Given the output schema exists, the description need not detail return values. It covers coverage limits, fallback behavior, and the two-stage process. However, it lacks detail on what the answer structure looks like, and parameter semantics are weak.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% so parameters are undocumented in schema. The description only implicitly mentions query and targetKind via 'symbol, component, route, file, or pattern', but provides no explanation of projectId, projectRef, freshnessPolicy, or limit. This is insufficient for correct parameter usage.
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 clearly states the tool answers where a symbol, component, route, file, or pattern is defined and used, with a two-stage process from maintained state then indexed references. It explicitly says it does not run grep, distinguishing it from raw text search tools.
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 implies usage for structural queries and mentions fallback behavior when maintained state has no answer. It explicitly states what it does not do (grep), but does not explicitly name alternative tools like live_text_search or cross_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: args must be a list (safety), cwd is restricted (security), env keys must be allowlisted (security). Annotations already mark destructiveHint=true, so the description reinforces safety concerns but does not elaborate on return values or error handling.
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 extremely concise: two sentences without any fluff. It front-loads the core purpose and immediately covers critical constraints. Every sentence adds value.
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?
Given the tool's complexity (shell execution, security, environment) and rich schema (100% coverage, output schema exists), the description covers key constraints. It does not explain success/failure behavior, but output schema likely handles that. Minor missing: no mention of stdout/stderr capture or process lifecycle.
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?
Input schema has 100% coverage with parameter descriptions. The description mostly reiterates schema details (e.g., args never concatenated, env allowlisted). It adds minor clarification for cwd ('locked to project root or subdirectory'). Baseline score of 3 is appropriate as schema already provides adequate meaning.
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 clearly states the tool's purpose: 'Run a shell command with arguments as a list (never concatenated).' It specifies the action (run), resource (shell command), and key constraints (args list, cwd locked, env allowlisted). It is distinctive from siblings which are mostly non-shell tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides constraints (args as list, cwd locked, env allowlisted) but does not explicitly state when to use this tool versus alternatives. It implies usage for secure command execution but lacks guidance on when not to use or mention of alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint true, so the description adds value by explaining the composition of data from multiple sources, but lacks further behavioral details (e.g., performance, pagination). No contradiction with 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 a single sentence that efficiently conveys the tool's purpose without superfluous information.
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?
Given the existence of an output schema and annotations, the description sufficiently outlines the tool's function. It could mention the role of maxPerSection, but overall it is complete enough for a data composition tool.
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 0%, so the description must compensate. It indirectly explains tableName and schemaName via the data sources, but does not detail projectId, projectRef, or maxPerSection. Some context is provided but not per-parameter clarity.
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?
Description clearly states it is a 'neighborhood composer for one table' that combines multiple data sources (schema, usage, trace edges, routes) into one bundle, distinguishing it from sibling tools like db_table_schema or schema_usage.
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 implies use for comprehensive table analysis by listing the combined data types, but does not explicitly state when to use this tool over individual queries or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. Description adds useful behavioral details like 'snapshot-strict' and lists trace components. No contradiction. Could further explain 'snapshot-strict' for clarity.
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?
Single sentence efficiently conveys all key information: action, resource, what is traced. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core functionality but omits parameter descriptions and does not elaborate on 'snapshot-strict' implications. Output schema exists but description could be more complete regarding input parameters and output interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 3 parameters (projectId, projectRef, name) with 0% description coverage. Description does not mention or explain any parameters. It implies name is the function name but lacks clarity on projectId and projectRef.
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?
Description clearly states it traces a handler/edge function, listing specific items (route, app-code callers via fetch/invoke patterns, tables/RPCs, DB triggers). This distinguishes it from sibling tools like trace_file, trace_rpc, trace_table.
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?
Provides clear context on what the tool does and what it covers (callers via ast-grep patterns, DB triggers). However, it does not explicitly state when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, covering the primary behavioral trait. The description adds no extra context about permissions, backups, or error cases, so it does not go beyond the 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?
Two sentences, front-loaded with the purpose, no wasted words. Efficient and easy to parse.
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 an output schema exists and annotations cover safety, the description fully explains the core behavior and the key constraint (unique occurrence) without needing elaboration on returns or side effects.
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% with clear parameter descriptions. The tool description does not add additional meaning beyond what the schema already provides, meeting the baseline.
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 clearly states the tool replaces a substring in an existing file, with a specific verb and resource. It distinguishes from siblings like create_file, delete_file, or apply_patch, which have different purposes.
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 provides a clear constraint (substring must occur exactly once unless replaceAll is true) but does not explicitly mention when to use this tool over alternatives like file_write or apply_patch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description reinforces this with 'Never writes to the ledger' and adds specifics about the returned data (aggregate counts by various dimensions, bounded reverse-chronological list). This adds value beyond the annotations.
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 description is concise, with no extraneous information. Key points are front-loaded: read-only, what it returns, and filter options. One could argue for a slightly more structured format, but it is efficient.
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?
Given there is an output schema (presumably defining return structure), the description does not need to detail return values. It covers the purpose, filters, and behavior (bounded list, read-only). With 9 optional parameters, the description adequately informs an agent about tool usage.
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 0%, so the description carries the burden. It lists filterable fields (category, subjectKind, filePath, status, ISO time window) but does not provide detailed explanations for each parameter or their default behavior. This partially compensates for the lack of schema descriptions but is not exhaustive.
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 clearly identifies the resource ('finding_acks ledger') and the action ('read-only inspection returning aggregate counts and a bounded list of acks'). It distinguishes from sibling tools that write to the ledger, such as 'finding_ack' and 'finding_ack_batch'.
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 usage context ('to see what operators have suppressed and which categories carry the most weight') and explicitly states the tool does not write. However, it does not explicitly mention when not to use it or suggest alternatives, though it is clear it is for reading only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, and idempotentHint. The description adds that it is 'read-only and explicitly live,' which reinforces but doesn't contradict annotations. No additional behavioral traits like pagination or limits are disclosed, but the description is consistent and adds some 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 concise (3 sentences) and well-structured: first sentence states main action, second clarifies default/option, third gives usage guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters and an output schema, the description does not provide sufficient context for many parameters (e.g., pathGlob, maxFiles). It lacks details on return format or how to use optional parameters effectively. The output schema might help, but the description should cover more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 9 parameters and 0% schema description coverage, the description only highlights 'fixedStrings' and implicitly 'query.' It does not explain other parameters like pathGlob, maxFiles, projectId, etc. The description adds minimal meaning beyond the schema.
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 clearly states the tool's purpose: 'Raw live filesystem text search: run ripgrep over the attached project root and return bounded file/line matches.' It also specifies default behavior (fixed-string matching) and regex option, distinguishing it from sibling tools like reef_ask.
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?
Explicit guidance is provided: 'Prefer reef_ask for bounded quoted literal questions; use this when you need regex, custom glob scope, or raw full match inventories.' This clearly indicates when to use this tool vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares read-only and bounded summaries, consistent with annotations. Adds details on limits and payload condition. No contradiction with annotations.
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?
Two sentences, front-loaded with purpose, includes key usage details. Slightly dense but acceptable.
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?
Covers filtering, limits, payload inclusion, and return structure. Output schema handles return values. Lacks pagination details but adequate for a read-only recall tool.
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 coverage is 0% and description covers 6 of 9 parameters (toolName, outcome, requestId, since, until, limit, includePayload). Misses projectId and projectRef. Partially compensates but not fully.
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?
Clearly states 'inspect prior project tool_runs' with specific filtering criteria. Distinguishes from sibling tools like 'recall_answers' by focusing on tool runs.
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?
Provides default limit, max limit, and payload inclusion detail. Implicitly suggests using requestId for agent_feedback. Does not explicitly contrast with alternatives, but usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only and idempotent behavior. Description adds that the tool returns 'durable facts, findings, and relevant diagnostic runs', providing concrete behavioral context about the output. No contradictions with 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?
Two sentences that are front-loaded: first sentence defines the action and output, second provides usage guidance. No redundancy or filler.
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?
Description covers the tool's role and usage context well. Output schema exists so return format is not required. However, the description does not clarify the roles of the 5 parameters (e.g., projectId vs projectRef), leaving some ambiguity for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 5 parameters with 0% schema description coverage. The description does not explain any parameter meaning, usage, or relationships. Given the lack of schema descriptions, the description should compensate but fails to do so.
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?
Description clearly states the verb 'explain' and the resource 'one file or subject fingerprint', and specifies the output: 'durable facts, findings, and relevant diagnostic runs'. It also distinguishes from sibling tool reef_scout by advising use after reef_scout.
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?
Explicitly provides context for usage: 'Use after reef_scout when the model needs the evidence trail and freshness details before editing.' This gives clear when-to-use guidance and implies an alternative, but does not explicitly state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds useful behavioral nuance about exact literals routing to a bounded preview, which goes beyond 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?
Two sentences, each serving a distinct purpose: defining scope and providing usage alternatives. No redundant or unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a good purpose statement and usage guidelines, the lack of parameter descriptions leaves gaps in completeness. The tool has 5 parameters with no explanation of how verbosity or limit affect results, or the role of projectId/projectRef.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fails to explain any of the 5 parameters (term, limit, projectId, verbosity, projectRef). The agent must rely solely on the schema for parameter meaning, which is insufficient.
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 clearly states the tool searches across multiple resource types (code chunks, schema objects, RPC/trigger bodies, routes, stored memories) and distinguishes from the sibling tool live_text_search, providing a specific verb and resource set.
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?
Explicitly advises when to use live_text_search instead (full inventories, regex, custom glob scope), giving clear context and alternatives for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read/write and non-idempotent behavior. The description confirms mutation by stating 'replace indexed Reef facts'. It also discloses dependency on existing snapshot. However, it could be more explicit about failure modes if snapshot is missing.
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, no unnecessary words. First sentence delivers the core purpose, second provides critical prerequisite. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the output schema exists (so return values need not be explained), the description lacks parameter coverage. For a 6-parameter tool, the description should detail at least the key parameters to be complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but only mentions a few aspects (snapshot, facts) and does not explain any of the 6 parameters (freshen, projectId, factsLimit, etc.). Users cannot infer parameter meanings from the description.
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 clearly states the verb (replace/index) and resource (Reef facts), listing many specific components. It distinguishes itself from sibling tools like project_index_refresh by explicitly mentioning it uses an existing snapshot and that the sibling should be run first if stale.
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?
Explicitly states when to use this tool (for ingestion after snapshot is ready) and when to use the alternative (run project_index_refresh first if stale). This provides clear context for choosing among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. Description adds that findings are durable, uses same overlay/source/status filters as project_findings, and supports source aliases. No contradictions.
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 concise sentences, front-loaded with purpose, no unnecessary words or repetition.
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?
Given the 9-parameter complexity and existence of output schema, the description provides sufficient context for understanding the tool's purpose and usage. Could be enhanced by mentioning the return value characteristics, but output schema compensates.
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?
Despite 0% schema description coverage, the description mentions 'overlay/source/status filters' and 'source aliases', which adds semantic context. However, it does not individually describe the 9 parameters beyond a high-level mapping, leaving some clarity gaps.
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 clearly states the tool returns 'durable Reef findings' for one file, identifies it as a read tool, and distinguishes it from sibling project_findings by specifying the same filters and source aliases.
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?
Explicitly says 'Use this before editing a file when a shell or agent needs known active diagnostics without rerunning broad lint.' Provides clear when-to-use context but does not elaborate on when not to use or explicitly name alternatives beyond project_findings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds valuable behavioral context: 'Read-only and does not execute the returned steps.' This reinforces and clarifies the tool's non-execution nature beyond the 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?
Two sentences with zero wasted words. The first sentence defines the tool's purpose and inputs/outputs. The second provides usage context. Front-loaded with the primary action and result.
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?
Given the complexity (12 params, 79 siblings), the description covers the essential purpose, usage, and most inputs. The output schema exists, so return values are documented elsewhere. Missing mention of maxSteps and project identifiers, but overall sufficient.
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 coverage is 0%, but the description lists many of the 12 parameters: focusFiles, changedFiles, focusRoutes, focusSymbols, focusDatabaseObjects, route, table, rpc, and the required task. However, maxSteps, projectId, and projectRef are not mentioned, providing incomplete semantics for those.
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 clearly identifies mako_help as an orientation tool that returns a Mako workflow recipe based on a task and optional anchors. It specifies the output structure (ordered tool sequence with pre-filled args) and distinguishes itself from sibling tools like reef_ask.
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?
Explicitly states when to use: before reading long AGENTS/CLAUDE docs when deciding how to start with reef_ask. Also notes it is read-only and does not execute steps, clarifying when not to use it. Could provide alternatives, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readonly and idempotent nature. Description adds useful behavioral details: default skips new-file scan, includeUnindexed triggers a more expensive walk, and clarifies that 'trust/stability' is separate from freshness. No contradictions with 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 concise (two sentences) and front-loaded with the core purpose. Every sentence adds value, and there is no redundant or filler content.
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 presence of an output schema (reducing need to explain return format), the description covers what the tool reports, default behavior, and the effect of the key parameter. It provides sufficient context for an agent to understand the tool's functionality without gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but only explains includeUnindexed. projectId, projectRef, and verbosity are not described. Though the schema provides enums for verbosity, their meaning (compact vs full) is absent, leaving ambiguity.
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?
Description clearly states the tool's purpose: compare indexed file rows against live disk metadata to report index freshness. It uses specific verbs and resources, and distinguishes itself from potentially confusing siblings like project_index_refresh by focusing on status rather than mutation.
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?
Description explains the default behavior and when to use includeUnindexed parameter, including the trade-off (repo walk cost). However, it does not explicitly mention when to use this tool over alternatives, such as project_index_refresh, though the context implies it is for checking status, not performing updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare the tool as read-only, idempotent, and open-world. The description adds valuable behavioral details: it loads specific file types, returns structured items with derived facts, and does not persist facts. It also clarifies the security scope ('reads only inside the project root'). No contradictions.
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 pack the essential purpose, behavior, and constraints. No filler. The first sentence is front-loaded with the core action and output, meeting conciseness and structure goals.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read tool with an output schema, the description is adequate but incomplete. It covers the general behavior and security, but lacks parameter details despite having 4 parameters. Given the schema's zero coverage, more parameter explanation would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It only hints at the 'files' parameter ('project-relative files') but fails to explain projectId, projectRef, or includeDerivedFacts. This is insufficient for understanding parameter semantics.
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 clearly states the tool's purpose: 'load .mako/instructions.md and applicable AGENTS.md files for requested project-relative files, returning structured instruction items plus derived Reef fact shapes.' It specifies the verb (load, return), resource (project instructions), and distinguishes from siblings by noting it is a read-only tool that does not persist facts.
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 implies usage for 'scoped project instructions' and 'requested project-relative files', and notes it 'Reads only inside the project root.' This provides context but does not explicitly state when to avoid this tool or suggest alternative sibling tools, leaving room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds detail: 'Suggestion-only', 'Never writes durable knowledge', lists data sources (resolved findings, repeated rule history, etc.). No contradictions.
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, front-loaded with main action, no unnecessary words. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 9 parameters (no required), an output schema, and is suggestion-only. Description covers core behavior and safety but lacks details on output format, error handling, or edge cases like empty results. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It hints at data sources (resolved findings, recent tool runs) but does not systematically explain each of the 9 parameters. Many params like mode, limit, since, projectId remain unexplained.
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 clearly states the verb 'propose' and resources (rule-pack, sentinel, etc.) and highlights it's suggestion-only. It distinguishes from sibling tools like list_reef_rules or reef_instructions by emphasizing no writes.
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?
Explicitly states when to use (suggestion) and when not (if writing is needed). Provides an alternative path ('explicit separate write path') though does not name specific sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description reinforces these by stating 'Read-only inspection' and 'Never writes to the event table,' and adds behavioral details like returning aggregate counts and a bounded list. No contradictions with 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?
Two clear, well-structured sentences, front-loaded with the core action and outputs. No extraneous information.
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?
The description covers purpose, usage, and key filters. It does not detail the output schema (but that is provided separately) or mention pagination. For a report tool with 8 optional parameters and an output schema, it is adequately complete.
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?
With schema description coverage at 0%, the description must compensate. It mentions four filterable parameters (decisionKind, family, requestId, ISO time window) but omits limit, since, until, projectId, and projectRef. This provides partial but incomplete enrichment over the schema.
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 clearly states the tool is a read-only inspection over mako_usefulness_events, returning aggregate counts and a bounded list of recent events, with specific filter parameters. It uses specific verbs and resources, distinguishing it from sibling tools like agent_feedback_report, though not explicitly contrasting.
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 explicit use cases: 'verify usefulness capture is flowing' and 'triage why a decision site emitted the grade it did,' plus a clear 'Never writes to the event table' disclaimer. However, it does not mention when not to use the tool or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true and idempotentHint=true, so the description's addition that it only finds direct references (not transitive) provides valuable behavioral context beyond annotations. No contradictions.
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: first states purpose concisely, second adds critical usage guidelines. No filler; every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values need no explanation. The description covers purpose and usage boundaries, but it omits any mention of prerequisites (e.g., indexing) and leaves parameter semantics unaddressed, making it just adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 4 parameters with 0% description coverage (no schema descriptions), but the tool description does not explain the meaning or usage of any parameter (e.g., projectId, projectRef, object, schema). The description only mentions 'indexed schema object' without mapping to parameters.
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 clearly states 'find where an indexed schema object is defined and directly referenced in app code', which is a specific verb and resource. It distinguishes itself from sibling tools by listing alternatives for transitive paths.
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?
The description explicitly states 'RPC-mediated touches are intentionally excluded' and provides four alternative sibling tools for transitive schema paths, giving clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant behavioral info beyond annotations: basis stability, artifactId shifting conditions, dedupe safety. No contradiction with readOnly/idempotent hints.
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?
Three concise sentences, front-loaded with purpose, each sentence adding unique value. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values need not be detailed. However, with 13 parameters and no schema descriptions, the description omits essential param semantics, leaving a major gap for tool usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 13 parameters, description mentions only two flags (includeSessionHandoff, includeIssuesNext) but fails to explain crucial parameters like queryKind, queryText, projectId, etc.
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 clearly states the tool composes a verification bundle, specifying verb 'compose' and resource 'verification bundle'. It differentiates from siblings by emphasizing artifact nature and safety.
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?
Provides specific guidance on when artifactId shifts (includeSessionHandoff, includeIssuesNext) and dedupe safety (both flags off). However, lacks explicit when-not-to-use or alternative tool mentions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, and openWorldHint=true. The description adds substantial behavioral context: it never edits files (read-only), explains the retry logic for ambiguous TSX/JSX snippets with auto-anchored parser context, describes the reef-backed freshness guard to avoid phantom matches, and mentions the MAKO_REEF_BACKED environment variable for rollback. No contradictions with annotations.
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 description is relatively long but front-loaded with the core purpose. Each sentence adds value, covering purpose, retry logic, freshness guard, and usage guidance. No fluff, but could be slightly more structured (e.g., separate sections). Overall efficient for the amount of information.
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?
Given 9 parameters with 0% schema coverage, the description explains key behavioral traits (retry, freshness, safety) and return values. However, it does not detail all parameters or provide output schema details (though output schema exists externally). For a moderate-complexity tool, it covers the most important aspects but leaves some gaps, such as parameter documentation and error conditions.
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 0%, so the description must compensate. It explains the 'pattern' parameter (ast-grep pattern), mentions 'captures' (captured metavariables), and implies 'languages' by listing file types. However, other parameters like projectId, projectRef, pathGlob, maxMatches, maxFiles, and excludeAcknowledgedCategory are not explained. The description adds partial value but is insufficient for all 9 parameters.
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 clearly states it is a code-intelligence tool for structural pattern search using ast-grep, specifies the file types (TypeScript/TSX/JavaScript/JSX), and lists the return value (typed matches: file, line range, column range, matched text, captured metavariables). It effectively distinguishes itself from text/FTS search by labeling it as structural pattern search.
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 explicitly says to use it when text/FTS search is too noisy for structural queries, with concrete examples like console.log($X) and await supabase.rpc($NAME). It does not explicitly exclude scenarios, but the 'use when' guidance is clear and helpful. It also mentions retry behavior for ambiguous TSX/JSX snippets, providing context for when the tool automatically adjusts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds behavioral context by specifying 'Read' and 'append-only ledger', reinforcing the read-only nature and providing details about the data source (local, persistent, append-only). No contradictions.
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 concise sentences: first describes function and filters, second gives usage context. No extraneous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 parameters, 0 required, and an output schema present, the description covers the core use case but does not detail all filter options or relationships between parameters. Missing mention of projectId/projectRef, which are likely needed for scoping. Could be more comprehensive.
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 0%, so the description must compensate. The description lists major filter categories (object, category, tag, query, fingerprint) but omits projectId, projectRef, schemaName, parentObjectName, and limit. Only provides partial parameter meaning beyond the schema.
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 clearly states 'Read DB review comments from Mako's local append-only ledger' with specific filtering options (database object, category, tag, free-text query, target fingerprint). It distinguishes from sibling tool 'db_review_comment' by indicating this is a read/browse operation rather than a single comment operation.
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?
Explicitly states to 'Use during schema/table/RLS/replication review to recover prior AI/operator notes.' Provides clear context for when to use, but does not mention when not to use or alternative tools like db_review_comment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and idempotentHint annotations, the description adds context: it queries a 'durable Reef findings view', status derivation from the 'finding_ack ledger', and the canonical nature of the read path. No contradiction with 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 two sentences, front-loaded with the core purpose, and each sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters and an output schema present, the description covers the core filtering purpose but leaves many parameters unexplained (projectId, projectRef, freshnessPolicy, limit, and the relationship between status and includeResolved). The tool is moderately complex, so more detail is warranted.
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?
With 0% schema description coverage, the description must compensate. It explains the 'source' parameter format and mentions filtering by overlay, source, status, and resolved inclusion. However, it omits explanations for the other parameters (projectId, projectRef, freshnessPolicy, limit, and details of overlay and status enums).
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 clearly states it is a 'Reef read tool for active project findings' and specifies the filters (overlay, source, status, resolved inclusion). It also positions itself as the 'canonical read path for Reef-native lint/rule findings', distinguishing it from sibling tools like finding_ack.
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 indicates it's a read tool for querying findings and explains the source filter format, but does not explicitly state when to use it versus alternatives or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses read-only behavior, default token budget (1024), maximum cap (16384), ranking algorithm (import-graph PageRank with bidirectional personalization), and symbol selection preference (exported declarations). This adds substantial value beyond the annotations (readOnlyHint, idempotentHint), providing deep behavioral transparency.
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 description is a single paragraph of three sentences, efficiently packing purpose, algorithm, default, and parameters. It is front-loaded with the core purpose, though some might find it dense. No wasted words.
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?
Given the tool has an output schema (so return values don't need full explanation), and the description covers purpose, algorithm, defaults, and parameter roles, it is fairly complete. It could mention that projectRef and projectId are identifiers, but the context is sufficient for most use cases.
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?
The description explains the purpose of focusFiles, focusRoutes, focusSymbols, focusDatabaseObjects, and tokenBudget, adding meaning beyond the schema. However, with 0% schema description coverage, it does not document all 10 parameters (e.g., pathGlob, maxFiles, maxSymbolsPerFile are not mentioned), leaving gaps.
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 clearly states the tool emits a token-budgeted outline of the indexed project (ranked files + key symbols) specifically for first-turn context when agents face an unfamiliar codebase. It uniquely distinguishes itself from sibling tools like flow_map or graph_neighbors by focusing on project orientation with a specific outline format.
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 explicitly says it is for 'first-turn context for agents meeting an unfamiliar codebase,' providing clear usage context. It also explains how focus parameters personalize the output, but does not explicitly state when not to use or compare to alternatives like ast_find_pattern or cross_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and idempotentHint=true, and the description does not contradict them. The description adds value by revealing that the search includes deferred and blocked tools, which is beyond the annotations. However, it does not detail other behavioral aspects like pagination.
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 two sentences long, front-loaded with the main purpose, and contains no unnecessary words. It achieves maximum conciseness.
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 low complexity (2 params, no enums, has output schema), the description covers purpose and usage adequately. The output schema handles return value details, so no further description is needed.
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?
With 0% schema description coverage, the description does not describe the parameters. However, the parameter names ('query', 'limit') are intuitive, and the search context implies their usage. A more explicit description would improve clarity.
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 clearly states the tool's purpose: to search the MCP-visible tool catalog, including deferred and blocked tools. It uses a specific verb ('Search') and resource, and differentiates from other tools by specifying the scope.
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 gives clear usage advice: 'Use when you are unsure which tool fits a task or why a tool is unavailable over MCP.' This provides context but does not explicitly mention alternatives or when not to use, though it is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits: it persists ProjectFinding rows (a side effect), runs a broad typecheck, and returns bounded findings. Annotations already indicate not read-only and not idempotent, but the description adds context about persistence and typecheck scope. However, it doesn't detail whether the operation is destructive or any rate limiting.
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 extremely concise: two sentences with no filler. It front-loads the core purpose ('Explicit Reef ingestion tool for semantic TypeScript compiler diagnostics') and efficiently adds usage guidance. Every sentence adds value.
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?
Given the complexity (5 parameters, side effects, output schema present), the description covers the primary behavior and distinguishes from a sibling. The output schema likely handles return values, so not describing them is acceptable. However, it could briefly mention the effect on the working tree or that it may be slow due to broad typecheck.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/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 by explaining each parameter. It only implies tsconfigPath and maxFindings but completely omits projectId, projectRef, and files. These are not self-explanatory from names alone, leaving the agent without critical details about what values are expected.
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 clearly identifies the tool as a 'semantic TypeScript compiler diagnostics' tool, specifying exactly what it does: read tsconfig, run TypeScript with no emit, persist findings, and return bounded results. It explicitly distinguishes from the sibling tool diagnostic_refresh for syntax-only refresh, making its purpose unambiguous.
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?
The description provides explicit guidance on when to use this tool versus alternatives: 'This may run a broad typecheck; use diagnostic_refresh with typescript_syntax for syntax-only refresh.' It tells the agent exactly which sibling tool to use for a lighter operation, making usage decisions clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description provides behavioral details beyond annotations: it is a mutation (consistent with readOnlyHint=false), it emits one telemetry event per successful row, and it shares batch-level defaults. No contradiction with 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?
Two sentences covering definition, use case, and side effects. No redundant information; each sentence adds unique value. Front-loaded with the core purpose.
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?
The description gives essential context: batch operation, defaults, use case, and telemetry. With an output schema present, return values are covered externally. However, it does not mention error handling behavior (continueOnError parameter) or row structure details, leaving some gaps for a tool with 12 parameters and nested rows.
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?
The description lists the default parameters that can be shared across rows (category, subjectKind, status, reason, etc.), adding meaning beyond the schema which has 0% description coverage. However, it does not explain all parameters (e.g., projectId, projectRef, preview, continueOnError, row fields like label, filePath, fingerprint). The baseline is 3 due to low coverage, and description partially compensates but not fully.
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?
Description clearly states it's a mutation batch for finding acknowledgements, appending multiple rows with batch-level defaults. It identifies the specific resource (finding_acks) and verb (batch append), and distinguishes itself from the singular 'finding_ack' sibling by emphasizing batch operation and defaults.
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?
Explicitly states when to use: 'Use when a scan returns many reviewed false positives or accepted tradeoffs.' It implies this is the batch alternative to the singular 'finding_ack', but does not explicitly mention when not to use or list alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds key behavioral information beyond annotations: it errors if the file already exists. Annotations already provide readOnlyHint=false and destructiveHint=true, and the description aligns with these. It does not mention other behaviors like permission requirements or return value, but the presence of an output schema and annotations reduces the burden.
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, front-loaded with the primary action, then error condition and alternative. Every word earns its place with no 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 simplicity (2 required params, no enums, no nested objects), the description covers the essential purpose, error condition, and alternative. Annotations and output schema fill remaining gaps, making it complete.
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 coverage is 100%, so both parameters have descriptions in the input schema. The description adds no additional meaning to the parameters beyond what is already in the schema. Baseline score of 3 is appropriate.
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 clearly states the verb 'create' and resource 'file at a project-relative path', and distinguishes it from the sibling tool file_write by noting that it errors if the file already exists and to use file_write to overwrite. This provides a specific and distinguishable purpose.
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?
The description explicitly states when to use this tool (to create a new file) and when not to (if file already exists, use file_write). This provides clear guidance on alternatives and conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only set readOnlyHint=false and idempotentHint=false, but description adds important behavioral context: 'Append-only' (non-destructive, no updates) and constraints like 'maxItems: 20' for reasonCodes. However, doesn't detail what happens on duplicate submissions or error behavior.
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 description is front-loaded with the core purpose, then gives usage guidance and parameter semantics in a structured way. While comprehensive, it could be slightly more concise without losing meaning.
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?
For a tool with 7 parameters (4 required, arrays, enums) and an output schema, the description covers the purpose, usage constraints, parameter roles, semantics, and behavioral traits. It leaves no significant gaps for an agent to use the tool correctly.
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 has 0% description coverage, but the description compensates by explaining grade semantics ('full = helped complete the task, partial = somewhat useful but flawed, no = wrong or wasted the turn') and listing starter reason codes for each grade. It also explains referencedToolName and referencedRequestId, but misses projectId and projectRef fields.
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 clearly states the tool's purpose as an 'append-only feedback tool for rating a prior Mako tool run from the agent perspective'. It distinguishes itself from the sibling 'agent_feedback_report' by being the writing tool.
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?
Explicitly advises to 'Use sparingly when a result was notably good, notably bad, or wrong; do not emit routine feedback after every call', providing clear when-to-use and when-not-to-use criteria. Also specifies that it 'Requires referencedToolName and referencedRequestId so each row is tied to a specific prior run'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, but the description adds rich behavioral details: runtime rejection of mutation/recursion, bounded concurrency with order preservation, projectId override, and output metadata (latency, per-op duration). No contradiction with annotations.
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 description is informative and front-loaded with the core purpose. It is slightly long but every sentence adds value, covering error modes, concurrency, output, and project isolation. Could be trimmed but remains effective.
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?
For a complex tool with 7 parameters and nested ops, the description is thorough. It covers batching semantics, concurrency, error handling, output format (label, duration, summary latency), and project override. Output schema exists but description still adds context. No gaps noted.
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?
With 0% schema coverage, the description must compensate. It explains the key parameters (ops, maxOps, projectId, verbosity, maxConcurrency, continueOnError) and their effects, such as compact vs full modes and error handling behavior. It lacks a bit of detail on projectRef but overall provides meaningful semantics.
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 precisely states the tool is a 'Read-only batching wrapper for independent Mako lookups', clearly distinguishing it from sibling tools by mentioning reduction of round-trips after context_packet expansions.
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 explains when to use (after context_packet recommends expansions), constraints on input tools, and details of continueOnError, maxConcurrency, verbosity, and resultMode. It doesn't explicitly state when not to use but implies via runtime checks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![agentmako MCP server](https://glama.ai/mcp/servers/drhalto/agentmako/badges/card.svg)](https://glama.ai/mcp/servers/drhalto/agentmako)

Score Badge

Copy to your README.md:

[![agentmako MCP server](https://glama.ai/mcp/servers/drhalto/agentmako/badges/score.svg)](https://glama.ai/mcp/servers/drhalto/agentmako)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/drhalto/agentmako'

If you have feedback or need assistance with the MCP directory API, please join our Discord server