Server Quality Checklist

Tool Scores

• endsessionA
  4.4/5.0
  Behavior4/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 effectively describes the multi-stage workflow, revision capabilities, and output structure (e.g., 'success,' 'stageCompleted,' 'summaryMessage'). However, it lacks details on error handling beyond mentioning an 'error' field, and doesn't specify performance characteristics like rate limits or idempotency.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness3/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is front-loaded with a clear purpose and usage guidelines, but becomes overly verbose with detailed lists of features, stages, and parameter explanations that could be condensed. Sentences like 'Organizes development activity into a coherent project history' add minimal value. While structured, it could be more concise without losing essential information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity (9 parameters, multi-stage workflow, no annotations, no output schema), the description is largely complete. It covers purpose, usage, parameters, and outputs in detail. However, it lacks explicit error scenarios or edge-case handling (e.g., invalid 'stageData' formats), which would enhance robustness for an AI 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?

  Schema description coverage is 100%, so the baseline is 3. The description adds significant value by explaining parameter interactions (e.g., 'isRevision' and 'revisesStage' relationship), providing concrete examples for 'stageData' formats, and clarifying usage contexts like 'sessionId' from 'startsession.' This goes beyond the schema's technical definitions to aid practical application.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose as a 'multi-stage tool for documenting development sessions' with specific verbs like 'recording achievements, tracking task progress, and updating project status in the knowledge graph.' It distinguishes from siblings like 'startsession' by focusing on session conclusion rather than initiation, and from context tools by its session-specific workflow.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly states 'Only use this tool when the user explicitly requests it or provides explicit approval' under 'When to use this tool.' It also provides implicit guidance by detailing the 6-stage workflow and recommending completion 'in order for comprehensive session documentation,' helping differentiate it from simpler or single-purpose tools.

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

• loadcontextA
  4.5/5.0
  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 explaining key behavioral traits: it's a read-only retrieval tool ('only retrieves existing information'), provides formatted/hierarchical output, adapts based on entity type, and presents relationships. It doesn't mention rate limits, authentication needs, or error conditions, but covers core behavior thoroughly.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness3/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is well-structured with clear sections, but overly verbose at ~450 words. Many sentences in the 'You should' section are repetitive (e.g., multiple 'Explore...' items) and could be consolidated. While front-loaded with purpose, it could be more concise without losing value.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a 3-parameter tool with no annotations and no output schema, the description provides excellent context: clear purpose, detailed usage guidelines, parameter explanations, and behavioral traits. It lacks explicit output format details (though hints at 'formatted' and 'hierarchical'), but given the comprehensive parameter coverage and sibling differentiation, it's nearly complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  With 0% schema description coverage, the description fully compensates with a detailed 'Parameters explained' section. It explains all 3 parameters: entityName (required, with examples), entityType (optional, default value, accepted values list), and sessionId (optional, purpose, typical source). This adds substantial meaning beyond the bare schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: 'retrieving rich, contextual information about specific software development entities' with 'formatted details based on entity type.' It distinguishes from siblings like buildcontext (adds new entities) and deletecontext (removes entities), making the read-only retrieval purpose explicit.

  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 extensive guidance with a dedicated 'When to use this tool' section listing 9 specific scenarios, plus a 'You should' section with 13 actionable recommendations. It explicitly contrasts with buildcontext ('only retrieves existing information') and mentions startsession for session tracking, offering clear when-to-use and when-not-to-use guidance.

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

• startsessionA
  4.5/5.0
  Behavior4/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 effectively describes key behaviors: generating a unique session ID, retrieving recent sessions, active projects, high-priority tasks, and upcoming milestones. It also mentions tracking activity and progress, though it lacks details on rate limits, error handling, or authentication needs, which keeps it from a perfect score.

  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 well-structured with sections like 'When to use this tool,' 'Key features,' 'Parameters explained,' and 'Return information,' making it front-loaded and easy to scan. However, it is slightly verbose with detailed lists in the return section, which could be condensed without losing essential information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the complexity of the tool (session initialization with multiple data retrievals), no annotations, and no output schema, the description does a good job of covering purpose, usage, features, parameters, and return values. It explains what the tool does and how to use it with siblings, though it could benefit from more behavioral details like error cases or performance expectations.

  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 schema has 0 parameters with 100% coverage, so the baseline is 4. The description explicitly states 'No parameters required - the tool automatically retrieves all relevant context,' which adds clarity beyond the schema by confirming the automatic nature of the retrieval, though it doesn't need to explain parameters.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose as 'starts a new development session' and 'provides a comprehensive overview of the current development landscape,' which is a specific verb+resource combination. It distinguishes itself from siblings like 'loadcontext' (loads specific entities) and 'endsession' (ends sessions), making the differentiation explicit.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly states when to use this tool ('Beginning a new development work session' and 'Establishing context before diving into specific development work') and provides clear guidance on alternatives, such as using 'loadcontext' with the session ID and 'endsession' when work is complete. This covers both usage context and exclusions effectively.

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

