Server Quality Checklist

Tool Scores

• traverse_knowledge_graphB
  3.2/5.0
  Behavior3/5

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

  Annotations cover key traits (read-only, non-destructive, idempotent, closed-world), so the bar is lower. The description adds useful context about traversal depth limits and directionality, but doesn't disclose rate limits, authentication needs, or pagination behavior. No contradiction with annotations.

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

  Conciseness4/5

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

  Two sentences that efficiently convey core functionality without waste. Front-loaded with the main action and outcome, though it could be slightly more structured (e.g., bullet points for key parameters).

  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 moderate complexity (6 parameters, no output schema), the description is adequate but incomplete. It covers the traversal purpose but lacks details on error handling, return format (beyond 'nodes and relationships'), or integration with siblings. Annotations help, but more context would improve 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?

  Schema description coverage is 67% (moderate), with parameters like 'project_code' and 'max_depth' well-documented in the schema. The description mentions 'starting entity' and 'specified depth', aligning with schema but not adding significant meaning beyond it. Baseline 3 is appropriate as the schema does reasonable work.

  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 ('Walk the graph'), resource ('from a starting entity'), and outcome ('Returns connected nodes and relationships'). It distinguishes from siblings like 'search_knowledge_graph' by emphasizing traversal rather than search, but doesn't explicitly differentiate from 'list_knowledge_entities' or 'get_knowledge_entity' which might also return graph data.

  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 'search_knowledge_graph' or 'list_knowledge_entities'. The description implies usage for exploring connections but lacks context about prerequisites (e.g., needing a valid project from 'list_knowledge_projects') or exclusions.

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

• list_knowledge_projectsB
  3.4/5.0
  Behavior3/5

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

  Annotations cover key behavioral traits (read-only, non-destructive, idempotent, closed-world), so the description's burden is lower. It adds value by specifying the output fields (project IDs, names, codes, status), but does not disclose additional context like pagination, rate limits, or authentication needs. No contradiction with annotations exists.

  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 ('List all graph projects') and specifies output details without any wasted words. Every part earns its place by providing essential information.

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

  Completeness3/5

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

  Given the tool's low complexity (0 parameters, no output schema) and rich annotations, the description is adequate but minimal. It covers the purpose and output fields, but lacks usage guidelines or deeper behavioral context, making it complete enough for basic use but with clear gaps for optimal agent decision-making.

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

  Parameters4/5

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

  With 0 parameters and 100% schema description coverage, the baseline is high. The description does not need to explain parameters, and it efficiently states the scope ('all graph projects') and output details, adding clarity without redundancy.

  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 resource ('all graph projects'), specifying what information is returned (project IDs, names, codes, and status). However, it does not explicitly differentiate from sibling tools like 'list_knowledge_entities' or 'get_knowledge_statistics', which might also list related items, so it falls short of 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. For example, it does not mention when to choose this over 'search_knowledge_graph' or 'get_knowledge_statistics' for project-related queries, nor does it specify any prerequisites or exclusions for usage.

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

• get_knowledge_statisticsA
  3.6/5.0
  Behavior3/5

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

  Annotations cover key behavioral traits (readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false), so the description doesn't need to repeat these. It adds useful context about what the tool returns ('node/relationship counts broken down by type') and its utility ('understanding the graph's size and composition'), which goes beyond annotations. However, it doesn't disclose additional behaviors like rate limits, auth needs, or error conditions. No contradiction with annotations.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core purpose and followed by a utility statement. Every sentence earns its place by adding value: the first defines the action, and the second explains why it's useful. It's appropriately sized with zero waste.

  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 (2 parameters, no output schema), rich annotations (covering safety and idempotency), and clear purpose, the description is mostly complete. It explains what the tool does and its utility, which is sufficient for a read-only, idempotent tool. However, it could benefit from more detail on output format or usage examples, but annotations help fill gaps.

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

  Parameters3/5

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

  Schema description coverage is 50% (one parameter has a description, one does not). The description doesn't add any parameter-specific information beyond what the schema provides—it doesn't explain project_code or environment usage. Since schema coverage is moderate, the baseline is 3, as the description doesn't compensate for the lack of parameter details in the schema.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Get node/relationship counts broken down by type.' It specifies the verb ('Get') and resource ('node/relationship counts'), and distinguishes it from siblings like get_knowledge_entity or get_knowledge_schema by focusing on statistics rather than specific entities or schema details. However, it doesn't explicitly differentiate from all siblings (e.g., list_knowledge_entities might also provide counts), so it's not a perfect 5.

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

  Usage Guidelines3/5

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

  The description provides implied usage guidance: 'Useful for understanding the graph's size and composition.' This suggests when to use it (for analytics or monitoring), but it doesn't explicitly state when not to use it or name alternatives (e.g., vs. list_knowledge_entities for detailed listings). The context is clear but lacks explicit exclusions or sibling comparisons.

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

