Server Quality Checklist

Tool Scores

• list_documentsB
  3.4/5.0
  Behavior4/5

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

  Beyond the readOnlyHint annotation, the description adds meaningful context about the `duplicate_file_names` output flag, explaining its cause (interrupted save) and the cleanup path (write_document with overwrite=true). This helps the agent interpret results and plan next steps, though it does not fully disclose all output 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 sentences, front-loaded with the core purpose, and includes additional relevant detail without redundancy. Every sentence contributes value, making it appropriately concise.

  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 there is no output schema, the description should explain return values more fully. It mentions one specific output field (`duplicate_file_names`) but does not describe the overall response structure or document fields. The tool is simple, so the current description is barely adequate but leaves gaps.

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

  Parameters1/5

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

  The schema has 0% description coverage, and the tool description does not add any detail about the `project_id` parameter—its format, meaning, or how to obtain it. The phrase 'in a project' is the only hint, leaving the agent without sufficient semantic grounding for the sole required parameter.

  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 action and resource: 'List the documents in a project.' It uses a specific verb and identifies what is being listed, which distinguishes it from siblings like read_document (single document) and project-level tools.

  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 does not explicitly state when to use this tool versus alternatives. There is no mention of 'use this to list all documents' or when to prefer it over read_document or list_projects. The reference to write_document is about cleanup behavior, not about when to invoke this tool.

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

• list_projectsA
  3.6/5.0
  Behavior3/5

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

  The readOnlyHint annotation already signals a safe read operation. The description adds modest behavioral context by noting projects are tagged with their owning organization and scoped to 'this account,' but it does not disclose other traits like pagination, response format, or permission requirements. This is acceptable given the annotation, 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?

  The description is exactly two sentences, with the verb and resource front-loaded in the first sentence and the use case in the second. Every word earns its place; there is no fluff or repetition of the tool name or schema.

  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 with one optional parameter and no output schema, yet the description still leaves the organization_id parameter ambiguous. The core purpose and use case are clear, but the missing parameter semantics and lack of output format details mean the description is not fully complete for an agent to use it confidently in all scenarios.

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

  Parameters1/5

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

  The schema has one optional parameter, organization_id, with 0% schema description coverage. The description fails to explain the meaning or effect of this parameter, such as whether it filters projects by organization or retrieves all projects when null. This is a significant gap since the description was the only place to clarify the parameter's semantics.

  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 ('projects') and scope ('on this account'), and further specifies the output includes the owning organization. It clearly distinguishes from siblings like get_project and list_documents, and states the intended purpose ('find a project uuid').

  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 a clear use case: 'Use this to find a project uuid.' This establishes when to use the tool, but it does not explicitly mention when not to use it or call out alternatives like get_project once the uuid is known. Still, the context is clear enough for an agent.

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

• create_projectA
  3.9/5.0
  Behavior4/5

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

  Annotations only include destructiveHint=false, so the description adds value by explaining when organization_id is required and the error behavior, plus the visibility semantics of private vs normal projects. It does not contradict 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, front-loaded with the main verb, and each sentence adds distinct contextual information without redundancy.

  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 description covers key creation nuances (org_id and privacy) but omits expected behavior like return value, permission requirements, or the purpose of the 'instructions' parameter. Given the sparse schema and annotations, it is functional but not fully comprehensive.

  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 0% schema description coverage, the description compensates for organization_id (needed only in multi-org accounts) and is_private (visibility), but it provides no explanation for name, description, or instructions, leaving some parameters without added meaning.

  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 starts with 'Create a project,' a specific verb+resource that clearly distinguishes it from sibling tools like update_project or delete_project. It adds context about organization_id and project visibility, reinforcing its purpose.

  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 use for creating a new project and provides situational guidance for organization_id and is_private, but it does not explicitly mention when to use this tool over alternatives like update_project or list_projects.

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