• buildcontextA
  4.6/5.0
  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 so effectively. It discloses key behavioral traits: 'Three distinct operation types,' 'Type validation against software development domain standards,' 'Automatic rejection of invalid entity or relation types,' 'Safe addition of new observations,' 'JSON-formatted response,' 'Clear error messages,' and 'Handles both single and batch operations.' It covers most aspects well but could mention performance characteristics like rate limits or latency.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness3/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is appropriately structured with clear sections (purpose, when to use, key features, parameters explained, entity types, relation types, guidelines), but it is lengthy with multiple lists and detailed examples. While informative, some content could be more condensed without losing value, making it less front-loaded than ideal.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity (multiple operation types, extensive domain-specific types) and lack of annotations or output schema, the description is highly complete. It covers purpose, usage, behavior, parameters with examples, valid types, and detailed guidelines, providing all necessary context for an AI agent to use the tool effectively without structured fields.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The description adds significant meaning beyond the input schema's 100% coverage. It explains the 'type' parameter's three values with detailed semantics ('entities' for creating new entities, 'relations' for relationships, 'observations' for adding metadata) and provides extensive context for the 'data' parameter with examples of valid structures, entity types (14 listed), and relation types (17 listed). This greatly enhances understanding of how to structure inputs.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: 'building and enriching the software development knowledge graph through creation operations' and specifies it 'allows developers to add new entities, create relationships between entities, or add observations to existing entities.' It distinguishes from siblings like 'deletecontext' and 'loadcontext' by focusing on creation operations.

  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 includes an explicit 'When to use this tool' section with 8 specific use cases (e.g., 'Creating new project components,' 'Establishing relationships between development entities'), plus a 'You should' section with 10 detailed guidelines (e.g., 'Specify the operation type,' 'Ensure entities exist before creating relations'). This provides comprehensive guidance on when and how to use this tool versus alternatives.

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

• advancedcontextA
  4.8/5.0
  Behavior5/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 and does so comprehensively. It details six specialized query operations, explains return structures including error handling, specifies valid status and priority values, and describes how sequencing information appears. It covers behavioral aspects like partial matching, chronological ordering, and progress calculation that aren't inferable from the schema alone.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness3/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is well-structured with clear sections (When to use, Key features, Parameters explained, etc.), but it's excessively long with repetitive information. Sentences like 'It enables deep exploration of projects, components, relationships, decisions, and progress tracking' could be more concise, and some details in the 'You should' section overlap with earlier guidance, reducing efficiency.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity (6 operation types with varying parameters) and lack of annotations or output schema, the description provides complete context. It covers all operations, parameter structures, return formats, valid values, and usage strategies. The detailed explanations compensate for the missing structured data, making the tool fully understandable for an AI agent.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Despite 100% schema description coverage, the description adds significant value beyond the schema. It explains each 'type' enum value with specific use cases and details the 'params' structure for each operation type, including examples like { query: 'search text' } and { names: ['EntityName1', ...] }. This provides crucial semantic context that the schema's generic descriptions don't cover.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose as 'advanced querying and analysis of the software development knowledge graph' with specific verbs like 'extract meaningful insights,' 'deep exploration,' and 'tracking progress.' It distinguishes itself from siblings like 'buildcontext' and 'deletecontext' by focusing on query operations rather than creation or deletion.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides explicit guidance on when to use this tool with a dedicated 'When to use this tool' section listing 11 specific scenarios (e.g., 'Retrieving the complete development knowledge graph,' 'Exploring all relationships for a specific entity'). It also includes a 'You should' section with 11 actionable recommendations for selecting query types and refining searches, offering clear alternatives and context.

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

• deletecontextA
  4.8/5.0
  Behavior5/5

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

  With no annotations provided, the description carries full burden and delivers comprehensive behavioral disclosure. It explains cascading deletion effects, lack of undo, partial graph implications, relation prerequisites, and specific deletion behaviors for each operation type. The safety considerations section provides critical operational context beyond basic functionality.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness3/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  While well-structured with clear sections, the description is verbose with 10-item lists in multiple sections. Some redundancy exists (e.g., operation types explained multiple times). The core functionality could be communicated more efficiently while maintaining the valuable safety and usage guidance.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a destructive tool with no annotations and no output schema, the description provides exceptional completeness. It covers purpose, usage scenarios, parameter semantics, behavioral traits, safety considerations, and operational procedures. The absence of output schema is compensated by mentioning 'JSON-formatted response with operation results.'

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Despite 100% schema description coverage, the description adds substantial value through a dedicated 'Parameters explained' section that clarifies the meaning of 'type' options and provides detailed data structure examples for each operation. It transforms the abstract schema into concrete usage patterns with specific examples for entities, relations, and observations.

  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: 'removing elements from the software development knowledge graph' with three specific operation types (entities, relations, observations). It distinguishes itself from siblings like 'buildcontext' and 'loadcontext' by focusing on deletion rather than creation or retrieval.

  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 extensive guidance with a dedicated 'When to use this tool' section listing 10 specific scenarios, plus safety considerations and a numbered list of 10 actionable steps. It explicitly advises against using this tool for status/priority updates, directing users to 'appropriate tools' instead.

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