• get_knowledge_entityA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds value by specifying 'with all properties' which clarifies the completeness of returned data beyond what annotations provide. However, it doesn't mention potential rate limits, authentication needs, or error conditions.

  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 ('Get a single entity') followed by key qualifiers. Every word earns its place with no redundancy or unnecessary elaboration.

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

  Completeness4/5

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

  For a read-only retrieval tool with good annotations, the description is reasonably complete. It clarifies the scope of returned data ('with all properties') which is important given no output schema. However, it doesn't mention what happens if the entity doesn't exist or if there are access restrictions, which would be helpful 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?

  With 75% schema description coverage (3 of 4 parameters well-described), the baseline is 3. The description doesn't add any parameter-specific information beyond what's in the schema - it mentions 'by type and ID' which is already covered, but doesn't explain the relationship between parameters or provide examples beyond what the schema provides.

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

  Purpose5/5

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

  The description clearly states the verb ('Get') and resource ('a single entity'), specifies the selection criteria ('by type and ID'), and indicates the scope of returned data ('with all properties'). It distinguishes from siblings like list_knowledge_entities (which lists multiple entities) and get_knowledge_schema (which gets schema information).

  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 retrieving a specific entity when type and ID are known, but doesn't explicitly state when to use this vs. alternatives like search_knowledge_graph (for queries) or list_knowledge_entities (for browsing). It mentions project_code comes 'from list_knowledge_projects' which provides some prerequisite guidance.

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

• search_knowledge_graphA
  4/5.0
  Behavior4/5

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

  Annotations already indicate read-only, non-destructive, and idempotent behavior, which the description doesn't repeat. The description adds useful context beyond annotations: it specifies that the search covers 'all string properties' and returns 'relevance scores', which helps the agent understand the scope and output format. However, it doesn't mention rate limits, authentication needs, or pagination 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 two concise sentences that efficiently convey the tool's purpose and output. Every word earns its place: 'full-text search' defines the method, 'across all string properties' specifies scope, and the second sentence details the return values without redundancy.

  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 annotations cover safety (read-only, non-destructive) and the description adds behavioral context (search scope, output format), this is reasonably complete for a search tool. However, without an output schema, the description could benefit from more detail on the structure of returned nodes (e.g., property examples), but it's adequate for basic 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 67% (2 of 3 parameters have descriptions). The description doesn't add any parameter-specific details beyond what's in the schema (e.g., it doesn't explain 'project_code' or 'environment' further). With moderate schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate for gaps but doesn't detract either.

  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 ('full-text search'), target resource ('across all string properties in the knowledge graph'), and output ('returns matching nodes with their types, properties, and relevance scores'). It distinguishes from siblings like 'get_knowledge_entity' (specific entity retrieval) and 'traverse_knowledge_graph' (graph traversal).

  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 text-based search across the knowledge graph but doesn't explicitly state when to use this versus alternatives like 'list_knowledge_entities' or 'get_knowledge_entity'. It mentions 'full-text search' which suggests text matching, but no explicit guidance on when-not-to-use or direct alternatives is provided.

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

