grafema-mcp
Server Quality Checklist
Latest release: v0.4.2
- Disambiguation2/5
Many tools have overlapping purposes, such as multiple query/trace/explore tools (query_graph, query_graphql, trace_calls, trace_dataflow, get_neighbors, enox_explore, etc.). The descriptions try to differentiate, but the sheer number and functional overlap will confuse an agent about which tool to use.
Naming Consistency2/5Naming conventions are mixed: some tools use verb_noun (add_assertion, create_guarantee), some use noun-like prefixes (enox_query, enox_stats), and others are compound phrases (find_shared_behaviors, trace_dataflow). No consistent pattern, making it hard for an agent to predict tool names.
Tool Count2/5At 52 tools, the set is excessively large for a single server. Many tools could be merged (e.g., trace_* tools, find_* tools). This over-fragmentation increases cognitive load and reduces coherence.
Completeness3/5The tool surface covers a broad domain (project analysis, code query, knowledge graph, guarantees), but there are gaps: no tools for updating the code graph (only knowledge graph), and the 'enox' knowledge graph integration feels separate. Some common operations like 'delete' are missing for code graph nodes.
Average 4.3/5 across 52 of 52 tools scored. Lowest: 3.4/5.
See the Tool Scores section below for per-tool breakdowns.
- 1 of 1 community issues answered or closed in the last 6 months
- 375 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
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.jsonto 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
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states creation but omits side effects (e.g., overwrite on duplicate name), required permissions, error scenarios, or idempotency. The examples illustrate usage but not behavior beyond creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (few sentences) and front-loaded with the core purpose. It uses bullet points and examples effectively. However, it could be slightly more compact by removing redundancy in the examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the two main use cases and parameter combinations. However, it lacks details about return values (no output schema), error handling, or what happens after creation. For 11 parameters including nested objects, more context on expected outcomes would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents each parameter. However, the description adds significant value by explaining the two types (Datalog vs. contract), showing how parameters like 'rule' and 'type' interact, and providing concrete examples that clarify parameter usage beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The name 'create_guarantee' and description 'Create a new code guarantee' clearly indicate the tool's purpose. The description elaborates on two supported types with examples, distinguishing creation from sibling tools like check_guarantees and delete_guarantee.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description outlines two types of guarantees but provides no guidance on when to use this tool versus alternatives (e.g., check_guarantees for checking, update for modification). No explicit when-to-use, prerequisites, or exclusions 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?
Without annotations, the description carries the burden. It discloses that the tool generates hypotheses, verifies against the code graph, and records findings in a knowledge database. This gives a clear behavioral picture, though it could mention whether the operation is read-only or if it modifies the database.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences and an example. It is well-structured and front-loaded with the action. However, it could be slightly more structured with separate sections for behavior and parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the tool's function and side effects but lacks information about the return value or output format, as there is no output schema. Given the complexity and lack of output schema, more details on what the tool returns would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description provides an example usage but adds no additional semantic information beyond what the schema already provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run ontological crawl on a code entity — generate hypotheses and verify against code graph.' It gives an example and differentiates from siblings by focusing on hypothesis generation and verification, which is unique among tools like analyze_project or find_calls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not explicitly state when to use it versus alternatives. It mentions the code graph and knowledge database but lacks guidance on prerequisites or scenarios where this tool is preferred over similar ones.
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?
No annotations provided, so description carries full burden. Describes returns (tree), lists exclusions, but does not detail performance, permissions, or edge cases. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise, front-loaded with purpose, no redundant sentences. Every sentence adds value. Length is appropriate for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple tool with 3 optional params and no output schema, description covers purpose, usage, and exclusions. Lacks info on output format or errors but is sufficient for a read-only tree tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. Description adds minimal extra meaning beyond schema (e.g., default values repeated). Baseline score appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it gets the directory structure and returns a tree of files/directories. Provides context for use (studying a new project) but does not explicitly differentiate from siblings, though the usage hint helps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (when studying a new project) and lists excluded directories. Lacks explicit when-not-to-use notes, but the guidance is clear and actionable.
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?
No annotations provided, so description carries full burden. Only notes the tool is an update (non-destructive replacement) but lacks details on permissions, side effects, idempotency, or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus an example, front-loaded with main action. No superfluous words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter mutation tool with no output schema, the description effectively explains purpose, usage, and parameters. Could mention return values or side effects, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 3 parameters (100% coverage), so baseline is 3. Description adds context via example and brief explanations (fact_id, context, confidence) beyond schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states 'Update an existing edge in the knowledge graph' with specific verb and resource. Clearly distinguishes from siblings like add_assertion and delete_assertion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
States 'Use this to change the context or confidence of a previously recorded assertion without deleting and re-creating it', providing clear context for when to use. Does not explicitly mention when not to use or list alternatives, but the purpose is clear.
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?
No annotations are provided, so the description carries full burden. It mentions return structure (nodes with depth info) but does not disclose side effects, permissions, rate limits, or scope limitations. Adding such details would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: starts with purpose, lists usage examples with clear formatting, explains return format, and provides a concrete example. Every sentence is valuable, and it is front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the parameters (all documented in schema), no output schema, and the tool's complexity, the description covers essential behaviors: traversal logic, direction, edge filtering, depth, and return format. It could be more complete by mentioning any traversal limits or pagination, but it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning beyond the schema: it explains directions with examples, suggests edge_types filtering via 'omit for all', and notes max_depth default. This enhances the agent's understanding of parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs graph traversal from a knowledge entity, with specific edge types and direction. Examples illustrate usage. However, it does not explicitly differentiate from the sibling 'traverse_graph' tool, which may lead to confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear examples (dependencies, supersedes, full neighborhood) showing when to use the tool. It lacks explicit 'when not to use' or alternative tools, but the examples give strong contextual 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?
No annotations are provided, so the description carries full burden. It discloses return order, fields like hash and effects, and empty result interpretation. It does not mention cost or limitations, but for a read-only tool, it is fairly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points for output fields, and front-loaded with purpose. While slightly long, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has two optional parameters and no output schema, but the description explains the output structure in detail (cluster fields like hash, effects, features). This compensates well for lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both parameters described in schema). The description adds no extra meaning beyond the schema, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists clusters of FEATUREs with identical behavior (forward-slice hash). It uses specific verb 'list' and resource 'clusters of FEATUREs', and distinguishes from sibling tools like 'find_calls' by focusing on cross-modality duplication.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for detecting duplication (e.g., CLI commands wrapping same library as HTTP endpoints) but does not explicitly state when to use this tool over alternatives or when not to use it. No direct comparisons or exclusions 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?
No annotations provided, but the description thoroughly explains return fields, graph structure, and transitive behavior limits. It lacks disclosure on side effects (likely read-only) but is quite transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections and front-loaded summary. Slightly verbose but organized logically; earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately covers return values, call array structure, and transitive behavior. Missing error scenarios but otherwise complete for expected usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning for parameters (e.g., depth limit explanation is more about return), thus not exceeding baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves comprehensive function details including call relationships, with a specific verb and resource. It distinguishes from siblings like find_calls by emphasizing the full detail return.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides usage context such as transitive depth limit and when to use transitive flag, but does not explicitly differentiate from sibling tools or state when not to use this tool.
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?
With no annotations, the description carries full burden. It reveals the tool traces an alias chain to the original source but does not mention side effects, limitations, error behavior, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loading the main purpose and then providing a clarifying example. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks return value information (no output schema) and does not differentiate from siblings like trace_calls. The example helps but incomplete for full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for parameters is 100%, so the schema already documents both parameters. The description adds no additional meaning beyond the example, which implicitly relates to the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Trace an alias chain to find the original source.' It provides a concrete code example, making it distinct from siblings like trace_calls or trace_dataflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear use case with example code, indicating when to use the tool. However, it does not explicitly state when not to use it or mention alternatives among the many tracing 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?
No annotations provided, but the description discloses key behavioral traits: returns all incoming and outgoing edges with node summaries, and that it reveals relationships, dependencies, and contradictions. This adds significant context beyond the input schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short paragraphs and an example, with no wasted words. The main action is front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains return values (edges with summaries). It covers purpose, usage context, and parameter. Minor gap: no mention of side effects, permissions, or rate limits, but acceptable for a read-only exploratory tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'entity' is fully described in the schema (100% coverage), and the overall description adds an example ('RFDB V2 engine') but no additional meaning beyond the schema's description. 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get all edges') and resource ('entity in knowledge graph'), making it clear what the tool does. It distinguishes from siblings like 'get_neighbors' by focusing on full context and all connected 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use it ('understand full context'), but does not explicitly mention when not to use it or compare to alternatives like 'crawl_entity' or 'get_neighbors'. Usage context is implied but exclusion criteria are absent.
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?
No annotations provided, so description carries full burden. It explains return values (counts, percentage, skip reasons) and implies it is a read-only check. However, it does not disclose prerequisites (e.g., must have run analyze_project) or potential performance costs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise, with a clear two-sentence purpose, bullet-like use cases, and a return summary. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose, usage context, and return values. It is almost complete, though it could mention default values for path or depth limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description does not add much beyond the schema descriptions for path and depth. The baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it checks which files were analyzed/skipped, with specific use cases like finding gaps, verifying patterns, and debugging empty results. It distinguishes itself from siblings like analyze_project by being a post-analysis diagnostic 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to use AFTER analyze_project when queries return unexpected empty results, and lists four specific scenarios. No explicit when-not-to-use, but the context is clear and helpful.
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?
No annotations are provided, so the description carries the full burden. It implies a read-only operation ('Get') but does not explicitly state lack of side effects or other behavioral details. The example and parameter descriptions add 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three focused sentences plus an example. Each sentence serves a purpose: stating the function, providing usage guidance, and illustrating with an example. No extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with two optional parameters and no output schema, the description covers the core functionality and usage. The only minor gap is lack of explicit mention of the return format, but it is implied by the purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description repeats the schema's parameter descriptions. The example usage adds practical value, but the description does not provide new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Get' and the resource 'recently created or updated nodes and edges'. This distinguishes it from siblings like get_node or get_neighbors by focusing on recent cross-session activity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises use at session start to see other sessions' recent activity, which helps avoid duplication. Does not discuss when not to use or compare directly with siblings, but the context is useful.
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?
No annotations are provided, so the description carries full burden. It discloses that the tool is read-only (returns stats) and lists the output structure (total nodes, edges, counts by type, domain distribution). No contradictory or missing behavioral info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, uses a list for clarity, and front-loads the key verb. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description adequately covers purpose, usage, and return values. Could include more detail on domain distribution, but overall complete for a simple stats tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0 parameters with 100% coverage. According to guidelines, baseline is 4. The description adds context about what the tool returns, which is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves statistics about the Enox knowledge graph and lists specific use cases (check content, node/edge counts by type). However, it does not explicitly differentiate from sibling tools like 'get_stats' or 'get_coverage', but the purpose is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage scenarios (check content, see counts, assess density) and indicates the tool is for aggregate statistics. It does not mention when not to use it, but the 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?
With no annotations provided, the description carries full burden and adequately discloses key behaviors: provenance is computed on demand, the return includes the rule and body facts, the key format (wire-string terms, node IDs as decimals), and the meaning of a null result. It does not cover potential side effects or permissions, but these are minimal for a read-only explanation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) with no filler. It front-loads the core purpose, then explains the inverse relationship, default program, and example. Every sentence is informative and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description adequately explains what is returned (rule + body facts). It also covers the key format and null result. Missing details like error handling or pagination are not critical for this type of tool, so completeness is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value beyond schema: it provides an example for the common use case (predicate='depends'), specifies that node IDs in the key should be decimal, and explains that omitting source defaults to the bundled depends.dl. This reduces ambiguity for agents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool explains why a derived fact holds and returns the rule and supporting body facts. It uses specific verbs and resources like 'explain WHY a derived (Datalog) fact holds'. However, it does not explicitly distinguish from sibling tools like 'explain' or 'explain_gap', relying on the phrase 'inverse of "what holds"' which may not be sufficient for all agents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete usage context: the default program is depends.dl, and gives an example for explaining module dependency edges. It also covers custom rules and mentions the null result scenario. However, it does not explicitly state when not to use this tool or list alternatives, though it contrasts with 'what holds'.
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?
No annotations provided, so description carries full burden. It implies a read-only operation but does not explicitly state safety, side effects, or authentication requirements. The behavioral traits are not fully disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded main purpose followed by a bullet list of topics. Every sentence is useful; structure aids quick scanning. Slightly long but no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, topics, and usage context thoroughly. Lacks specification of return format (e.g., plain text or markdown), but output schema is absent, so this is a minor gap given the tool's nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with a list of topics. The tool's description enriches each topic with specific context (e.g., 'queries: Datalog query syntax'), adding semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves documentation about Grafema usage and query syntax, listing specific topics. It distinguishes itself from sibling tools that perform analysis, queries, or other operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to use when needing to learn Datalog syntax, DSL notation, or understand available features. Does not mention when not to use or list alternatives, providing clear but not exhaustive 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?
With no annotations, the description fully describes the tool's behavior: it executes queries, supports two languages, and lists predicates and types. It does not mention side effects (likely read-only), error handling, or performance limits beyond the parameters, but the examples provide clear behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with clear sections (predicates, node types, edge types, examples). It front-loads the main purpose. Some redundancy could be trimmed, but the structure aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers query languages, predicates, node/edge types, and examples. It does not explain the return format but provides enough context for a user to understand what the tool does. It is sufficiently complete for a query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds significant context: it explains the query languages, provides example queries, and details the predicates and node/edge types, enriching the meaning beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it executes Datalog or Cypher queries on the code graph, with specific verb 'Execute' and resource 'code graph'. It distinguishes from sibling tools like sim_datalog by specifying the query languages and providing detailed examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives comprehensive examples and lists available predicates and node/edge types, implying usage for graph queries. However, it lacks explicit guidance on when not to use this tool versus alternatives like find_nodes or find_calls, which could cover simpler cases.
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?
With no annotations, the description carries full burden. It explains registry contents, source_type values, and return format. It lacks details on authentication or rate limits, but those are less critical for a read-only query tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at around 150 words, with clear bullet points for usage and return types. Every sentence adds value, and the structure is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains return format and source_type values despite no output schema. It lacks explicit error handling, but for a simple query tool with two parameters, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, and the description adds value with examples and clarifies behavior when parameters are omitted. It explains that 'symbol' requires 'package' and the three output modes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it queries the local manifest registry for package exports and side effects, with specific examples. However, it does not explicitly differentiate from sibling tools like query_graph or semantic_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear list of when to use the tool, including knowing exports, checking effects, and verifying registry presence. It does not mention when not to use it or alternatives.
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?
No annotations are provided, so the description carries full burden. It explains that the subject becomes a node or reuses an existing one, and the fact is stored as an assertion. However, it omits other behavioral details like side effects (overwriting, reversibility) or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It starts with a clear purpose, lists use cases, explains the effect, and ends with an example. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, and effect, but lacks information about return values or confirmation. Given no output schema, a brief note on what the tool returns would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value beyond the schema by providing an example call and explaining that the subject becomes a node. This enriches understanding of how parameters interact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Quick knowledge write — store a fact about a subject.' It provides specific use cases and an example, distinguishing it from siblings like add_assertion by emphasizing simplicity and lack of graph structure specification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists scenarios to use the tool (discover something worth remembering, record results/decisions, quick jot down). It implies when not to use by contrasting with tools requiring exact graph structure, but does not explicitly state alternatives or 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?
With no annotations, the description carries full burden. It discloses that the committed graph is never touched, default program is bundled depends.dl, hypothetical node ids can be new, and only NEW facts are returned. This provides sufficient 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first sentence summarizing purpose, followed by specifics. It uses bullet points for clarity but is not excessively long. Front-loads the core purpose effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (Datalog simulation, hypothetical overlay), the description covers how to use it, parameters, default program, and companion tool. Though no output schema, it states what is returned (NEW facts). Sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 adds context like the default program and example usage, but the schema already documents each parameter's type and purpose. No additional semantic nuance beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool predicts NEW derived facts from hypothetical changes without committing, using a what-if simulation. It specifies the verb (predict/simulate) and resource (derived facts via Datalog), and distinguishes from sibling explain_gap by noting it verifies adding missing premises.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'Give it hypothetical nodes and/or edges' and gives a common use case for module dependencies. It mentions companion tool explain_gap but does not explicitly state when not to use or list 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?
Discloses that nodes are created if absent, a key side effect. No annotations present, so description carries burden. However, it does not mention idempotency or conflict behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short paragraphs plus an example, all front-loaded with purpose. No unnecessary words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, key behavior, and example. Lacks return value description, but given tool simplicity and no output schema, it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds little beyond schema; the example gives context but does not explain parameter constraints or relationships.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states specific verb 'Create' and resource 'edge between two nodes in the knowledge graph', clearly distinguishing from siblings like delete_assertion and update_assertion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases (specific relation, confidence, domain) and an example, but lacks explicit when-not-to-use or comparison with alternatives like bulk imports.
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?
No annotations provided, so description carries full burden. It only says 'Remove an edge' without detailing irreversibility, side effects, or permissions. Adequate but could be more explicit about consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences plus example, front-loaded with purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and no output schema, the description covers when to use, alternatives, and an example. Could mention return value or error handling, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with fact_id described as 'ID of the assertion/edge to remove'. Description adds an example format but no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Remove' and the resource 'edge from the knowledge graph'. It distinguishes from siblings by mentioning alternatives like update_assertion and add_assertion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'when an assertion is wrong, outdated, or no longer relevant'. Also provides alternatives: using update_assertion or add_assertion with supersedes relation.
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?
No annotations exist, so the description carries the full burden. It discloses that the document becomes a node, content is stored, and linking to entities is possible. This is sufficient for an agent to understand the behavioral impact (a write operation with persistence). It does not contradict any 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear purpose statement, bullet-pointed use cases, behavioral details, and an example. Every sentence contributes meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the four parameters, full schema coverage, and no output schema, the description provides enough context about what the tool does and how to use it. The example and usage guidelines make it complete for an agent, though a note about return values (e.g., created node ID) could enhance completeness slightly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all parameters, so the schema already explains each parameter's meaning. The description adds context (e.g., that doc_type defaults to 'note', and relates_to expects node IDs/names) and provides an example, but this adds only marginal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Store a document or artifact as a node in the knowledge graph.' It lists specific use cases (ADRs, postmortems, etc.) and provides an example, making the purpose unmistakable. This distinguishes it from sibling tools like 'remember' or 'describe' 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use the tool for 'longer-form content that should be persisted' and lists example document types. It also advises using 'relates_to' to link to entities. However, it does not explicitly state when NOT to use it or mention alternatives among siblings, such as 'remember' for potentially shorter-form content.
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?
With no annotations, the description fully discloses behavior: it uses DFS traversal, collects effects from leaf nodes via effects-db, handles UNKNOWN for unresolved calls, and returns direct/transitive effects, boundary crossings, and leaf sources. It does not mention performance or rate limits, but the core behavior is well explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence summary, bullet-pointed use cases, effect type explanation, and return value summary. Every sentence is useful, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains return values thoroughly (direct/transitive effects, boundary crossings, leaf sources) and defines effect types and UNKNOWN. It could be more complete by mentioning prerequisites or performance considerations, but it covers the essential context for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no new semantic information beyond the schema's parameter descriptions (node, file, max_depth). The schema already describes these adequately, and the description does not enrich them further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: tracing transitive side effects of a function through its call graph. It uses a specific verb ('Trace') and resource ('side effects'), and the detailed explanation distinguishes it from sibling tools like trace_calls by focusing on effects rather than just call chains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly gives use cases (e.g., 'What side effects does this function have?', 'Does this handler do IO?'), which helps an agent decide when to use this tool. While it does not name alternative tools directly, the context provides clear guidance on the tool's specific role 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?
With no annotations, the description carries the full burden. It reveals BFS algorithm, returns depth info, directional options, default maxDepth=5 and max=20. Does not mention performance or cycle handling, but overall transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: one-line summary, bullet use cases, return format, direction explanation, examples, tip. Front-loaded with verb and resource. Every sentence serves a purpose; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, parameters, return format, direction, examples, and a tip. Lacks error handling or limits on node count, but for a graph traversal tool the description is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already describes each parameter well. The description adds examples and a tip about using get_schema for edge types, providing marginal added value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Traverse the graph using BFS from start nodes, following specific edge types' and lists four distinct use cases, differentiating it from nearby siblings like get_neighbors (immediate only) and trace_* (path-specific).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Lists explicit use cases ('Use this for:') and gives examples, but does not explicitly exclude alternatives or mention when not to use it. Still provides clear context for when to select this tool.
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?
With no annotations, the description carries the full burden. It discloses a key behavioral trait: updates do not affect edges, which is beyond the schema. The example also clarifies usage. No contradictions present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—three sentences and a relevant example. Every sentence adds value, no redundancy. Front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers inputs and side-effects well, it does not describe the output/return value. Since there is no output schema, the description could mention what the tool returns after update. Minor gap, but otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, so the baseline is 3. The description does not add additional semantic details beyond the schema definitions; the example shows values but doesn't explain parameter constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'metadata on an existing node in the knowledge graph', and lists specific operations (rename, re-domain, add descriptions), distinguishing it from sibling tools like get_node or add_assertion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use it for renaming, re-domaining, or adding descriptions without affecting edges, providing clear context. It could mention explicit alternatives but the guidance 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?
For a query tool with no annotations, the description discloses exact/substring matching behavior and mentions default limit. It does not discuss read-only nature or performance implications, but such assumptions are reasonable for a filter query.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences plus an example. The action is front-loaded, and every sentence adds value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description explains the tool's purpose and how to use it, it does not describe the output format (e.g., returns list of nodes). Given no output schema, this is a gap. Also, it only contrasts with one sibling, leaving others unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by providing an example usage that shows how parameters combine, going beyond the schema's individual descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Filter nodes in the knowledge graph by type, domain, or name.' It uses a specific verb and resource, and distinguishes itself from 'semantic_search' by specifying exact/substring matching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends use for 'exact filtering when you know what you're looking for' and contrasts with 'semantic_search'. Provides an example. However, it does not mention when to use other 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?
Discloses that it returns graph query results plus a natural-language prompt for LLM summarization, and that no extra API call is needed. No annotations provided, so description carries burden effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with front-loaded key points. Bullet use cases are helpful. Could be slightly tighter but no excess.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, unique behavior, and parameter details adequately. No output schema or annotations, but the description provides enough context for an agent to decide when and how to invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions. Description adds context: elaborates on the 'question' parameter with examples and default behavior, and explains how parameters guide data fetching.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it 'explain a code element using graph data' and distinguishes from tools that return raw data. Use cases provide concrete examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly contrasts with other tools ('Unlike other tools...') and provides use cases, but does not directly name sibling alternatives like 'describe' or 'explain_fact'.
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?
With no annotations, the description fully covers behavior: it creates a GitHub issue if GITHUB_TOKEN is configured, otherwise returns a pre-formatted template. It also mandates asking permission, addressing consent. However, it could mention inactivity or retry behavior if the token is invalid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (about 10 sentences) with a clear structure: a one-line summary, a bullet list of use cases, a note on token configuration, and an important instruction. It is front-loaded and efficiently conveys key information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple reporting tool with no output schema, the description covers input parameters (via schema), behavior (issue creation vs. template), and a safety guideline (ask permission). It lacks details on error cases (e.g., invalid token) but is otherwise sufficient for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing baseline descriptions. The description adds only minor context for the 'context' parameter ('error messages, file paths, query used, etc.'). It does not elaborate on 'title', 'description', or 'labels' beyond what the schema provides, so value added is limited.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Report a bug or issue with Grafema to GitHub.' It lists specific scenarios (unexpected errors, incorrect results, missing features, documentation issues), clearly distinguishing this tool from all sibling tools, none of which serve an issue-reporting function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use this tool when you encounter: ...' with a bullet list of cases. It also includes the critical instruction to 'Always ask the user for permission before reporting an issue.' No alternative tool exists for this purpose, so no need for exclusion 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?
No annotations are provided, so the description carries the full burden. It discloses partial matches, automatic fuzzy fallback, and pagination (limit/offset). It does not mention destructive actions or authentication, but the tool appears to be 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with bullet points and examples. Every sentence adds value, and the information is efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters and no output schema. The description explains what the tool does, how to use it, and what the output is (semantic IDs). It also covers pagination. Missing details about error handling or empty results are minor, so the description is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents parameters. The description adds value by providing usage patterns (e.g., combining type and file) and explaining the fuzzy matching behavior for the name parameter, which goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds nodes in a graph by type, name, or file pattern, with specific examples. It distinguishes from sibling tools like get_node (retrieves a specific node) and find_guards, by noting that it returns semantic IDs for use with other 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases with examples (e.g., find functions in a file, find a class by name). It does not explicitly state when not to use this tool or compare to alternatives, but the examples effectively guide the user.
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?
No annotations provided, but description details the output: node info, source code, all outgoing/incoming edges, and code context. Mentions that primary edges include code context while structural edges are compact. Does not mention any destructive behaviors, which are not expected for a read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with a clear first sentence and bullet-like list of outputs. Slightly long but every sentence adds value. Could be slightly more concise but overall good.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but description comprehensively explains what the tool returns: node info, source code, all edges grouped by type, and code context. Distinguishes between primary and structural edges. Fully compensates for missing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but description adds value beyond schema: for contextLines it adds default value 3, for edgeType it gives example filter 'CALLS,ASSIGNED_FROM', and for semanticId it reiterates source. Adds useful context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it gets deep context for a graph node, including source code and full graph neighborhood. Distinguishes from siblings like get_neighbors and get_node by specifying it shows all edges grouped by type with code context at connected nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this after find_nodes or query_graph to deep-dive into a specific node.' Provides clear context for when to use. Does not explicitly mention when not to use, but the guidance 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?
With no annotations, the description carries full burden and discloses key behaviors: shows inherited members via EXTENDS chain, follows INSTANCE_OF for variables, and returns members, extends chain, implements list. Minor gaps like depth limits or performance are not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with purpose, and uses bullet-point examples that earn their place. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and absence of output schema, the description covers essential information: members, inheritance, and return values. It lacks explicit differentiation from siblings but is still very good.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining target can be CLASS, INTERFACE, variable name, or semantic ID, and file disambiguates. Examples clarify usage beyond basic schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets the shape (methods + properties) of a CLASS, INTERFACE, or typed variable, including inherited members. Examples differentiate it from sibling tools like get_function_details or get_node.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases with examples (e.g., 'What methods does GraphBackend have?') and explains behavior like following INSTANCE_OF. However, it doesn't explicitly state when not to use this tool or mention 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?
No annotations provided; description compensates with depth parameter details (speed vs. breadth) and an example. Discloses performance trade-offs but not auth or 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight paragraphs: purpose, usage, parameter details, example. No redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, parameters, and example. Missing return value description but not required for a recall tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; description adds value by explaining depth values (1=fast, 2=balance, 3=slower) and providing an example usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it combines embedding search with graph traversal for broad knowledge retrieval. Distinguishes from siblings like semantic_search and graph traversal 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly suggests use at session start or before decisions to check prior art and context. Provides clear context but no exclusions 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?
No annotations provided, so description carries full burden. It discloses that it follows CALLS and CALLS_REMOTE edges and returns an indented call tree with file:line locations. Missing details like performance limits or side effects, but sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with bullet points and examples, front-loading core purpose. Slightly verbose but every sentence adds value; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema provided, but description explains return format (indented call tree with locations). Covers main use cases thoroughly for a 4-param tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and schema already describes parameters well. Description adds context for direction and max_depth implicitly but does not add per-parameter details beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool traces call chains following CALLS and CALLS_REMOTE edges, distinguishing it from sibling tool `trace_dataflow` which follows data assignments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use scenarios (forward, backward, both) with examples and clarifies when not to use it by contrasting with `trace_dataflow`.
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?
With no annotations provided, the description carries the burden. It discloses validation and automatic directory creation. It implies partial overwrite without specifying merge details, but overall provides useful behavior information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a usage tip, containing exactly the necessary information with no fluff. The most critical information is front-loaded: purpose, then validation, then creation, then usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, nested objects) and rich schema, the description covers purpose, behavior, and usage guidelines. It lacks explicit mention of error handling or return value, but those are secondary for a write tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline is 3. The description adds value by explaining that only fields to override need inclusion and defaults apply, which clarifies the optional nature of all parameters and the partial update semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Write or update', the specific resource 'Grafema configuration file (.grafema/config.yaml)', and additional behaviors like validation and directory creation. It distinguishes itself from sibling tools which are read-only or analytical.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool 'after studying the project to save the discovered configuration' and explains the partial override behavior. It lacks a direct 'when not to use' statement, but the context signals make it clear this is for writing, not reading.
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?
With no annotations, the description carries full burden. It discloses that the tool returns a violations array with node IDs, file, line, rule name, and that an empty array means all pass. It does not mention side effects, but as a validation tool it's expected to be read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a main statement followed by bullet-pointed use cases and a clear return description. Every sentence is informative with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's single optional parameter and lack of output schema, the description is complete. It explains purpose, usage, return format, and includes an example, covering all necessary information for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description adds value beyond the parameter description by showing an example of usage with 'names' and explaining filtering. It provides practical context like pre-commit validation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Validate code against defined guarantees and return violations.' It lists specific use cases that differentiate it from siblings like add_assertion or list_guarantees, such as 'Find violations' and 'Verify specific rule'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage contexts: 'Find violations', 'Verify specific rule', 'Pre-commit validation', 'After code changes', and includes an example with the 'names' parameter. It lacks explicit 'when not to use' or alternatives, but the contexts are clear enough.
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?
Since no annotations exist, the description must disclose behavioral traits. It states the action is permanent removal, but does not detail authorization or side effects. This is adequate for a simple delete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence plus three bullet points. It efficiently conveys the action, usage, and a caution without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and no output schema, the description covers the action, usage, and a precaution, making it fully informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'name'. The description adds context about usage scenarios but does not provide additional meaning beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('delete') and the resource ('guarantee'), distinguishing it from siblings like 'create_guarantee' and 'list_guarantees'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides three specific scenarios for use and advises to verify the name with 'list_guarantees', offering clear when-to-use and preparatory 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?
With no annotations, the description carries full transparency burden. It thoroughly explains the tool's behavior: generates DSL notation with specific operators, depth-controlled detail, compression, and example output. It lacks explicit mention of side effects or auth needs, but given it's a read-like operation, the coverage is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with bullet points, an example output, and a clear breakdown of depth levels. Every sentence is informative and concisely communicates key details without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations or output schema, the description provides a self-contained explanation of the tool's purpose, output format, parameters, and usage context (e.g., line count savings). It is complete enough for an AI agent to understand and use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant extra meaning by elaborating depth levels (0-3) with precise definitions and an example. The perspective parameter is only listed in schema, but depth gets rich context. Overall adds value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Render a node's neighborhood as compact Grafema DSL notation.' It specifies the verb (render), resource (node's neighborhood), and output format. This distinctly differentiates it from sibling tools like analysis, querying, or exploration 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (reducing verbose edge listings, ideal for LLM context windows) and explains depth parameter behavior. However, it does not explicitly state when not to use it or compare to alternatives, which would improve 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?
Without annotations, the description carries the burden. It discloses the return format (file, line, resolved status) and implies a read operation with no side effects. It does not mention permissions or limits, but the tool's nature is simple search.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused paragraph with no redundancy. Examples are embedded naturally, and the structure is easy to parse. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with 4 params and no output schema, the description covers the purpose, use cases, and output sufficiently. It does not need additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by showing parameter usage in context (e.g., name='getUserById', className='redis') and giving default/max values, which help an agent understand parameter interplay.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds all places that call a specific function or method, with concrete examples (e.g., 'Who calls getUserById?'). It distinguishes itself from sibling tools like trace_calls by focusing on direct call sites.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists use cases with example questions, guiding when to use the tool. It does not directly mention when not to use it or compare to siblings, but the context is clear enough for an agent to decide.
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?
No annotations are provided, so the description carries full burden. It explains the behavior (walking from inner to outer scope) and the output fields (scopeId, scopeType, condition, constraints, file/line). It does not mention authorization or side effects, but for a read-only query tool, the transparency is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (about 10 lines) and well-structured: a one-line summary, a sentence on scope walking, bullet points for returned fields, and three example questions. No redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter and no output schema, the description fully covers what the tool does, how it works, what it returns, and typical use cases. An agent can confidently invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter (nodeId) with a basic description. The tool description adds meaning by explaining the parameter's role in context and giving examples ('e.g., CALL, VARIABLE'). Since schema coverage is 100%, the description adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Find conditional guards protecting a node' with a clear verb and resource. It distinguishes from sibling tools like 'find_calls' and 'find_nodes' by focusing on guard conditions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete use cases (e.g., 'What conditions guard this API call?') and a helpful question ('what conditions must be true for this code to execute?'). However, it does not explicitly state when not to use this tool or compare to alternatives, but the context is sufficiently 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?
No annotations provided, so description carries full burden. It discloses return type ('all node properties, type-specific metadata') and performance tip ('faster than get_context'). However, it does not mention what happens if node not found or any rate limits. Still adequate for a read-only query.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, bullet points, and a tip. However, some information is repeated (e.g., 'Get a single node' and later 'full details'). Could be slightly more concise, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with high schema coverage and no output schema, the description covers purpose, usage, return value, and alternatives adequately. Missing details like error handling or edge cases would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage for the single parameter 'semanticId'. The description adds context: 'Use this when you have a node ID from find_nodes, query_graph, or another tool.' This reinforces parameter purpose and provides examples of valid inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single node by its semantic ID with full metadata.' It uses a specific verb (get) and resource (node), and distinguishes itself from sibling tools like get_context and get_neighbors by explaining when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: 'Use this when you have a node ID from find_nodes, query_graph, or another tool.' It also provides alternatives: 'For relationships and code context, use get_context instead. For just the direct edges, use get_neighbors.'
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?
No annotations are provided, so the description fully bears the burden. It explains how edges are followed (ASSIGNED_FROM, PASSES_ARGUMENT, FLOWS_INTO) and what directions do. It does not mention side effects or state modifications, but as a trace tool it is inherently read-only. This is adequate disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and sections, no redundancy. It is front-loaded with the core purpose, and every sentence adds meaningful information. The tip at the end is concise and helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 params, no output schema), the description explains the return value ('List of nodes in the data flow chain with edge types and depth'). It covers direction options, use cases, and a practical tip, making the tool fully understandable for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, baseline is 3. The description adds value by elaborating on direction options (forward, backward, both) and advising to start with max_depth=5. It also briefly explains detail levels, going beyond the schema's bare descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Trace data flow paths from or to a variable/expression.' It specifies the verb 'trace' and resource 'data flow paths', and distinguishes itself from sibling tools like trace_calls and trace_effects by focusing on data flow with forward, backward, and both directions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when to use forward/backward/both tracing and gives concrete use cases (e.g., tainted data, impact analysis). It also recommends starting max_depth at 5. However, it does not explicitly mention when not to use this tool or suggest alternatives, which would earn a 5.
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?
No annotations are provided, so the description carries the full burden. It describes the behavior thoroughly: query execution, pagination, available query types (node, nodes, bfs, etc.), and node fields. However, it does not explicitly state that the tool is read-only or mention any side effects, though it is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise given the amount of information. It is well-structured with sections, bullet points, and an example. Every part serves a purpose, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a GraphQL query tool with 100% schema coverage and no output schema, the description is very complete. It lists all available top-level queries, node fields, and provides an example. It also references get_documentation for the full schema, covering any remaining gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all three parameters are described in the input schema). The description adds value beyond the schema by providing schema highlights, node field details, and an example query, which help the agent understand how to construct queries.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute a GraphQL query on the code graph' with a specific verb and resource, and distinguishes itself from the sibling tool 'query_graph' (Datalog) by explaining when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides usage guidance: 'Use GraphQL when you need nested data... Use Datalog (query_graph) for pattern matching...' and includes a pointer to get_documentation for the full schema, giving clear context on 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: it's a substring match (not semantic), case-insensitive, returns plain matches, and has a known limitation (RFD-63). This transparency helps the agent set correct expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: main purpose, limitation note, example. Front-loaded with key information, no redundancy, concise yet complete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with no output schema, the description covers behavioral aspects well. However, it lacks details about the return format (e.g., what fields are returned). An example partially compensates, but a bit more on output structure would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all 3 parameters with descriptions (100% coverage). The description adds an example with usage but does not enrich the semantics beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs case-insensitive substring search on knowledge-graph node names, distinguishing it from embedding-based semantic search. The verb 'search' and resource 'node names' are specific, and the note about RFD-63 clarifies its current limitations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use it ('substring search across node names') and when not ('not embedding-based', advises to use 'recall' for broader retrieval). It also clarifies that results are plain matches, not similarity-ranked.
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?
Describes return format (list of violations with file/line) and implies read-only nature, though could explicitly state non-destructive behavior. No annotations exist, so description carries 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with front-loaded purpose, clear differentiation, use cases, and return info. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a check tool: explains purpose, when to use vs alternatives, return format, and includes examples. No output schema but return description suffices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 4 parameters, but description adds value by providing a Datalog rule example and explaining the rule's role beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool checks one-off invariants using Datalog rules and returns violations. Distinct from siblings like create_guarantee by specifying ad-hoc vs permanent use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says use for ad-hoc checks and points to create_guarantee + check_guarantees for persistent rules. Provides concrete use cases with examples.
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 returns status and progress, including the return fields. It advises periodic polling after analyze_project. No annotations exist, so the description carries the full burden. It is transparent about the polling behavior, though it could mention potential errors 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with bullet points for usage and a clear list of return fields. It is front-loaded with the main purpose and efficiently organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description fully covers the required context: the purpose, usage scenarios, and return structure. It is complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the baseline is 4. The description does not need to add parameter details. It is sufficient for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the current analysis status and progress.' It specifies the tool's purpose with a specific verb and resource, and differentiates from siblings like analyze_project by indicating it is used to monitor progress.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists three use cases: polling progress, checking if analysis is running, and seeing the active phase. It provides clear context on when to use the tool, including after analyze_project.
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?
No annotations are provided, so the description carries full burden. It discloses that the tool returns a structured summary (imports, exports, classes, functions, variables) and implies it is non-destructive ('replaces reading'). It does not mention any side effects or permissions, but for a read-only tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with a bold key phrase, bullet-pointed return fields, and a clear usage flow. Every sentence contributes meaning without redundancy. It is concise yet thorough.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description provides a detailed list of return categories (imports, exports, etc.), compensating fully. The tool is simple (2 params) and the description covers purpose, usage, and output comprehensively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds value beyond schema. It explains the default for include_edges ('default: true') and its performance trade-off ('Set false for faster results'), which aids parameter selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's purpose: 'Understand what a file does without reading it — shows structure and relationships from the graph.' It uses a specific verb ('understand') and resource ('file'), and it distinguishes from sibling tools by positioning itself as the first step for file understanding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'USE THIS FIRST when you need to understand a file' and 'After this, use get_context with specific node IDs to deep-dive into relationships.' This provides clear when-to-use and when-to-use-next guidance, distinguishing from 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?
With no annotations, the description carries full burden. It discloses return format ('edges grouped by type with connected node summaries') and cost comparison, but does not explicitly state read-only nature or side effects. However, context implies no mutations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with general purpose, followed by structured sections for usage, direction, and edge types. No redundant sentences; every sentence adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description adequately explains return values. It covers all usage aspects and parameters, making it complete for a graph exploration tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). The description adds value by explaining direction options with concrete examples (calls, contains, depends on) and edge type filter usage ('Pass edgeTypes to see only specific relationships. Omit to get all edge types.').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get direct neighbors of a node — all incoming and/or outgoing edges.' It uses a specific verb (get) and resource (direct neighbors/edges), and distinguishes itself from sibling tools like get_context by noting it is cheaper and returns no code snippets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when-to-use scenarios: 'What does this node connect to?' and 'Simple graph exploration without Datalog.' It also mentions alternatives ('Cheaper than get_context') and gives direction options with examples.
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?
No annotations are provided, so the description carries full burden. It describes that it returns types and counts, but doesn't detail performance or limits. However, for a simple read-only discovery tool, the behavioral context is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, bullet-point use cases, options, and a tip. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple discovery tool with one parameter, the description is comprehensive: it explains purpose, use cases, parameter options, and return contents, fully compensating for the lack of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds value by explaining the effect of each option ('nodes', 'edges', 'all') and providing usage examples, going beyond the schema's enum definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets the graph schema (node/edge types with counts). It includes specific use cases like discovering types, validating edge types, and finding correct type names, differentiating it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists when to use this tool (discover types, validate edge types, understand structure, find correct names) and provides a tip to run it first when exploring a new graph.
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?
No annotations are provided, so the description must disclose behavior. It describes the return structure (nodeCount, edgeCount, nodesByType, edgesByType) and implies it is a read-only operation. Could add performance hints, but sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and a usage list. Every sentence is informative. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description fully covers purpose, usage, and output format. It is complete for a simple statistics tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so baseline is 4. The description does not need to add parameter details. It appropriately explains the output structure instead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get graph statistics: node and edge counts by type.' It uses specific verbs and resources, and distinguishes from sibling tools like enox_stats by focusing on graph statistics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists use cases (verify analysis, understand graph size, see types, debug) and recommends using it before querying an unfamiliar graph. Provides clear context for when to use the tool.
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?
No annotations are provided, so the description carries full burden. It lists the return fields (name, type, description, rule/schema, priority, status) but does not explicitly state that the operation is read-only or has no side effects. While the 'list' verb implies reading, making it explicit would improve transparency. Still, it provides good 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It starts with a clear one-line summary, then uses bullet points for use cases and return fields. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains what is returned (name, type, description, rule/schema, priority, status). The tool is simple (no params, no nested objects) and the description covers all necessary information for an agent to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% schema description coverage. With no parameters, the description adds no parameter details, which is appropriate. Baseline 4 for 0 parameters is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'all defined code guarantees (rules and contracts)', distinguishing it from siblings like 'check_guarantees' (which validates) and 'create_guarantee' (which creates). The purpose is 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides use cases ('See existing invariants', 'Understand code contracts before modifying code') and tells when to use it ('Use BEFORE check_guarantees'). This gives clear guidance on when to select this tool over alternatives.
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?
Discloses that this is a fast discovery only, returns no graph data, and describes the edge case when no config file exists. No annotations are provided, so the description carries full burden and meets it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points, workflow steps, and a tip. Front-loaded with purpose. Slightly lengthy but efficient, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description fully covers purpose, usage, return values, workflow, and edge case. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so schema coverage is 100%. The description adds value by explaining the return values (service names, paths, entry points) and workflow, exceeding the baseline of 4 for zero-param tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool discovers services in a project without full analysis, distinguishing it from analyze_project. It uses specific verbs and resources and includes the phrase 'before running analyze_project' to differentiate siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (during onboarding), when not (before full analysis), and provides a workflow step-by-step. It also mentions an alternative (write_config) for saving configuration.
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?
With no annotations, the description carries full burden. It details the return structure: the rule, satisfiable premises, and the first unsatisfiable premise. It explains the two cases (missing positive vs. present negated) and the 'no gap' result. This is comprehensive behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections explaining the dual nature, return value, interpretation of results, and a concrete example. Every sentence adds value, no fluff. It is appropriately detailed for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully explains the return value and edge cases. It covers the common use case, default program, and how to interpret results. Given the tool's complexity, the description is complete and self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context beyond schema: e.g., 'predicate' is the derived predicate, 'key' is ground tuple with wire-string terms and node IDs as decimal, 'source' is optional and defaults to depends.dl. This enriches understanding without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool explains why a derived fact does NOT hold, positioning it as the dual of explain_fact. It specifies the verb 'explain' and the resource 'missing derived fact', with concrete examples like module dependencies, making it distinct 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions the alternative explain_fact for when the fact is derivable, and provides a canonical use case for missing dependencies. The description guides when to use this tool versus others, e.g., 'A 'no gap' result means the fact actually IS derivable (use explain_fact).'
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?
No annotations are provided, so the description carries the full burden. It details the phases (Discovery→Indexing→Analysis→Enrichment→Validation), explains the effect of each option (force re-analyzes, index_only skips detailed analysis), and mentions the return type (summary with counts/timing). This provides thorough behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first sentence stating purpose, followed by necessary context, bullet-pointed options, and phases. Every sentence adds value, and there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters and no output schema, the description fully explains the tool's process, return value, and usage context. It covers the multi-phase analysis and provides a tip for verification, making it complete for an agent to understand and use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds significant value beyond the schema by explaining the purpose and effects of each parameter: service for faster multi-service analysis, force for re-analysis after code changes, index_only for fast module-only mode.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool builds a code graph by analyzing source code, using specific verbs like 'Build' and 'analyze'. It explicitly says it is required before using query tools, distinguishing it from sibling tools that query the graph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'REQUIRED before using query tools. Without analysis, the graph is empty.' It also provides guidance on options and a tip to verify with get_stats, making usage clear and well-defined.
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:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/Disentinel/grafema'
If you have feedback or need assistance with the MCP directory API, please join our Discord server