Server Quality Checklist

Tool Scores

• run_generatorA
  3.9/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral disclosure burden. It explicitly states that validation is not automatic, that generated artifacts are not committed, and that outputs are returned inline or via a temporary path. These are meaningful, non-obvious behavioral traits. It could add details about path lifetime or error behavior, but it already goes well beyond a generic description.

  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 sentences with no filler. The first sentence states the core action, the second covers side-effect exclusions, and the third covers return behavior. Every sentence earns its place and the structure is easily scannable.

  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 output schema and no annotations, the description covers the main action and key behavioral boundaries, but it leaves gaps around how long the temporary path remains valid, how to retrieve or consume its contents, and how to discover valid generator-specific options. These details matter for fully correct invocation, especially since options is an open-ended nested object.

  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 approximately 80%, so the schema already documents commit_id, generator, workspace_id, path, and options semantics. The description reinforces that generation happens against a specific commit and that only supported generators can be used, but it does not add substantial new parameter-level meaning beyond what the schema provides.

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

  Purpose5/5

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

  The description opens with a specific verb and resource: 'Run a supported LinkML generator against a schema file at a specific commit.' This clearly identifies the action, the target, and the scope, and distinguishes it from sibling tools like list_generators and describe_generator, which only inspect generators rather than executing them.

  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 intended use is implied by the purpose and by the statement that it 'Does not validate automatically,' but the description never names alternatives or explicitly states when to choose this tool over validate_schema or describe_generator. An agent must infer routing from sibling names and context rather than being given direct guidance.

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

• validate_schemaA
  3.9/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the behavioral disclosure burden. It does disclose the important side-effect boundary ('does not create a commit'), which helps an agent understand this is non-mutating. However, it does not describe what the validation response contains, such as whether it returns errors, a pass/fail status, or a report, which is especially relevant since no output schema 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 two short sentences with no filler. The core purpose and target resource are front-loaded, and the second sentence adds an important behavioral clarification. Every word contributes meaning.

  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 three simple parameters and no output schema, the description is reasonably complete, but it leaves the return behavior implicit. It also does not mention when in a workflow validation is expected, such as before running a generator or applying a changeset. Given the absence of annotations and an output schema, a bit more detail about expected results would make it fully complete.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the parameters are already well documented by the schema. The description adds minimal semantics beyond restating that validation happens at a specific commit, which maps to commit_id and workspace_id. It does not add new meaning for the path parameter, but the schema already covers that, so a baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description uses a specific verb ('Validate') and a precise resource ('LinkML YAML schema at a specific workspace commit'). It also clarifies that this is validation-only, which distinguishes it from sibling tools like apply_changeset that would mutate state or create commits. This is immediately clear to an agent selecting among the listed 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 gives clear context: the tool validates a schema at a given commit and explicitly states it does not create a commit. This communicates a key exclusion relative to commit-creating operations. However, it does not explicitly state when to prefer this over siblings like read_schema or apply_changeset, nor does it name alternatives, so it stops short of a 5.

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

• describe_generatorA
  4/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full behavioral disclosure burden. It adds useful detail about option format ('CLI-style option names without leading dashes') and 'describe' implies a read-only operation, but it does not explain what output the tool returns or whether unsupported names produce errors. This is adequate for a simple lookup tool but not rich.

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

  Conciseness5/5

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

  Two concise sentences with no filler. The core purpose is stated first, and the additional option-format nuance is included without bloat. Every sentence contributes useful 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?

  This is a simple tool with one enum-constrained parameter and no output schema, so the description is nearly complete. It covers the tool's purpose and the key behavioral detail about option formatting. It could mention that list_generators is the way to enumerate supported generators, but that is a minor omission.

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

  Parameters3/5

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

  Schema description coverage is 0%, and the description does not explicitly explain that 'name' selects the generator, though 'Describe one supported LinkML generator' implies it. The enum values (shacl, owl, doc) are self-explanatory, but the description does not add meaning beyond the schema for the parameter itself.

  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 states a specific verb ('Describe') and resource ('one supported LinkML generator'), and clarifies it covers the option format accepted by run_generator. This clearly distinguishes it from sibling tools like list_generators (which enumerates) and run_generator (which executes).

  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 this tool should be used to inspect a specific generator or learn its option format before invoking run_generator. It does not explicitly mention when to use list_generators instead, but the phrase 'one supported generator' plus sibling context makes the usage scenario reasonably clear.

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

