Server Quality Checklist

Tool Scores

• close_issueA
  3.8/5.0
  Behavior2/5

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

  No annotations are present, so the description must carry the full burden of behavioral disclosure. It mentions requiring the issue number but does not address authentication, side effects beyond closing, or the response format. For a mutation tool, this is insufficient.

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

  Conciseness5/5

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

  Three concise sentences, each serving a distinct purpose: stating the action, giving usage guidance, and highlighting a requirement. No redundancy or unnecessary detail.

  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-action tool, the description covers purpose, usage, and the critical input. The schema fully documents parameters. Minor gaps exist regarding output or error behavior, but they are not critical given the tool's simplicity.

  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 coverage is 100% with each parameter having a description. The tool description adds that the issue number is required, but this is already evident from the schema's required list. No additional semantic meaning is provided 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 clearly states a specific action ('Cierra un issue abierto en un repositorio de GitHub') and distinguishes it from sibling tools like create_issue or list_issues. The verb and resource are both explicit.

  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?

  It provides explicit usage guidance: 'Usa este tool cuando el usuario pida cerrar, resolver o finalizar un issue específico.' This clearly indicates when to use the tool, though it does not mention exclusions or alternatives.

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

• create_commitA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It reveals that the tool creates or updates a file and creates a commit, which is useful, but it does not disclose side effects like overwriting existing content, the default branch behavior, or any authentication requirements.

  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 well-organized sentences: first stating the purpose, then listing usage triggers, and finally summarizing the key inputs. It is front-loaded and contains no 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?

  The description effectively conveys the core function and provides explicit usage guidance, which is sufficient for an agent to select this tool. However, it omits some behavioral nuances like branch handling and return values (no output schema exists), so it is not 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?

  The input schema provides full descriptions for all 6 parameters, achieving 100% coverage. The description only summarizes a subset (path, content, message) and adds no extra semantic details beyond what the schema already provides, so the baseline of 3 applies.

  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 that the tool creates or updates a file in a GitHub repository and generates a commit with a given message. The verb+resource (create/update file -> commit) is explicit, and the tool is distinct from siblings like create_repository or create_issue, which target different actions.

  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 explicitly lists trigger phrases for when to use the tool ('commitear', 'guardar cambios', 'agregar un archivo', 'modificar un archivo'), providing clear context. However, it does not mention when not to use it nor explicitly name alternative tools for exclusions, so it falls just 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.

• create_issueA
  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 burden of disclosing behavior. It does state that the tool returns the issue number and URL, which is useful. However, it does not mention authentication requirements, potential errors (e.g., invalid repo), or rate limits. This is adequate but lacks some context for a mutation 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 concise: three sentences covering purpose, when to use, required inputs, and return value. Every sentence earns its place with no redundant information or filler.

  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?

  Without an output schema, the description correctly explains the return value (number and URL). It also covers the core behavior, required parameters, and typical use cases. It does not mention error scenarios or edge cases, but for a simple create-issue tool, the description is sufficiently complete for an agent to understand its purpose and outcome.

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

  Parameters3/5

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

  The input schema already provides 100% coverage with detailed descriptions, patterns, and examples for all four parameters. The description adds little beyond stating that owner, repo, and title are required and body is optional, which is already implied by the schema. 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 identifies the tool as creating an issue in a specific GitHub repository using the specific verbs 'Abre un issue' (open/create an issue). It distinguishes from siblings like close_issue, create_pull_request, and create_repository by focusing solely on issue creation.

  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 explicitly states when to use the tool: when the user wants to report a problem, suggest a task, or open an issue. However, it does not mention when not to use it (e.g., for closing issues) nor does it explicitly name alternatives, so it falls short of a perfect score.

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

• create_pull_requestA
  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 carries the full burden. It states that the tool creates a pull request and mentions required parameters, but it does not disclose behavioral traits like side effects (e.g., triggering CI), permissions needed, or that the branches must exist. This is adequate but not rich.

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

  Conciseness5/5

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

  Two sentences: the first states the core purpose, the second gives usage triggers and required parameters. Fully front-loaded, zero wasted words, and structured for quick parsing.

  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 covers the essential context: what it does, when to use it, and the core required inputs. It omits return value and error behavior, but given the simplicity of the operation and the rich schema, it is reasonably 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 baseline is 3. The description adds minor value by grouping head and base as 'rama origen' and 'rama destino', but it does not provide meaning beyond the schema's already-complete field descriptions.

  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 opens with 'Abre un pull request' (opens a pull request), specifying the verb, resource (pull request), and scope (between two branches in a GitHub repo). This distinguishes it from sibling tools like create_issue or create_commit.

  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 explicitly lists user intents that should trigger this tool ('hacer un PR', 'crear un pull request', 'fusionar cambios de una rama a otra'), which is clear when-to-use guidance. However, it does not mention when not to use it or name alternative tools for exclusion, stopping short of full 5.

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

