tentra

Server Quality Checklist

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

Latest release: v1.2.0
Disambiguation4/5
Most tools have distinct purposes with clear boundaries, such as analyze_codebase for scanning, create_architecture for design, and diff_snapshots for comparison. However, some overlap exists between tools like get_architecture and list_architectures, or index_code and index_code_continue, which could cause minor confusion in selection.
Naming Consistency5/5
Tool names follow a highly consistent verb_noun pattern throughout, such as analyze_codebase, create_architecture, and diff_snapshots. This predictability makes it easy for agents to understand and navigate the toolset without ambiguity.
Tool Count3/5
With 32 tools, the count feels heavy for a single server, potentially overwhelming for agents to manage efficiently. While the domain of code analysis and architecture management is broad, the toolset could benefit from consolidation to reduce complexity and improve usability.
Completeness5/5
The toolset provides comprehensive coverage for codebase analysis, architecture management, and decision tracking, including CRUD operations (e.g., create, get, update, list architectures) and advanced features like diffing, linting, and exporting. No obvious gaps are present, ensuring agents can handle full workflows without dead ends.
Average 3.4/5 across 32 of 32 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- 0 of 1 community issues answered or closed in the last 6 months
- 2 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
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.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It hints at different indexing methods (local vs. via agent) but doesn't disclose performance characteristics, side effects (e.g., whether indexing is incremental or overwrites existing data), error handling, or authentication needs. The description doesn't contradict annotations, but it's insufficient for a tool with 6 parameters and no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence) and front-loaded with the core purpose. However, it's arguably too brief for a complex tool with 6 parameters and no output schema, leaving critical gaps in understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, 0% schema coverage, no output schema, no annotations), the description is incomplete. It doesn't explain what indexing does, what the output looks like, how to interpret results, or handle errors. Sibling tools like 'index_code_continue' suggest ongoing operations, but no context is provided for when to use which.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but fails to do so. It mentions 'Tier 1 local, Tier 2 via agent' which loosely relates to the 'tier' parameter but doesn't explain the 6 parameters (repo_path, repo_id, service_id, force_reindex, tier, batch_size) or their interactions. No parameter meanings, formats, or examples are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Index a code repository' which provides a clear verb ('Index') and resource ('code repository'), but it's vague about what indexing entails and doesn't differentiate from siblings like 'index_code_continue' or 'get_index_job'. The Tier 1/Tier 2 distinction adds some specificity but remains ambiguous without explaining what these tiers mean.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'index_code_continue' or 'get_index_job'. The description mentions 'Tier 1 local, Tier 2 via agent' but doesn't explain when to choose which tier or what the 'both' option means. No prerequisites 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action is to 'persist' data, implying a write operation, but fails to detail critical aspects like required permissions, whether the operation is idempotent, error handling, or what happens on success/failure. This leaves significant gaps in understanding the tool's 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and wastes no space, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 11 parameters with 0% schema coverage, no annotations, and no output schema, the description is insufficient. It does not compensate for the lack of structured data, failing to explain parameter meanings, behavioral traits, or expected outcomes, making it inadequate for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning none of the 11 parameters are documented in the schema. The description does not explain any parameters, such as what 'job_id', 'snapshot_id', or 'semantic_role_slug' represent, nor does it clarify the relationships between parameters like 'file_id' and 'symbol_id'. This lack of semantic information hinders effective tool invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('persist') and the resource ('agent-extracted semantic node for a file or symbol'), making the purpose understandable. However, it does not explicitly differentiate this tool from its siblings like 'record_contract' or 'record_decision', which also involve recording operations, leaving room for ambiguity in tool selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as other recording tools like 'record_contract' or 'record_decision'. There is no mention of prerequisites, context, or exclusions, leaving the agent without clear usage instructions.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the search mechanism (pgvector cosine distance) and what gets returned (semantically similar symbols or files), but doesn't address important behavioral aspects like whether this is a read-only operation, performance characteristics, rate limits, authentication requirements, or what happens when no matches are found. For a search tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise with two sentences that get straight to the point. The first sentence explains the search mechanism and input requirement, while the second describes the return value. There's no wasted language, though it could be slightly more structured for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a vector search tool with 4 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain the return format (what fields are included, how similarity scores are presented), doesn't mention error conditions, and provides minimal guidance on when this tool is appropriate versus other search methods. The agent would need to guess about important behavioral aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema, mentioning only that 'query_vector' requires embedding text first. It doesn't provide additional context about parameter interactions, typical values, or usage patterns that would help an agent understand the semantics better.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'vector similarity search using pgvector cosine distance' and returns 'semantically similar symbols or files', which is a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'query_symbols' or 'get_symbol_neighbors' that might also search for code-related entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal usage guidance, mentioning only that the agent should 'embed your text with your native embedding capability first'. It doesn't indicate when to use this tool versus alternatives like 'query_symbols' or 'get_symbol_neighbors', nor does it specify prerequisites or appropriate contexts for vector search versus other search methods.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a 'Get' operation which implies read-only behavior, but doesn't specify whether this requires authentication, has rate limits, returns real-time status or cached data, or what format the status information takes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core purpose without any wasted words. It's appropriately sized for a simple status-checking tool and front-loads the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and 0% parameter documentation, the description is insufficient. It doesn't explain what status information is returned, what job_id format is expected, or how this tool relates to the indexing workflow among the many sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description doesn't mention the 'job_id' parameter at all, and with 0% schema description coverage, the parameter is completely undocumented in both schema and description. However, since there's only one parameter and its purpose is somewhat inferable from context, this meets the baseline for minimal viability.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('status of an indexing job'), making the purpose immediately understandable. However, it doesn't differentiate this tool from potential siblings like 'index_code' or 'index_code_continue' that might also provide job status information, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'index_code' and 'index_code_continue' that might relate to indexing jobs, there's no indication of whether this is for checking status after initiation, monitoring progress, or retrieving results.
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 are provided, so the description carries the full burden of behavioral disclosure. It states the tool continues an indexing job, implying a mutation or processing action, but does not describe what 'continue' entails (e.g., resuming from a checkpoint, handling errors, or time/rate limits). This leaves significant gaps in understanding the tool's 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and appropriately sized for a simple tool, with no wasted information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of continuing an indexing job (a mutation operation), the lack of annotations, no output schema, and low parameter schema coverage, the description is insufficient. It does not explain what the tool returns, how errors are handled, or dependencies on other tools, making it incomplete for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 1 parameter with 0% description coverage, and the description does not add any details about the 'job_id' parameter (e.g., format, source, or constraints). Since schema coverage is low, the description should compensate but fails to do so, resulting in minimal added value beyond the schema's structural definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Continue') and the target ('an in-progress indexing job'), which is specific and unambiguous. However, it does not explicitly differentiate from sibling tools like 'index_code' or 'get_index_job', which could provide context on when to use this versus starting a new job or checking status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when there is an existing indexing job to resume, but it does not provide explicit guidance on when to use this tool versus alternatives like 'index_code' for new jobs or 'get_index_job' for checking status. No exclusions or prerequisites are mentioned, leaving usage context vague.
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?
With no annotations provided, the description carries full burden. It states the tool 'validates' and lists quality issues checked, but doesn't disclose behavioral traits like whether it's read-only vs. destructive, permission requirements, rate limits, or output format. The description is functional but lacks operational context needed for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first states the core purpose, second lists specific checks. It's front-loaded with the main action and efficiently enumerates examples without unnecessary elaboration. However, the second sentence could be slightly more structured (e.g., bullet points in the original formatting).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a validation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the output looks like (e.g., report format, error codes), success/failure conditions, or side effects. Given the complexity implied by checking multiple quality issues, more contextual information is needed for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with one parameter 'id' documented as 'The architecture ID to lint'. The description adds no additional parameter semantics beyond what the schema provides. Since schema coverage is high, baseline 3 is appropriate as the description doesn't compensate but doesn't need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'validate' and resource 'existing architecture' with a specific purpose 'for quality issues', and lists concrete checks like orphan nodes, duplicate connections, etc. However, it doesn't explicitly differentiate from sibling tools like 'get_quality_hotspots' or 'analyze_codebase' which might have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_quality_hotspots' or 'analyze_codebase'. It mentions what the tool checks but doesn't specify prerequisites (e.g., architecture must exist) or contextual triggers for usage.
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 are provided, so the description carries the full burden of behavioral disclosure. It mentions 'AI-inferred or human-confirmed assignments with a confidence score', which hints at mutation behavior and data sources, but fails to cover critical aspects like permissions needed, whether assignments are reversible, rate limits, or what happens on success/failure. For a mutation tool with zero annotation coverage, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the core functionality without any fluff. It's front-loaded with the main action and includes key details (entity types, assignment sources, confidence scoring) in a compact form, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with 5 parameters, no annotations, and no output schema, the description is incomplete. It lacks information on behavioral traits (e.g., side effects, error handling), usage context relative to siblings, and output expectations. The high schema coverage helps, but the description doesn't compensate for the missing structural context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by mentioning 'AI-inferred or human-confirmed assignments', which loosely relates to the 'source' and 'confidence' parameters, but doesn't provide additional syntax, format, or usage details. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Assign') and resource ('a file, symbol, or service to a domain'), making it easy to understand what it does. However, it doesn't explicitly differentiate from sibling tools like 'set_service_mapping' or 'link_decision', which might have overlapping functionality in domain/entity relationships.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions support for 'AI-inferred or human-confirmed assignments' but doesn't specify scenarios, prerequisites, or exclusions. With many sibling tools (e.g., 'set_service_mapping', 'link_decision'), this lack of differentiation is a significant gap.
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?
With no annotations provided, the description carries full burden but lacks critical behavioral details. It mentions the tool exports files but doesn't disclose whether this is a read-only operation, if it modifies the architecture, what permissions are needed, or what the output looks like (e.g., file paths, success indicators). For a tool that generates files, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two sentences: the first states the purpose and lists formats, the second provides usage note for output_dir. It's front-loaded with key information and avoids unnecessary details, though the long format list could be slightly condensed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (exporting to multiple formats, potentially generating files) and lack of annotations and output schema, the description is incomplete. It doesn't explain what the export produces (e.g., file contents, success response), error conditions, or behavioral constraints, leaving significant gaps for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters (id, format, output_dir) with descriptions and enum values. The description adds marginal value by clarifying that output_dir is 'required for code formats' and listing the format options, but doesn't provide additional syntax or format details beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports an architecture into various formats (runnable code, docker-compose, Mermaid diagram, or ADR docs), which is a specific verb+resource combination. It distinguishes from siblings like 'get_architecture' (retrieval) and 'create_architecture' (creation), but doesn't explicitly contrast with 'sync_architecture' or 'update_architecture' which might have overlapping export-like functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by listing available formats and noting that 'output_dir' is required for code formats, providing some contextual guidance. However, it doesn't explicitly state when to use this tool versus alternatives like 'get_architecture' for viewing or 'sync_architecture' for updating, nor does it mention prerequisites or exclusions.
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 are provided, so the description carries full burden. It states the tool lists contracts but doesn't disclose behavioral traits like whether this is a read-only operation, what permissions are required, how results are paginated or formatted, or any rate limits. The description is minimal and lacks essential operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('List all contracts in a workspace') and adds necessary detail about optional filtering. There's zero waste—every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete for a tool that likely returns a list of contracts. It doesn't explain what a 'contract' is in this context, what fields are returned, or how to interpret results. For a read operation with potential complexity, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters well-documented in the schema. The description adds marginal value by mentioning the optional filtering by kind, but doesn't provide additional semantics beyond what's already in the schema descriptions. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('List') and resource ('contracts'), and specifies the scope ('in a workspace'). It distinguishes the filtering capability by contract kind, but doesn't explicitly differentiate from sibling tools like 'record_contract' or 'bind_contract' beyond the 'list' action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing contracts with optional filtering by kind, but provides no explicit guidance on when to use this tool versus alternatives like 'record_contract' (which appears to be a sibling tool). There's no mention of prerequisites, exclusions, or specific scenarios where this tool is preferred.
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 are provided, so the description carries the full burden. It mentions the return content but lacks details on behavioral traits like rate limits, authentication needs, response format, pagination, or error handling. The description is minimal and doesn't compensate for the absence of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It is front-loaded, directly stating the tool's purpose without unnecessary details, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a 4-parameter tool with no annotations and no output schema, the description is incomplete. It doesn't explain the return values, error cases, or usage context, leaving significant gaps for an AI agent to understand how to invoke and interpret results effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all parameters. The description adds no additional meaning beyond what's in the schema, such as explaining the significance of 'depth' or 'include_semantics' in context. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Returns') and resource ('full code subgraph for a Tentra canvas service'), specifying what it returns ('files, symbols, and cross-service edges'). It distinguishes from siblings like 'get_architecture' or 'get_symbol_neighbors' by focusing on the complete subgraph with cross-service edges.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites, context, or exclusions, such as when to choose 'get_architecture' for structural overview or 'query_symbols' for specific symbols instead.
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?
With no annotations provided, the description carries full burden but lacks behavioral details. It states the action ('Link') but doesn't disclose permissions needed, whether the link is reversible, error conditions, or side effects. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and key details. Every word earns its place with no redundancy or unnecessary elaboration, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after linking (e.g., confirmation message, error responses), or address potential conflicts or dependencies, leaving significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds minimal value by listing entity types and link kinds, but doesn't provide additional context like examples or edge cases beyond what the schema already specifies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Link an existing decision') with the target resources ('service, file, symbol, contract, or domain') and relationship types. It distinguishes this tool from siblings like 'record_decision' (which creates decisions) and 'get_decisions_for' (which retrieves decisions), establishing a unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., requiring an existing decision ID), exclusions, or comparisons to sibling tools like 'bind_contract' or 'set_service_mapping', leaving usage context unclear.
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?
With no annotations, the description carries full burden. It mentions 'Persist' (implies write/mutation) and 'Supports supersession' (implies updates to older records), but lacks critical behavioral details: whether this creates or updates records, authentication/permission requirements, rate limits, error handling, or what happens on success/failure. The description is insufficient for a mutation tool with 10 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with zero waste. The first sentence states the core purpose, and the second lists key features—each word earns its place. It's front-loaded with the main action and efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutation tool with 10 parameters, no annotations, and no output schema, the description is incomplete. It lacks behavioral transparency (e.g., side effects, permissions), usage guidelines, and output expectations. While the schema covers parameters well, the description doesn't compensate for missing context about how the tool behaves or what it returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 10 parameters. The description adds minimal value beyond the schema—it mentions 'supersession' (hinting at 'superseded_by_id'), 'lifecycle status' (hinting at 'status'), and 'immediate entity links' (hinting at 'links'), but doesn't provide additional syntax, format, or usage context. Baseline 3 is appropriate given the comprehensive schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Persist') and resource ('Architecture Decision Record to the code graph') with specific capabilities ('Supports supersession, lifecycle status, and immediate entity links'). It distinguishes from siblings like 'get_decisions_for' (read) and 'link_decision' (add links later) by emphasizing creation/persistence with advanced features.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It mentions 'can be added later with link_decision' for links, but doesn't clarify when to use 'record_decision' versus 'create_architecture' or 'record_contract' for different artifact types, or prerequisites like needing a workspace.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions this is for 'attaching implementation evidence' which implies a write operation, but doesn't specify permissions needed, whether the binding is reversible, what happens on duplicate binding attempts, or any rate limits. For a mutation tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise - just two sentences that efficiently convey the tool's purpose and positioning in the workflow. Every word earns its place, with no redundant information or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 4 required parameters and no annotations or output schema, the description provides adequate basic context about what the tool does and when to use it. However, it lacks important behavioral details about permissions, idempotency, and error conditions that would be needed for robust agent usage, especially given the absence of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so parameters are well-documented in the schema itself. The description adds minimal value beyond the schema - it mentions the three relation types but doesn't provide additional context about when to choose each one beyond what's already in the schema's enum description. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Link a symbol to a contract') and specifies the three possible relations ('provides', 'consumes', or 'documents'). It distinguishes this tool from 'record_contract' by mentioning it's used 'after record_contract', but doesn't explicitly differentiate it from other sibling tools like 'link_decision' or 'set_service_mapping' that might also create relationships.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool ('after record_contract to attach implementation evidence'), which helps position it in a workflow. However, it doesn't specify when NOT to use it or mention alternatives among the many sibling tools, such as when to choose 'link_decision' instead for different relationship types.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation tool ('Create a step-by-step flow'), implying mutation, but doesn't address permissions needed, whether flows are editable/deletable, rate limits, or what happens on success/failure. For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with just two sentences. The first sentence defines the tool's purpose and scope, the second provides usage guidance. Every word earns its place with zero redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with no annotations, no output schema, and only 50% schema description coverage, the description is minimally adequate. It covers purpose and usage context but lacks behavioral details, parameter explanations beyond schema, and output information. For a creation tool with complex nested parameters, more completeness would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, so the description needs to compensate but doesn't. It mentions 'existing architecture' which relates to 'architectureId', and 'step-by-step flow' which relates to 'flow' with 'steps', but adds no additional meaning beyond what's in the schema. With moderate schema coverage, baseline 3 is appropriate as the description doesn't significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create a step-by-step flow on an existing architecture' with specific examples of what flows visualize (request paths, data pipelines, business processes). It distinguishes from siblings like 'create_architecture' by focusing on flows rather than architectures, but doesn't explicitly differentiate from all siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use: 'Use when the user asks to describe, trace, or explain a flow through the system.' This gives practical guidance, though it doesn't explicitly mention when NOT to use or name specific alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/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 what the tool does (compare snapshots) but lacks behavioral details like whether it's read-only, requires specific permissions, has rate limits, or what output format to expect. For a diff tool with no annotation coverage, this is a significant gap in 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and front-loaded, using a single sentence that efficiently lists key comparison aspects without unnecessary words. Every part of the sentence earns its place by specifying the tool's scope and outputs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (architectural diffing), no annotations, and no output schema, the description is moderately complete. It covers the purpose and aspects compared but lacks details on behavioral traits, output format, or error handling, which are important for such an operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with parameters 'from_snapshot_id' and 'to_snapshot_id' clearly documented as older and newer snapshot IDs. The description adds no additional parameter semantics beyond what the schema provides, such as format examples or constraints, so it meets the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('compare', 'diff') and resources ('two snapshots'), listing concrete comparison aspects like files added/removed/modified, symbols, and god-node deltas. It distinguishes from siblings by focusing on architectural diffing between commits, unlike tools like 'list_snapshots' or 'analyze_codebase'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for comparing snapshots in a commit-based context, suggesting when to use it (for architectural diffs). However, it lacks explicit guidance on when not to use it or alternatives, such as whether to use 'list_snapshots' for basic snapshot info instead.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates this is a read operation ('Retrieve', 'read the current state'), which is helpful, but doesn't address important behavioral aspects like error handling, authentication requirements, rate limits, or what format the architecture data returns in. For a tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each serve distinct purposes: the first states the core functionality, the second provides usage guidance. There's zero wasted language, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with 1 parameter and 100% schema coverage, the description provides adequate basic information about purpose and usage context. However, with no annotations and no output schema, it should ideally provide more behavioral context about what the retrieval returns and any constraints. The description is minimally complete but could be more helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the single parameter 'id' fully documented in the schema. The description doesn't add any meaningful parameter semantics beyond what's already in the schema ('The architecture ID to retrieve'). This meets the baseline expectation when schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Retrieve') and resource ('a specific architecture by ID'), making the purpose unambiguous. It distinguishes from siblings like 'list_architectures' by specifying retrieval of a single item, but doesn't explicitly contrast with all relevant alternatives like 'export_architecture' or 'sync_architecture'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('to read the current state before making updates'), which implicitly suggests it's for preparatory reads before mutations. However, it doesn't explicitly state when NOT to use it or name specific alternative tools for different scenarios.
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 provided, the description carries the full burden. It discloses the return type ('list of team or user handles') and the rule-based resolution mechanism, but lacks details on error handling, rate limits, authentication needs, or whether it's a read-only operation (implied but not stated).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: the first defines the tool's purpose and mechanism, the second specifies the return value. It's front-loaded with the core functionality and efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is moderately complete—it covers purpose and return format but lacks behavioral details like error cases or performance characteristics. Given the 2-parameter input with full schema coverage, it's adequate but could be more informative about operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds no additional meaning beyond what's in the schema (e.g., no examples of path formats beyond the schema's example, no clarification on workspace_id scope), meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Resolve the owner(s)'), target resource ('file path'), and mechanism ('according to the workspace CODEOWNERS rules'), with a distinct purpose from sibling tools like 'get_architecture' or 'get_contracts' that focus on different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives is provided. While the description implies usage for ownership resolution, it doesn't specify prerequisites, exclusions, or compare it to similar tools like 'get_decisions_for' or 'get_service_code_graph' that might handle related workspace queries.
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?
With no annotations provided, the description carries full burden. It mentions BFS traversal and efficiency gains, but lacks critical behavioral details: whether this is read-only or has side effects, authentication requirements, rate limits, error conditions, or what the output format looks like. The description provides some context but leaves significant behavioral questions unanswered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just two sentences that each earn their place: the first explains the core functionality and scope, the second provides the efficiency rationale. No wasted words, front-loaded with the essential purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no annotations, and no output schema, the description is incomplete. While it clearly states the purpose and efficiency benefit, it lacks information about output format, error handling, performance characteristics, and when to use versus siblings. The 100% schema coverage helps with parameters, but behavioral aspects remain underspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. The baseline of 3 is appropriate when the schema does the heavy lifting for parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs BFS graph traversal from a symbol, specifying the types of relationships explored (calls, imports, inheritance) and the efficiency benefit (eliminates 20+ file reads). It distinguishes from siblings by focusing on symbol-level graph traversal rather than broader codebase analysis or architecture management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for exploring symbol relationships efficiently, but doesn't explicitly state when to use this tool versus alternatives like 'query_symbols' or 'explain_code_path'. The efficiency claim suggests it's preferred over manual file reads, but no direct sibling comparisons are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes key behaviors: scanning directories, detecting services from specific config files, inferring connections, detecting infrastructure components, creating architectures, and running lint rules. However, it lacks details on permissions needed, whether it modifies the codebase (e.g., 'creates the architecture' might imply writing files or just generating a diagram), error handling, or performance characteristics like timeouts. The description adds value but leaves gaps for a complex analysis 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized at 6 sentences, each adding distinct value: the core action, detection sources, inference methods, component detection, output generation, and additional linting. It's front-loaded with the main purpose. While efficient, minor trimming could be possible (e.g., combining some detection details), but overall it avoids redundancy and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (automated codebase analysis with multiple detection methods) and no annotations or output schema, the description provides a good overview of what it does but has gaps. It covers the analysis process and output ('returns the URL'), but doesn't detail the format of the architecture diagram, error conditions, or what 'quality issues' entail. For a tool with rich functionality and no structured output documentation, more completeness would be beneficial to guide the agent fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters ('path', 'name', 'description') with clear descriptions. The description doesn't add any parameter-specific semantics beyond what the schema provides (e.g., it doesn't clarify format constraints for 'path' or examples for 'name'). The baseline score of 3 is appropriate since the schema does the heavy lifting, and the description focuses on overall tool behavior rather than parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('scan', 'generate', 'detects', 'infers', 'creates', 'runs', 'reports') and resources ('local codebase directory', 'architecture diagram', 'services', 'connections', 'databases', 'queues', 'external services', 'API gateways', 'quality issues'). It distinguishes itself from siblings like 'create_architecture' by specifying it's an automated analysis tool that scans codebases rather than manually creating architectures.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context through phrases like 'scan a local codebase directory' and 'automatically generate an architecture diagram', suggesting this tool is for initial analysis of existing codebases. However, it doesn't explicitly state when to use this vs. alternatives like 'create_architecture' (which might be for manual creation) or 'get_architecture' (which might retrieve existing ones). No explicit exclusions or prerequisites are mentioned.
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 are provided, so the description carries the full burden of behavioral disclosure. It mentions retrieving decisions but does not describe key behaviors such as authentication requirements, rate limits, pagination, error handling, or what the output looks like (since there's no output schema). This leaves significant gaps for an agent to understand how to interact with the tool effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and followed by usage context. Every sentence earns its place: the first defines the tool's function, and the second provides practical application, with no wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a retrieval tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., response format, error cases) and relies solely on the input schema, which doesn't cover output or operational context. This makes it insufficient for an agent to fully understand the tool's behavior and results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters well. The description adds minimal value beyond the schema by implying the tool retrieves decisions 'for a specific entity,' which aligns with the parameters but doesn't provide additional syntax, format details, or usage examples. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Retrieve') and resource ('all decisions that affect a specific entity'), specifying the entity types (service, file, symbol, contract, or domain). It distinguishes this from sibling tools like 'record_decision' (which creates decisions) and 'get_architecture' (which retrieves architecture data), making the purpose specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool ('to surface architectural rationale while reviewing code'), which implies it's for understanding design decisions during code review. However, it does not explicitly state when not to use it or name alternatives among siblings (e.g., 'get_architecture' for broader architectural data), leaving some guidance implicit rather than explicit.
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 are provided, so the description carries the full burden of behavioral disclosure. It states it 'List all saved architectures' but doesn't describe what 'all' entails (e.g., pagination, filtering, or sorting behavior), the return format, or any limitations (e.g., rate limits or permissions required). This leaves significant gaps for an agent to understand how the tool behaves beyond basic listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences that are front-loaded with the purpose and followed by usage guidance. Every word earns its place without redundancy, making it highly efficient and easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, no annotations, no output schema), the description is minimally adequate. It covers the purpose and usage but lacks behavioral details like return format or limitations. With no output schema, the description should ideally hint at what 'list' returns, but it doesn't, leaving some contextual gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, meaning no parameters are documented in the schema. The description doesn't add parameter details, which is appropriate since there are none. A baseline of 4 is applied for 0 parameters, as the description doesn't need to compensate for missing schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'saved architectures', making the purpose specific and understandable. It distinguishes from siblings like 'get_architecture' (which likely retrieves a single architecture) by implying a comprehensive listing. However, it doesn't explicitly differentiate from other list-like tools such as 'list_snapshots' or 'list_god_nodes', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'when the user asks to see, browse or find existing architectures'. This covers common user intents clearly. However, it doesn't specify when NOT to use it or mention alternatives (e.g., using 'get_architecture' for a specific architecture), which would be needed for a score of 5.
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 are provided, so the description carries the full burden of behavioral disclosure. It mentions the tool 'annotates each hop with semantic purpose,' which adds some context about output behavior, but it lacks details on performance (e.g., computational cost, rate limits), error handling, or data mutability (e.g., whether it modifies the snapshot). For a tool with no annotations, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and front-loaded, consisting of two sentences that directly state the tool's function and use case without any wasted words. Every sentence earns its place by clearly conveying purpose and context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is adequate but has gaps. It explains what the tool does and its use case, but without annotations or output schema, it lacks details on behavioral traits, return values, or error conditions. This makes it minimally viable but incomplete for full agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the input schema already documents all parameters ('from_symbol', 'to_symbol', 'snapshot_id') with clear descriptions. The description does not add any additional meaning or syntax details beyond what the schema provides, such as explaining symbol formats or snapshot constraints. Thus, it meets the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Finds', 'annotates') and resources ('shortest call/import path between two symbols'), and it distinguishes itself from siblings by focusing on path analysis rather than broader codebase operations like analysis, indexing, or architecture management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('Answers "how does X reach Y?"'), which implies it's for tracing dependencies or relationships between symbols. However, it does not explicitly state when not to use it or name alternatives among the sibling tools, such as 'get_symbol_neighbors' for local connections or 'analyze_codebase' for broader analysis.
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 discloses the ranking behavior and the composite score formula, which is valuable. However, it does not cover other behavioral traits such as performance characteristics, error handling, or data freshness (e.g., how 'latest snapshot' is determined). The description adds some context but leaves gaps in 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that is front-loaded with the core purpose ('Rank files by a composite score...') and ends with the outcome ('Top refactor candidates'). There is zero waste, and every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (ranking based on multiple metrics) and lack of annotations and output schema, the description is somewhat complete but has gaps. It explains the ranking logic but does not describe the return format (e.g., structure of ranked files), error cases, or dependencies. For a tool with no output schema, more detail on outputs would be beneficial, though the purpose is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description does not add any additional meaning or semantics beyond what the schema provides (e.g., it doesn't explain parameter interactions or provide examples). Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Rank files') and resource ('files'), and it distinguishes itself from siblings by focusing on a composite score of cyclomatic complexity × churn × (1 - test coverage) to identify top refactor candidates. This is more specific than general analysis tools like 'analyze_codebase' or 'lint_architecture'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for identifying refactor candidates based on a specific metric, but it does not explicitly state when to use this tool versus alternatives like 'list_god_nodes' or 'find_similar_code'. It provides context but lacks explicit guidance on exclusions or direct comparisons with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the tool's purpose and high-level behavior (listing god nodes based on fan-in/fan-out). However, it lacks details on permissions, rate limits, pagination, or response format. The description doesn't 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with zero waste. The first sentence states the purpose, and the second provides usage context. It's front-loaded and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, 3 parameters with full schema coverage, and no output schema, the description is minimally adequate. It covers the purpose and high-level usage but lacks behavioral details (e.g., output structure, error handling) that would be helpful for an AI agent, especially without annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 3 parameters. The description adds no parameter-specific information beyond what's in the schema (e.g., it doesn't explain how 'repo_id' or 'snapshot_id' affect the listing). Baseline 3 is appropriate as the schema handles the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'symbols flagged as god nodes', specifying the criteria 'very high fan-in or fan-out'. It distinguishes from siblings by focusing on architectural coupling hotspots, unlike tools like 'list_snapshots' or 'get_quality_hotspots'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for identifying architectural coupling hotspots, which suggests when to use it (for architectural analysis). However, it doesn't explicitly state when not to use it or name alternatives (e.g., 'get_quality_hotspots' might overlap for hotspots). No 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses behavioral traits like 'fuzzy trigram matching' and the return format ('symbol kind, file path, fan-in/out, semantic role'), but doesn't cover aspects like rate limits, authentication needs, or error handling. It adds value beyond the schema but isn't comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, with every sentence earning its place: it states the purpose, provides a performance comparison, and details the return format efficiently in three concise sentences without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters, no output schema, no annotations), the description is moderately complete. It covers the purpose, search method, and return values, but lacks details on error cases, pagination (beyond the limit parameter), or how results are ordered. Without an output schema, more return format explanation would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds context by mentioning 'fuzzy trigram matching' for the 'q' parameter and listing return fields that relate to parameters like 'kind' and 'role', but doesn't provide additional syntax or format details 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Search for symbols') and resources ('symbols by name or qualified name'), and distinguishes it from siblings by mentioning 'Replaces 10+ grep calls', which implies it's a specialized search tool unlike broader analysis tools like analyze_codebase or get_symbol_neighbors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fuzzy symbol searching, but doesn't explicitly state when to use this tool versus alternatives like find_similar_code or get_symbol_neighbors. It mentions replacing grep calls, which suggests a specific context, but lacks clear exclusions or named alternatives.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. While it mentions the tool persists data and returns a contract_id, it doesn't disclose important behavioral traits like whether this is a write operation (implied but not stated), what permissions are needed, whether it's idempotent, error conditions, or rate limits. For a tool that appears to create records with 6 parameters, this is insufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise - a single sentence that communicates the core purpose and the key output value. Every word earns its place, with no wasted text or redundancy. It's front-loaded with the main action and follows with the practical consequence (returns contract_id).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's apparent complexity (6 parameters, no annotations, no output schema), the description is minimally adequate but leaves significant gaps. It explains what the tool does and what it returns, but doesn't cover error conditions, side effects, or how the persisted contract integrates with the broader system. The lack of output schema means the description should ideally say more about the return value format beyond just 'contract_id'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description doesn't add any parameter-specific information beyond what's already in the input schema, which has 100% coverage with detailed descriptions for all parameters. The baseline score of 3 is appropriate since the schema does all the heavy lifting, though the description could have provided context about how parameters relate to each other or usage patterns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('persist'), the resource ('service contract'), and the destination ('to the code graph'). It distinguishes from siblings by mentioning the return value (contract_id) and referencing bind_contract, which is a sibling tool. This provides clear differentiation from other tools like get_contracts or analyze_codebase.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by stating this is for persisting service contracts and mentions the return value is used with bind_contract, giving implicit guidance on when to use this tool. However, it doesn't explicitly state when NOT to use it or mention alternatives among the many sibling tools, which prevents a perfect score.
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 are provided, so the description must fully disclose behavioral traits. It states the tool stores embeddings to populate a vector search index, implying a write operation, but lacks details on permissions, rate limits, idempotency, or error handling. For a tool with no annotations and a mutation action, this leaves significant gaps in understanding its behavior and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and followed by usage timing. Every word earns its place with no redundancy or fluff, making it highly efficient and easy to parse for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no annotations and no output schema, the description is somewhat complete for a basic understanding but lacks depth. It covers the what and when but omits behavioral details like side effects, response format, or error cases. For a mutation tool with 6 parameters, this is a minimal viable description that could benefit from more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all parameters are well-documented in the schema itself. The description adds minimal value beyond the schema by mentioning the tool is for storing embeddings after generation, but it does not provide additional semantic context for parameters like why snapshot_id might be optional or how vector dimensions relate to the model. Baseline 3 is appropriate as the schema carries the primary burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Store an embedding vector') and the target ('for a symbol or file'), specifying both verb and resource. It also distinguishes from potential siblings by mentioning it's used 'to populate the vector search index,' which sets it apart from other tools like record_contract or record_decision that handle different data types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context on when to use it: 'Call this after generating an embedding with your native capability.' This gives clear timing guidance. However, it does not specify when NOT to use it or mention alternatives among the many sibling tools, such as how it differs from record_semantic_node or other indexing tools.
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 are provided, so the description carries the full burden of behavioral disclosure. It mentions 'Assign' and 'update file mappings', implying a mutation operation, but does not specify permissions required, whether changes are reversible, error handling, or rate limits. For a tool that modifies data, this lack of detail is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and followed by usage context. Every word earns its place, with no redundancy or wasted text, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description adequately covers the purpose and basic usage but lacks details on behavioral aspects like mutation effects, error cases, or return values. For a tool with 2 parameters and 100% schema coverage, it meets minimum viability but leaves gaps in operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds minimal value beyond the schema, mentioning 'one or more files' and 'path → service_id pairs', which aligns with but does not expand on the schema's details. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Assign'), resource ('files in a snapshot'), and target ('Tentra canvas service ID'), distinguishing it from siblings like 'set_domain_membership' or 'get_ownership' by focusing on file-to-service mapping rather than domain or ownership queries. It explicitly mentions 'Use after indexing', which further clarifies its role in the workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context with 'Use after indexing to declare which service owns each file', indicating when to use it in the workflow. However, it does not explicitly state when not to use it or name alternatives among siblings, such as 'set_domain_membership' for different mapping types, leaving some ambiguity.
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 provided, the description carries full burden. It discloses key behaviors: scanning codebase, diffing against saved diagram, and reporting changes with accuracy score. However, it lacks details on permissions needed, rate limits, whether it modifies data, or what the output format looks like. For a tool with no annotations, this is adequate but leaves gaps in behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with zero waste: first states the core purpose, second explains the process, third specifies the output. Each sentence earns its place by adding distinct value, and the description is appropriately front-loaded with the main function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description provides good purpose and process clarity but lacks details on output format, error handling, or behavioral constraints. Given the complexity of architecture comparison, more context on what 'accuracy score' means or how results are structured would improve completeness, though the current description is minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('architectureId' and 'codebasePath'). The description adds context about what these parameters are used for (comparing saved architecture against codebase), but doesn't provide additional syntax, format, or constraints beyond what the schema states. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('compare', 'scans', 'diffs', 'reports') and resources ('saved architecture', 'current codebase', 'services/connections'). It distinguishes from siblings like 'diff_snapshots' (which might compare snapshots rather than architecture vs codebase) and 'analyze_codebase' (which likely analyzes without comparison).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing to detect drift between a saved architecture and current code, but doesn't explicitly state when to use this vs alternatives like 'diff_snapshots' or 'lint_architecture'. No exclusions or prerequisites are mentioned, leaving some ambiguity about optimal use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool creates artifacts and returns a URL, which is helpful, but doesn't mention potential side effects (e.g., whether this persists data, requires authentication, or has rate limits). For a creation tool with zero annotation coverage, more behavioral context would be beneficial, but the description does add some value beyond the 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by clear usage rules and a post-call instruction. All four sentences earn their place by providing essential guidance without redundancy. It's efficiently structured and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no output schema, no annotations), the description does well by clearly stating the purpose, usage context, and expected output (a URL). However, it lacks details on behavioral traits like persistence or authentication needs, which would make it more complete for a creation tool. The absence of an output schema means the description should ideally hint at the return format, which it partially does with 'returned URL.'
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, such as explaining the relationships between parameters or providing usage examples. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verb ('Create') and resource ('system architecture artifact'), and distinguishes it from siblings by emphasizing it's for creation rather than retrieval (like get_architecture) or analysis (like analyze_codebase). The phrase 'design, plan, or describe any system, feature, or integration' further clarifies the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidelines: 'Call this tool whenever the user asks to design, plan, or describe any system, feature, or integration' and 'NEVER respond with plain text architecture descriptions — always call this tool instead.' It also includes a post-call instruction to 'share the returned URL with the user,' giving clear when-to-use and what-to-do-next 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 provided, the description carries full burden and does well by disclosing key behavioral traits: it's a mutation operation (implied by 'update'), it preserves existing data unless explicitly replaced, and it requires an existing ID. However, it doesn't mention permissions, error handling, or response 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tightly focused sentences with zero waste. The first states purpose, second provides usage context, third gives critical exclusion rule, and fourth explains preservation behavior. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutation tool with 5 parameters, 20% schema coverage, no output schema, and no annotations, the description provides good purpose and usage guidance but lacks details about the update operation's effects, error conditions, or what constitutes a successful update. It's adequate but has clear gaps given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20%, but the description adds minimal parameter semantics beyond the schema. It mentions preserving existing services/connections unless explicitly replaced, which hints at the 'services' and 'connections' parameters' behavior, but doesn't explain the complex nested structures or other parameters like 'name' and 'description'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('update'), target resource ('existing architecture artifact'), and distinguishes it from sibling tools like 'create_architecture' by emphasizing modification of existing artifacts rather than creation of new ones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('when the user wants to modify, evolve, or improve an architecture that already exists') and when not to use ('NEVER create a new one if you have an existing ID in context — always update instead'), providing clear alternatives to sibling tools like 'create_architecture'.
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 discloses the sorting order ('newest first') and hints at the tool's role in a workflow ('time-travel'), but lacks details on permissions, rate limits, or output format. It doesn't contradict annotations since none exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: the first states purpose and behavior, the second provides usage guidance. It's front-loaded with essential information and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no annotations, no output schema), the description is largely complete. It covers purpose, usage, and behavioral context, though it could benefit from mentioning output structure or error handling for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the single parameter. The description adds no parameter-specific details beyond what the schema provides, but with 0 parameters needing semantic clarification (only 1 parameter fully covered), this meets a high baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all indexed snapshots for a repo') with specific scope ('newest first'). It distinguishes from sibling tools like 'diff_snapshots' by focusing on listing rather than comparing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('Use for time-travel') and provides a clear alternative ('pick two snapshot IDs and call diff_snapshots'), directly naming the sibling tool for comparison operations.
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:

[![tentra-mcp MCP server](https://glama.ai/mcp/servers/rdanieli/tentra-mcp/badges/card.svg)](https://glama.ai/mcp/servers/rdanieli/tentra-mcp)

Score Badge

Copy to your README.md:

[![tentra-mcp MCP server](https://glama.ai/mcp/servers/rdanieli/tentra-mcp/badges/score.svg)](https://glama.ai/mcp/servers/rdanieli/tentra-mcp)

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rdanieli/tentra-mcp'

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