• get_entityA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. 'Fetch' conveys a read-only operation, and 'at a specific commit' discloses that the lookup is version-pinned. The required entity_type domain is also stated, though error behavior and return format are not addressed.

  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 compact sentences with no filler. The action and resource are front-loaded, and the entity_type constraint is cleanly separated for readability.

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

  Completeness4/5

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

  For a simple single-entity fetch tool, the description plus schema provides enough practical detail: what to fetch, from where, and under which constraints. The main omissions are a direct pointer to read_schema for full-file needs and any hint about the output, but neither is critical for correct invocation at this complexity level.

  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 80%, so the schema already documents most parameters. The description only repeats the entity_type enum values, adding little semantic value beyond what the input 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 uses a specific verb ('Fetch') with a precise resource ('one LinkML entity from a schema file at a specific commit'). It also enumerates exactly which entity types are allowed, clearly distinguishing it from file-level tools like read_schema or list_files.

  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: use this when you need a single entity at a pinned commit. However, it never explicitly contrasts it with siblings such as read_schema for whole-schema reads or validate_schema for validation, leaving the decision to inference.

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

• list_filesA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description must carry the behavioral disclosure burden. It clearly communicates a read-only enumeration scoped to a specific commit, which is useful, but it omits details such as return format, whether listing is recursive, or behavior on invalid commit IDs. This leaves some behavioral ambiguity for the agent.

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

  Conciseness5/5

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

  Two sentences with no filler. The core action is front-loaded in the first sentence, and the second sentence adds actionable usage guidance. Every element earns its place.

  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 low-complexity list tool with two clearly documented parameters, the description covers what it does and when to use it. The main gap is the absence of any statement about output format (e.g., file names vs. paths), which would make interpreting the result slightly less certain.

  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 both workspace_id and commit_id are already fully documented in the schema. The description reinforces the 'specific commit' scoping but adds no new parameter-level detail beyond what the schema provides, so the 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 uses a specific verb 'List' with a clearly defined resource: 'files present in a LinkML workspace at a specific commit.' This distinguishes it from sibling tools like read_schema, and the additional note 'Use this before targeting imported local schema files' 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 sentence 'Use this before targeting imported local schema files' provides a concrete, actionable scenario for when to invoke this tool. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of fully explicit routing.

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

• list_generatorsA
  4/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the behavioral disclosure burden. It clearly indicates this is a read-style enumeration operation and adds the useful detail about milestone generators, but it does not describe the output format, whether the list is exhaustive, or any other behavioral specifics. This is acceptable but not rich.

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

  Conciseness5/5

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

  Two short sentences with no filler. The primary action and resource appear first, and the milestone examples add useful context without 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 zero-parameter list tool with no output schema, the description is largely sufficient. It could be more explicit about the return format, but the provided information, combined with the sibling tool context, is enough for an agent to invoke it correctly.

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

  Parameters4/5

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

  The tool has zero parameters and the schema is an empty object, so parameter-level guidance is not needed. The baseline for zero-parameter tools is 4, and the description appropriately adds no irrelevant parameter information.

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

  Purpose5/5

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

  The description uses a specific verb ('List') with a clear resource ('the LinkML generators supported by this MCP server'), and it names milestone examples ('shacl, owl, and doc'). This makes the tool's purpose immediately apparent and distinguishes it from siblings like describe_generator and run_generator.

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

  Usage Guidelines3/5

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

  The description implies the tool should be used when an agent needs to discover available LinkML generators before using describe_generator or run_generator. However, it does not explicitly state when to use it versus alternatives or when not to use it, leaving the guidance implicit.

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