• pull_documentsA
  3.9/5.0
  Behavior4/5

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

  The description discloses a non-obvious behavior: local files that differ are kept and not overwritten unless overwrite_local=true. This adds valuable context beyond the readOnlyHint=false annotation, though it does not cover other aspects like permissions or error handling.

  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 primary action, and includes only necessary behavioral detail. Every word earns its place.

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

  Completeness3/5

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

  While the core action and overwrite behavior are covered, the description does not mention return values, preconditions (e.g., destination directory must exist), or error scenarios. Given the lack of an output schema, these omissions leave the tool's full behavior incompletely specified.

  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 0% schema description coverage, the description compensates by explaining overwrite_local's effect. Project_id and destination_directory are only implicitly defined through the overall action, and the schema titles already make their roles clear. The description adds no further detail on formats or constraints.

  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 'Copy' and resource 'project's documents' into a local folder, clearly distinguishing pull_documents from siblings like push_documents and read_document. It states the direction and scope of the operation.

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

  Usage Guidelines3/5

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

  The description implies usage by stating the action, but does not explicitly mention when to use it over alternatives like read_document for single files or push_documents for the reverse operation. No exclusions or alternative tools are referenced.

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

• read_documentA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds valuable behavioral context: the newest document wins on name collisions and a warning lists the other matches. This goes beyond the annotation without contradicting it.

  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, front-loaded with the primary action. The second sentence addresses an important edge case without unnecessary detail. 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?

  The description covers the core behavior and the name-collision edge case, which is useful given there is no output schema. It does not describe the return format or other side effects, but for a simple read operation with good annotations, this 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?

  With schema description coverage at 0%, the description is responsible for explaining parameters. It clarifies that 'document' can be a file name or a UUID, but it does not explain 'project_id' at all. The description partially compensates for the missing schema documentation but leaves a key parameter undefined.

  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 ('Read') and resource ('one document'), clearly stating that it retrieves a single document by file name or UUID. This distinguishes it from sibling tools like list_documents (which lists) and write_document (which writes).

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

  Usage Guidelines3/5

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

  The description implies usage context by explaining how to identify a document (by name or uuid) and the ambiguity resolution rule, but it does not explicitly state when to prefer this tool over siblings or exclusions. No alternatives are named, so the guidance is only implied.

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

• rename_documentA
  4.2/5.0
  Behavior5/5

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

  The description goes well beyond the destructiveHint annotation by detailing the rename mechanism: content is re-created under the new name before deletion, local backups are made first, and overwrite is refused unless explicitly requested (with backup for the replaced holder). This provides a transparent view of the tool's effects and safety properties, aligning with the annotation's non-destructive intent.

  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 and each sentence adds meaningful detail: the first defines the action and identifier, the second explains the safe rename execution, and the third addresses collision handling. No redundant or extraneous information is present.

  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 tool has four parameters and no output schema, but the description covers the core semantics for document, overwrite, and new_file_name, leaving only project_id as assumed context. The rename behavior, including backups and overwrite refusal, is fully disclosed, making the tool well-specified for an agent.

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

  Parameters4/5

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

  With zero schema description coverage, the description supplies essential parameter context. It explains that 'document' can be a uuid or unambiguous filename, clarifies the semantics of 'overwrite' (refused by default, replaces existing holder when true), and implicitly defines 'new_file_name' as the target name. Only 'project_id' remains unelaborated, but it is a common context parameter.

  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 immediately states the tool's core action—'Rename a document'—and clarifies the acceptable identifier forms ('by uuid or by an unambiguous file name'). This cleanly distinguishes it from sibling tools like read_document or delete_document, which serve different purposes.

  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 is given about when to use this tool over alternatives. There is no mention of when not to use it (e.g., use write_document to edit content rather than rename), nor any reference to alternative tools. The description does explain the overwrite behavior but that is a parameter constraint, not a usage directive.

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