• create_knowledge_projectA
  4.2/5.0
  Behavior4/5

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

  Annotations indicate this is a non-readOnly, non-destructive, non-idempotent operation with openWorldHint. The description adds valuable context beyond annotations: it specifies the deployment environment (staging), mentions a 30-60 second execution time, and details the created schema (Topics, Articles, Authors, Concepts), which helps the agent understand behavioral traits like latency and resource creation. No contradiction with annotations.

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

  Conciseness5/5

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

  The description is front-loaded with the core action, followed by key details (schema components, deployment, timing). Every sentence adds value: the first defines the tool, the second specifies schema and deployment, and the third warns about latency. No wasted words, making it efficient and well-structured.

  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 (creates a database with schema), annotations cover safety and idempotency, but there's no output schema. The description compensates by detailing the created schema and timing, though it could mention response format or error handling. It's mostly complete but has minor gaps in output expectations.

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

  Parameters3/5

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

  Schema description coverage is 100%, with clear descriptions for both parameters (name and optional description). The description doesn't add meaning beyond the schema, as it doesn't explain parameter usage, constraints, or examples. Baseline score of 3 is appropriate since the schema adequately documents 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 specific action ('Provision a new knowledge graph project') and resource ('Neo4j graph database'), distinguishing it from siblings like 'delete_knowledge_project' or 'list_knowledge_projects'. It specifies the schema components (Topics, Articles, Authors, Concepts) and deployment target (staging), making the purpose explicit 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 implies usage context by stating it creates a project with a knowledge-optimized schema and deploys to staging, suggesting it's for initial setup. However, it doesn't explicitly state when to use this versus alternatives like 'list_knowledge_projects' for checking existing projects or 'delete_knowledge_project' for removal, 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.

• delete_knowledge_projectA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare destructiveHint=true, readOnlyHint=false, etc., covering safety and mutability. The description adds valuable context by emphasizing 'ALL its data' and 'cannot be undone,' which reinforces the destructive nature beyond the annotation, but does not detail error handling or permissions.

  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 action and critical warning in just two sentences, with zero wasted words. Every sentence earns its place by conveying essential information efficiently.

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

  Completeness4/5

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

  Given the tool's complexity (destructive deletion) and lack of output schema, the description is mostly complete by highlighting irreversibility. However, it could improve by mentioning potential side effects or confirmation steps, though annotations cover key behavioral traits.

  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 the parameter 'project_id' fully documented as a UUID. The description does not add any extra semantic details about the parameter beyond what the schema provides, so it meets 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 explicitly states the verb ('Delete') and resource ('a graph project and ALL its data'), making the purpose specific and clear. It distinguishes from sibling tools like 'create_knowledge_project' or 'list_knowledge_projects' by focusing on removal rather than creation or listing.

  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 'DESTRUCTIVE — cannot be undone,' indicating when to use it cautiously. However, it does not explicitly mention alternatives (e.g., archiving instead of deleting) or prerequisites (e.g., ensuring no dependencies), 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.

• fetch_url_contentA
  4.2/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond annotations: it specifies that the tool returns both text content and metadata (title, author, date), which isn't covered by the annotations. While annotations already indicate it's read-only, non-destructive, idempotent, and open-world, the description usefully explains what kind of data is returned and its purpose in the workflow.

  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 and front-loaded: the first sentence states the core functionality, the second explains the return values and their purpose. Every sentence earns its place with no wasted words or redundant information.

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

  Completeness4/5

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

  Given the tool's moderate complexity (web scraping), rich annotations, and lack of output schema, the description does well by explaining what's returned (text content and metadata) and how it fits into the broader workflow. However, it could be more complete by mentioning potential limitations (e.g., rate limits, authentication needs for certain sites, or content type restrictions).

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

  Parameters3/5

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

  With 100% schema description coverage for the single 'url' parameter, the schema already fully documents the input. The description doesn't add any additional parameter semantics beyond what's in the schema (e.g., URL format requirements, supported protocols, or error handling for invalid URLs), so it 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 specific action ('scrape a URL and extract clean text content') and resource (URL), distinguishing it from sibling tools like 'ingest_text_content' which handles text input rather than web scraping. It explicitly mentions what the tool does beyond just the name/title.

  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 ('for the LLM to read, extract entities from, and then call add_knowledge_nodes/relationships'), but doesn't explicitly state when NOT to use it or name specific alternatives among siblings. It implies usage in a knowledge graph workflow but lacks explicit exclusions.

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