• read_schemaA
  4.1/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 behavioral burden. The verb 'Read' clearly indicates a non-mutating operation, and 'from a specific workspace commit' adds important scoping context. It does not describe error behavior, but for a simple read tool this is adequate.

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

  Conciseness5/5

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

  Two concise sentences with no filler. The primary action and target are front-loaded in the first sentence, and the second sentence adds a useful clarifying detail about path usage.

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

  Completeness3/5

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

  The tool is simple and parameters are well-documented, but because there is no output schema, the description should ideally clarify what the tool returns (e.g., raw YAML content, parsed schema object). The description implies reading but leaves the return contract implicit.

  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?

  All three parameters already have schema descriptions, so the baseline is 3. The description adds mild value by explaining that 'path' can point to schema.yaml or another local imported YAML file, but it does not substantially enhance meaning beyond the schema.

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

  Purpose5/5

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

  The description states a specific verb ('Read'), a clear resource ('LinkML YAML schema file'), and a precise location ('from a specific workspace commit'). It distinguishes the tool from siblings like validate_schema and get_entity by framing it as a file-content read operation rather than validation or entity access.

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

  Usage Guidelines4/5

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

  The description gives clear context: this tool is for reading schema.yaml or another local imported YAML file at a specific commit. It implicitly tells the agent when to choose this over list_files or validate_schema, though it does not explicitly name exclusions or alternatives.

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

• init_workspaceA
  4.2/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 states the creation side effect (new workspace backed by a bare git repository), the return values, and the fallback behavior when files are omitted. It does not go into failure modes or conflict handling, but it covers the key operational behavior for a creation tool.

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

  Conciseness5/5

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

  The description is two sentences with no wasted words. It front-loads the core action and resource, then provides return values and a conditional behavior. Every sentence earns its place.

  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 creation tool with four optional parameters and no output schema, the description provides the essential return values and the default behavior for omitted files. It is complete enough for an agent to invoke correctly, though details about where the workspace is created or what happens on conflicts are not mentioned.

  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 four parameters. The description adds a small amount of context beyond the schema by noting that omitting files creates a minimal schema.yaml, but other parameter semantics are already well covered by the input 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 a specific verb ('Create'), resource ('new LinkML editing workspace'), and implementation detail ('backed by a bare git repository'). It also names the return values (workspace_id and initial_commit), making it easy to distinguish from sibling tools that operate on an existing workspace.

  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 clearly positions this as the workspace creation tool, and mentioning that it returns workspace_id implies it is a prerequisite for the other sibling tools that require an existing workspace. However, it does not explicitly state when to use it instead of alternatives or when not to use it.

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

• apply_changesetA
  4.4/5.0
  Behavior4/5

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

  With no annotations present, the description carries the full burden of disclosing behavior. It does well by mentioning atomicity, ordering, validation before and after, the base_commit requirement, and the return of a new commit id. It stops short of describing failure behavior, rollback, or permission requirements, but the disclosed traits are substantial and not contradicted by any annotation.

  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 three sentences with no filler. The main purpose is front-loaded, the critical requirement (base_commit) and core behaviors (validation, return value) are in the second sentence, and the third sentence enumerates supported operations compactly. Every sentence earns its place.

  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 complex mutation tool, the description provides a strong high-level picture: atomic ordered application, validation, commit id return, and the set of supported operations. It does not detail the exact parameters required for each operation type or the response structure beyond a commit id, but the input schema fills most of the gaps. A bit more on error/failure behavior would make it fully complete.

  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 covers all 4 parameters at 100%, so the baseline is 3. The description adds meaningful value by expanding the operation vocabulary (create/delete/rename class, slot, enum, prefix, import, file, plus set_field, unset_field, list_append, list_remove, list_replace, map_set, map_remove) and by clarifying that the changes array is ordered and applied atomically. This goes beyond the schema's single example.

  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 begins with a specific verb and resource: 'Apply an atomic ordered semantic changeset to a LinkML workspace.' It clearly distinguishes this tool from the sibling read/init/generate tools by positioning it as the mutation/commit operation, and even enumerates the supported operation families.

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

  Usage Guidelines4/5

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

  The description gives clear context: it requires base_commit, applies changes atomically, and validates before/after. It does not explicitly name alternatives or when-not to use it, but among the sibling tools there is no other changeset-apply tool, so the intended usage is unambiguous.

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