• get_projectA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, so the description does not need to restate safety. It adds that the tool returns name, description, and instructions, and that instructions are unique to this tool. While it does not mention permissions or error handling, for a read-only tool with readOnlyHint this is adequate context beyond the 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 two sentences with no filler, front-loading the core action ('Read one project') and then adding a crucial distinguishing detail. 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 simple read tool with one parameter and a readOnlyHint annotation, the description covers the purpose, the returned content (name, description, instructions), and a key differentiation from list_projects. No output schema exists, but the description adequately communicates what is returned. A minor gap is the lack of error-case mention, but the core context is sufficient.

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

  Parameters2/5

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

  The schema has one parameter project_id with 0% description coverage. The tool description does not mention project_id at all, nor does it clarify how to identify the project. Given the low schema coverage, the description needed to compensate but did not, relying on the parameter name alone.

  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 the specific verb 'Read' with the resource 'one project' and explicitly differentiates itself from the sibling tool list_projects by noting that it is the only tool that returns instructions. This clearly states what the tool does and why it is distinct.

  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 an alternative and a condition for use: 'Only this tool returns the instructions — list_projects does not carry them.' This directly tells the agent when to choose this tool over a sibling, and implies when not to use it (for listing without instructions).

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

• delete_documentA
  4.4/5.0
  Behavior5/5

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

  Beyond the destructiveHint annotation, the description discloses that content is backed up locally first and that ambiguous names are refused, adding safety and error-condition context.

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

  Conciseness5/5

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

  Three concise sentences with no redundant information; each sentence adds a distinct piece of information (action/identifiers, backup, ambiguity handling).

  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?

  Covers the action, identification methods, backup behavior, and ambiguity handling, but omits any explanation of the project_id parameter and does not describe success/error returns. Adequate for a simple tool but 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 description explains that the 'document' parameter can be a uuid or unambiguous file name, but it does not explain the 'project_id' parameter at all. With 0% schema coverage, this leaves a gap for one of the two required 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 action (Delete a document) and the resource (document), with additional specificity about the two identifiers (uuid or unambiguous file name). This distinguishes it from sibling tools like delete_project and other document operations.

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

  Usage Guidelines4/5

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

  The description provides explicit guidance on when to use uuid versus file name based on ambiguity, and notes the refusal behavior. It does not explicitly compare with alternative tools or state when not to use this tool, but it gives clear context for invocation.

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

• push_documentsA
  4.4/5.0
  Behavior5/5

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

  Beyond the annotation destructiveHint=false, the description reveals key behaviors: skip unchanged files, overwrite requirement, no deletion of remote documents, and dry-run preview. This adds substantial context about side effects and safety, going well beyond the annotation's minimal information.

  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, front-loaded with the main action, followed by concise behavioral details and a usage tip. Every sentence adds value with no redundancy or 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?

  The description covers the core upload behavior, skip logic, overwrite requirement, no-deletion guarantee, and dry-run option, which are essential for safe usage. It omits details about the pattern parameter (default '*.md') and expected return behavior, but given the presence of a schema and no output schema, the description is reasonably complete for a bulk upload tool.

  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 0% schema description coverage, the description compensates for dry_run and overwrite by explaining their purpose (preview and overwriting differing files). However, pattern, project_id, and source_directory are not explained in the description, relying on schema titles and defaults alone, so compensation is incomplete.

  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 'Upload a local folder's files into the project' clearly states a specific action (upload), resource (local folder files), and destination (project). It distinguishes from siblings like pull_documents (reverse operation) and write_document (single-file write), making the tool's purpose unambiguous.

  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 operational context: unchanged files are skipped, overwrite=true is needed for differing files, and remote deletions are not propagated, plus dry_run=true for preview. However, it does not explicitly name alternatives or state when not to use this tool, though the sibling list implies bulk vs. single operations.

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