• list_knowledge_entitiesA
  4.2/5.0
  Behavior4/5

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

  Annotations cover key traits (read-only, non-destructive, idempotent, closed-world), but the description adds valuable context: it implies that entity types are not known upfront and must be discovered via another tool ('get_knowledge_schema'). This behavioral nuance about dependency and discovery is not captured in annotations, enhancing transparency without contradiction.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core purpose and followed by a crucial usage guideline. Every word serves a clear purpose, with no redundancy or unnecessary elaboration, making it highly efficient and well-structured.

  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 moderate complexity (5 parameters, no output schema), the description is fairly complete. It covers purpose and usage, and annotations provide safety and behavioral traits. However, it lacks details on output format or error handling, which could be helpful for an agent, leaving a minor gap in completeness.

  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 high (80%), so the baseline is 3. The description adds minimal parameter semantics by mentioning 'entity type' as an example, but it doesn't provide additional meaning beyond what the schema already documents (e.g., details on 'project_code' or pagination behavior). It compensates slightly but not significantly.

  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 resource ('entities of a specific type'), making the purpose understandable. However, it doesn't explicitly distinguish this tool from sibling tools like 'list_knowledge_projects' or 'search_knowledge_graph', which might also list entities in different contexts, so it misses full sibling differentiation.

  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: 'Use get_knowledge_schema first to see available entity types.' This indicates a prerequisite step and helps the agent understand the proper sequence, effectively distinguishing it from alternatives by specifying a preparatory action.

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

• add_knowledge_nodesA
  4.4/5.0
  Behavior4/5

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

  Annotations already indicate this is a write operation (readOnlyHint=false), non-destructive, non-idempotent, and open-world. The description adds valuable context beyond annotations: it specifies bulk creation, mentions the LLM extraction workflow, and references schema validation requirements. However, it doesn't disclose rate limits, error handling, or confirmation of creation success.

  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 front-loaded with the core purpose in the first sentence, followed by essential usage guidance. Every sentence earns its place by providing critical context about entity structure, schema dependencies, and workflow integration without any redundant information.

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

  Completeness4/5

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

  For a bulk creation tool with comprehensive annotations and full schema coverage, the description provides excellent context about the workflow (LLM extraction, schema checking) and distinguishes from siblings. The main gap is the lack of output schema, leaving return values unspecified, but the description compensates well with operational guidance.

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

  Parameters3/5

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

  With 100% schema description coverage, the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema: it reinforces kebab-case format for entity_id and mentions matching schema fields for properties, but doesn't provide additional syntax or format details. 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 specific action ('bulk create entities in the knowledge graph'), specifies the resource ('entities'), and distinguishes from siblings by mentioning the LLM extraction context and bulk nature. It explicitly contrasts with get_knowledge_schema for schema discovery.

  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 ('bulk create entities') versus alternatives ('use get_knowledge_schema first to see available entity types and their fields'). It also mentions prerequisites (extracting entities from content) and references list_knowledge_projects for project codes.

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

• add_knowledge_relationshipsA
  4.4/5.0
  Behavior4/5

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

  Annotations provide readOnlyHint=false (mutation), openWorldHint=true (flexible schema), idempotentHint=false (non-idempotent), and destructiveHint=false (non-destructive). The description adds valuable context beyond this by specifying it's a 'bulk create' operation, mentioning that entities must already exist ('matching existing entity_ids'), and that properties are optional. No contradiction with annotations.

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

  Conciseness5/5

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

  Two sentences with zero waste. The first sentence clearly states the purpose and key requirements. The second sentence provides crucial usage guidance. Every word earns its place, and the structure is front-loaded with the core functionality.

  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 mutation tool with no output schema, the description provides good context about the operation's nature (bulk create), prerequisites (existing entities, need to check schema), and scope (relationships with optional properties). The annotations cover safety aspects well. Minor gap: doesn't mention response format or error handling.

  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 fully documents all parameters. The description adds minimal semantic context by mentioning that from_id/to_id must match 'existing entity_ids' and that rel_type must match 'schema', but doesn't provide additional meaning beyond what's in the schema descriptions. 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 specific action ('Bulk create relationships'), the resource ('between entities in the knowledge graph'), and distinguishes from siblings by focusing on relationships rather than nodes, projects, or other operations. It provides concrete examples of relationship types like 'AUTHORED' and 'COVERS'.

  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 provides when-to-use guidance by stating 'Use get_knowledge_schema first to see available relationship types.' This names a specific alternative tool (get_knowledge_schema) that should be used as a prerequisite, giving clear context for proper tool selection.

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