• list_commitsA
  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 disclose behavior. It mentions the return fields and 'recent' commits, but does not explicitly state read-only nature, pagination behavior, or auth requirements. Adequate but with gaps in depth.

  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: first describes the action, second gives usage triggers, third describes return values. Each sentence earns its place, front-loaded with the primary purpose, no fluff.

  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 list tool with 3 parameters and no output schema, the description covers what it returns and when to use it. It lacks explicit pagination detail and read-only confirmation, but the schema's perPage parameter and sibling context fill some gaps. Overall sufficiently 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 each parameter is already well-documented (owner, repo, perPage). The description does not add extra parameter semantics beyond returning fields, which are not parameters. 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 states the tool lists recent commits from a GitHub repository, with a specific verb 'Lista' and resource, and even specifies returned fields (sha, mensaje, autor, fecha). This clearly distinguishes it from sibling tools like list_repositories and list_issues.

  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 explicitly gives use cases: when the user asks 'what commits are there', wants to see history, or latest modifications. It does not mention exclusions or alternatives, but the guidance is clear and contextually relevant.

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

• list_repositoriesA
  4/5.0
  Behavior3/5

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

  There are no annotations, so the description carries the burden of behavioral disclosure. It does disclose that the tool returns specific fields (name, visibility, description, URL) and implies authentication is required by stating 'authenticated user'. However, it does not explicitly mention that the operation is read-only, nor discuss rate limits or pagination behavior beyond what the schema already provides.

  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 that front-load the core function first, followed by usage examples and return fields. Every sentence adds value with no repetition or filler.

  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 list tool with no output schema, the description covers the purpose, when to use it, and return fields. It does not explicitly mention pagination or the distinction between public/private repos, but the schema covers pagination parameters, and the tool's simplicity means the description is largely sufficient. A brief note on pagination or authentication failure 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?

  The schema provides 100% coverage with detailed descriptions for both page and perPage, including defaults and bounds. The description adds no additional parameter semantics, so the baseline score of 3 applies.

  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 lists the authenticated user's GitHub repositories, using a specific verb ('Lista') and resource ('repositorios del usuario autenticado'). It also provides scope (authenticated user) and examples of user queries that should trigger this tool, effectively distinguishing it from sibling tools like list_issues or create_repository.

  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?

  It explicitly states when to use the tool: when the user asks 'what repositories do I have', wants to see their repo list, or enumerate their projects. However, it does not mention when not to use it or provide alternative tool names, so it lacks explicit exclusions.

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

• create_repositoryA
  4.2/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. It discloses that the operation occurs on the authenticated account, returns the name/URL/private status, and defaults to public if privacy is not specified. This covers key behavioral traits, though it lacks explicit error or idempotency details.

  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 and every sentence earns its place: purpose, usage trigger, return values, and default behavior. It is front-loaded with the core action and free of fluff.

  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 4 parameters, no output schema, and no annotations, the description provides essential context: action, usage, return values, and default privacy. Minor gaps such as not mentioning potential naming conflicts or authentication prerequisites are acceptable given the brief description.

  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 each parameter thoroughly. The description adds marginal value by reinforcing the default privacy behavior, but it does not introduce meaning beyond what the schema already provides, so the baseline of 3 applies.

  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 it creates a new repository in the authenticated GitHub account, using a specific verb and resource. It distinguishes from siblings like create_issue and create_pull_request, which target different resource types, and also notes return values.

  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?

  It explicitly says 'Usa este tool cuando el usuario pida crear, inicializar o agregar un repositorio nuevo', providing clear when-to-use guidance. It does not mention when-not-to-use or explicitly name alternative tools, but the when-to-use is strong enough to guide selection among siblings.

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

• list_issuesA
  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 burden of behavioral disclosure. It states what the tool returns (number, title, state, and URL of each issue), which is useful because there is no output schema. It does not mention potential side effects, but as a read-only listing tool, the absence is acceptable.

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

  Conciseness5/5

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

  The description is concise, consisting of three sentences that each serve a distinct purpose: stating the action, providing usage guidance, and listing return fields. There is no fluff or 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 tool's simplicity and the fully documented schema, the description is complete enough. It covers what the tool does, when to use it, and what it returns. It does not explicitly mention pagination or default state, but these are covered in the schema, so the description is adequate.

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

  Parameters3/5

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

  The input schema has 100% coverage with each parameter described. The tool description does not add extra parameter-level detail beyond the schema; it only mentions the state filter, which is already in the schema. Baseline of 3 is appropriate since 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 that the tool lists issues from a GitHub repository and filters by state (open, closed, all). It uses a specific verb ('Lista') and resource ('issues de un repositorio de GitHub'), and distinguishes itself from sibling tools like create_issue and close_issue by focusing on 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 explicitly provides a usage trigger: 'Usa este tool cuando el usuario pregunte "qué issues hay"'. This gives clear when-to-use guidance, though it does not mention when not to use it or alternative tools explicitly. It is still strong for practical use.

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