• update_projectA
  4.4/5.0
  Behavior4/5

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

  Annotations provide destructiveHint=false, indicating non-destructive behavior. The description adds meaningful behavioral detail beyond this: partial updates and the ability to clear fields with an empty string. It does not mention permissions, return values, or error handling, but the mutation semantics are clearly disclosed.

  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 deliver all essential information with no filler. The first sentence front-loads the core purpose, and the second provides critical partial-update/clearing behavior. Every clause 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?

  The tool has no output schema, but the description covers the main contextual needs: what fields can be changed, that updates are partial, and how to clear values. It omits return value/error behavior, but given the low complexity and the presence of destructiveHint=false annotation, the description is largely complete. A more explicit mention of whether an updated project object or just a status is returned would push it to a 5.

  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% schema description coverage, the description compensates by naming the three updatable fields (name, description, instructions) and clarifying their semantics: only passed fields are changed, and empty strings clear values. The required project_id is not described, but its role is implied by the tool name and schema, and the field-level semantics for the others are well explained.

  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 action verb and resource: 'Change a project's name, description, or instructions.' It clearly distinguishes update_project from sibling CRUD tools like create_project, get_project, and delete_project by naming the exact mutable fields.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use the tool: updating existing projects, with a partial-update semantic ('Only the fields you pass are touched'). It does not explicitly name alternatives or state when not to use it, but the sibling tool names and 'change' verb make the use case obvious.

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

• delete_projectA
  4.5/5.0
  Behavior5/5

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

  Beyond the destructiveHint annotation, the description discloses the backup process (documents copied locally), the failure safety (nothing deleted if backup fails), and the irreversible nature (no undo). This enriches the behavioral model significantly.

  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 well-structured sentences front-load the main action, present a safety warning, and detail the backup mechanism. Every clause serves a purpose without redundancy.

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

  Completeness5/5

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

  For a destructive tool with two parameters and no output schema, the description covers the deletion scope, undo limitation, required confirmation, pre-deletion backup, and failure behavior. It is fully self-contained and explains all critical aspects a user needs to know before invoking.

  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 covers 0% of parameter semantics, and the description explains confirm_name (must match exact current project name), but project_id is only implied by the tool name. It adds some value but does not fully compensate for the lack of schema descriptions for both 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 action (delete) and the resource (a project and every document in it), which distinguishes it from sibling tools like delete_document. The scope is explicit and specific.

  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 a critical usage condition: confirm_name must be set to the exact current name. It also notes the absence of server-side undo, warning the user when to be cautious. It does not explicitly name alternatives, but the destructive context is clear.

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

• write_documentA
  4.6/5.0
  Behavior5/5

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

  The description goes beyond the minimal destructiveHint annotation by revealing two important behaviors: the previous content is backed up locally before any replacement, and the write can be refused if expected_uuid doesn't match (optimistic concurrency). These are not disclosed in annotations or schema, so the description carries the burden and does so thoroughly.

  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, each serving a distinct purpose: core action, safety mechanism, and concurrency control. No wasted words, and the most important information is front-loaded.

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

  Completeness4/5

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

  The tool has 5 parameters, no output schema, and a single annotation. The description explains the primary write/replace behavior, the backup guarantee, and concurrency protection, which covers the main risks and usage context. It does not describe return values or distinguish from batch tools like push_documents, but for a single-document write tool, the coverage is strong.

  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% schema description coverage, the description must explain parameters. It explicitly clarifies 'overwrite=true' for replacement and explains the purpose of 'expected_uuid' (from read_document) to prevent overwriting teammate changes. The remaining parameters (project_id, file_name, content) are left to inference from their names, but the non-obvious semantics are well covered.

  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 and resource: 'Create a document, or replace one with overwrite=true.' This distinguishes it from siblings like read_document and delete_document by specifying creation and replacement behavior.

  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: create a new document or replace an existing one, with overwrite=true for replacement. It also mentions using expected_uuid from read_document for concurrency checks, directly tying to a sibling. It does not explicitly state when not to use it, but the context is strongly implied.

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