• get_knowledge_schemaA
  4.4/5.0
  Behavior4/5

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

  Annotations already indicate read-only, non-destructive, and idempotent behavior, which the description doesn't contradict. The description adds valuable context by specifying that this tool should be called first to understand available types and fields, which goes beyond annotations by explaining its preparatory role in the workflow. However, it doesn't mention potential rate limits or authentication needs, leaving some behavioral aspects uncovered.

  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 that are front-loaded with the core purpose and followed by actionable guidance. Every word earns its place—there's 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.

  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 (schema retrieval with parameters) and lack of output schema, the description does well by emphasizing its preparatory role. However, it doesn't detail what the schema output looks like (e.g., structure or format), which could be helpful since there's no output schema. The annotations cover safety aspects, but more context on return values would enhance completeness.

  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%, with one parameter ('project_code') well-described in the schema. The description doesn't add any parameter-specific information beyond what the schema provides, such as explaining the 'environment' enum choices or how 'project_code' relates to sibling tools. Since schema coverage is moderate, the description doesn't fully compensate, resulting in a baseline score.

  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 ('Get') and resource ('full schema — entity types with fields, relationship types with from/to mappings'), making the purpose specific. It distinguishes from siblings by explicitly mentioning it should be called 'before adding nodes or relationships,' which differentiates it from tools like 'add_knowledge_nodes' or 'search_knowledge_graph' that operate on the schema itself.

  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: 'CALL THIS FIRST before adding nodes or relationships to understand what types and fields are available.' This clearly indicates its role as a prerequisite for other operations, distinguishing it from alternatives like 'get_knowledge_entity' or 'list_knowledge_entities' that work with existing data.

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

• ingest_text_contentA
  4.5/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond annotations: it explains the tool's role in a multi-step workflow, mentions the 500k character limit (implied from input schema but emphasized), and describes the output ('schema + instructions'). Annotations already cover safety (readOnlyHint=true, destructiveHint=false), so the description appropriately focuses on operational behavior without contradiction.

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

  Conciseness5/5

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

  The description is well-structured and front-loaded: it starts with the core purpose, then details the workflow, and ends with key benefits. Every sentence adds value—no fluff or repetition. The bullet-point workflow enhances readability without wasting space.

  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 (multi-step workflow) and rich annotations (covering safety and idempotency), the description is complete: it explains the tool's role, workflow, alternatives, and constraints. Although there's no output schema, the description specifies the return ('schema + instructions'), which is sufficient for an agent to proceed 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 thoroughly. The description adds minimal parameter-specific information beyond the schema (e.g., 'large block of text' aligns with text_content). It does not provide additional syntax, format, or constraints, so it 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 tool's purpose: 'BATCH INGESTION — the fast way to populate a knowledge graph.' It specifies the verb ('ingest'), resource ('text content'), and scope ('batch' vs 'per-entity'), distinguishing it from sibling tools like add_knowledge_nodes which handles only nodes. The description explicitly contrasts with 'per-entity approach,' making the distinction clear.

  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 guidance: it outlines a '3-CALL WORKFLOW' with named alternatives (add_knowledge_nodes, add_knowledge_relationships), specifies when to use this tool ('BATCH INGESTION — the fast way'), and when not to use it ('replaces per-entity approach'). It clearly defines the context for invoking this tool first in a sequence.

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