Server Quality Checklist

Tool Scores

• contentrain_bulkB
  3.1/5.0
  Behavior3/5

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

  The description adds 'All operations are auto-committed to git,' which is a behavioral trait beyond annotations. However, it does not disclose the destructive nature of delete_entries or that confirm=true is required for deletion, leaving gaps in behavioral understanding.

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

  Conciseness4/5

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

  The description is very concise with two sentences. It front-loads the core purpose, but could be slightly more informative without becoming verbose. Still, it avoids unnecessary detail.

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

  Completeness2/5

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

  The tool has 8 parameters and 3 operations with no output schema. The description lacks details on operation behaviors, expected outputs, error handling, or success/failure indicators, making it incomplete for an agent to use effectively.

  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 documentation coverage is high (88%), so the description adds minimal value for most parameters. The description does not elaborate on operation-specific parameter usage beyond the schema, meeting the baseline expectation.

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

  Purpose4/5

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

  The description clearly states 'Batch operations on content entries' and mentions auto-commit, giving a clear purpose. It distinguishes from sibling tools which handle single operations, though it doesn't explicitly list the three operations available.

  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 guidance is provided on when to use this tool versus individual content tools like contentrain_content_delete or contentrain_content_save. There is no mention of prerequisites or context where this tool is preferable.

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

• contentrain_scaffoldB
  3.2/5.0
  Behavior3/5

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

  Annotations provide minimal behavioral context (readOnlyHint false, destructiveHint false), so the description carries the burden. It adds the key fact that 'Changes are auto-committed to git,' which is a valuable disclosure. However, it does not explain whether existing files are overwritten, what git operations occur, or if the tool is safe to run repeatedly; this gap prevents a higher score.

  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, followed by a useful template list and a key behavioral note. Every sentence contributes value without redundancy.

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

  Completeness2/5

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

  This is a mutation tool (readOnlyHint false) with no output schema, so the description must explain outcomes and side effects. It fails to mention whether the tool is intended for fresh projects, whether it overwrites existing files, or what the resulting project structure looks like. The auto-commit note is helpful but insufficient for safe and correct invocation.

  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 covers all three parameters with descriptions, and schema coverage is 100%, so the description does not need to explain parameters. The description's template list duplicates the schema, adding no meaningful semantic value beyond what the schema already provides.

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

  Purpose4/5

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

  The description clearly states the tool's function as 'Template-based project setup' and enumerates the available templates (blog, landing, docs, etc.), which makes the purpose understandable. It distinguishes from siblings like contentrain_init by focusing on templates, though it doesn't explicitly contrast with other setup 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?

  No explicit guidance is provided on when to use this tool versus alternatives such as contentrain_init. The description implies usage for project scaffolding but lacks any context about prerequisites (e.g., empty directory, existing git repo) 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.

• contentrain_validateA
  3.6/5.0
  Behavior4/5

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

  Annotations provide readOnlyHint=false and idempotentHint=true. The description adds meaningful context: what auto-fix does (canonical sort, orphan meta, etc.), a warning not to manually edit .contentrain/ files, and that title_field backfills are reported with the choosing rule. No contradiction with annotations.

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

  Conciseness5/5

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

  Compact and well-structured. Three sentences, all information-bearing, front-loaded with purpose, then fix behavior, then safety warning. No redundant content.

  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 tool purpose, fix options, and a safety warning. However, it doesn't describe the output format of validation results (e.g., report structure, exit codes), which may be relevant for agents interpreting results. Minor gap, otherwise 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 schema already explains both 'fix' and 'model' parameters. The description restates the fix behavior but doesn't add new parameter-level details beyond the schema, earning the baseline score.

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

  Purpose4/5

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

  Clearly states it validates project content against model schemas and lists specific violation types (required fields, type mismatches, etc.). The verb+resource is specific, but it doesn't differentiate from sibling tools like contentrain_scan or contentrain_doctor.

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

  Usage Guidelines2/5

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

  No explicit guidance on when to use this tool versus alternatives like contentrain_apply or contentrain_doctor. The description implies a validation use case but doesn't provide context for selection or exclusion.

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

• contentrain_mergeA
  3.7/5.0
  Behavior1/5

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

  The description discloses destructive behavior ('prunes the merged branch'), but the annotations mark destructiveHint as false, creating a contradiction. Additionally, it does not mention side effects like data loss or the need for permissions beyond the contradiction.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the primary action, and each sentence adds essential detail without redundancy. No superfluous words.

  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 explains the merge process well but lacks mention of return values (since no output schema), prerequisites (e.g., being in a git repo), and error scenarios. For a 5-parameter tool with no output schema, more context on outcome is needed.

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

  Parameters4/5

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

  Schema description coverage is 100%, but the description adds value by explaining the resolution logic between 'branch' and 'model' parameters and emphasizing 'confirm' must be true. This provides clarity beyond the individual parameter 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 states the verb 'merge' and specific resource 'review-mode branch into contentrain' with a detailed breakdown of operations (merge, update-ref, sync, prune). It also distinguishes from sibling tools like contentrain_branch_delete and contentrain_submit by specifying it's a local git operation.

  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 explains when to use the tool (merging review-mode branches) and how to target branches either by exact name or by model with optional locale/latest. However, it does not explicitly state when not to use it or mention alternative tools like contentrain_submit.

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

• contentrain_model_saveA
  3.9/5.0
  Behavior4/5

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

  The description discloses a key behavioral trait beyond annotations: changes are auto-committed to git, and warns against manual edits after calling. While annotations already indicate this is a write operation (readOnlyHint=false), the git side effect is valuable additional context not captured by annotations.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the primary action, and every word serves a purpose. The critical git auto-commit warning is efficiently integrated 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 tool is complex with 10 parameters and nested objects, but the schema is very detailed, covering parameter semantics. The description lacks information about return values, validation behavior, or how create vs. update is determined, but the schema and annotations provide much context. Still, for a tool with no output schema and this complexity, a bit more behavioral context would improve completeness.

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

  Parameters3/5

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

  Schema documentation coverage is 100%, so the schema carries full parameter semantics. The description adds no additional parameter meaning, which is acceptable given the high schema coverage, but it does not enhance or clarify any parameter details.

  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 'Create or update a model definition' with a specific verb and resource. This distinguishes it from sibling tools like contentrain_model_delete and contentrain_content_save, which target different objects or operations.

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

  Usage Guidelines3/5

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

  The description implies usage (for creating/updating model definitions) and includes a post-action warning about not manually editing .contentrain/ files. However, it does not explicitly mention when to use this tool versus alternatives or state any exclusions, so it falls short of clear usage guidance.

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

• contentrain_initA
  4/5.0
  Behavior4/5

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

  The description adds a crucial behavioral warning that changes are auto-committed to git and that users should not manually create these files. This goes beyond the annotations, which only indicate non-read-only, non-destructive, and non-idempotent hints. It provides actionable context about side effects.

  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 extremely concise, with two short sentences that deliver the purpose and the key warning. Every word earns its place, 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?

  For a simple initialization tool with no output schema and no required parameters, the description covers the essential purpose and risk. It could mention what happens if already initialized or what the structure contains, but the current content is sufficient for basic use.

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

  Parameters3/5

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

  The input schema has full descriptions for all three parameters (stack, domains, locales), including defaults and auto-detection behavior. The tool description adds no additional parameter semantics, so the 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 clearly states the tool initializes a .contentrain/ structure, with a specific verb and resource. This distinguishes it from sibling tools like contentrain_validate or contentrain_scaffold, which have 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 Guidelines3/5

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

  It implies this is the setup step for a project but does not explicitly state when to use it versus alternatives. There is no mention of prerequisites, when not to use it, or references to sibling tools that could serve similar roles.

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

• contentrain_model_deleteA
  4/5.0
  Behavior4/5

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

  Annotations already declare destructiveHint=true, but the description adds valuable context: changes are auto-committed to git and manual editing of .contentrain/ files is discouraged. 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?

  The description is a single, front-loaded sentence that states the action and the key caveat. Every word earns its place; no redundant or filler content.

  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 destructive two-parameter tool with no output schema, the description adequately covers scope ('model and its content/meta') and the critical behavior (git auto-commit). The confirmation requirement is already in the schema. Slightly more detail on consequences (e.g., irreversibility) would round it out, but it's essentially 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 covers 100% of parameters with descriptions ('Model ID to delete', 'Must be true to confirm deletion'). The description adds no additional parameter-level detail, 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 uses a specific verb ('Delete') and resource ('a model and its content/meta'), making the tool's function unmistakable. It clearly distinguishes from siblings like contentrain_content_delete (content only) and contentrain_model_save (save/create).

  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 when to use by warning 'do NOT manually edit .contentrain/ files', suggesting this tool as the safe alternative to manual editing. However, it lacks explicit comparison to sibling tools or exclusion of contexts (e.g., when to use contentrain_content_delete instead).

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

• contentrain_scanA
  4.1/5.0
  Behavior4/5

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

  Annotations already indicate read-only and idempotent. Description adds 'Read-only — no changes to disk or git', 'MCP finds strings deterministically; the agent decides what is content', and explains mode behaviors, which are beyond annotation defaults.

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

  Conciseness4/5

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

  Single paragraph, front-loaded with purpose, efficiently covers modes, safety, determinism, and workflow. No fluff, but could be slightly more structured with bullet points for modes.

  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 purpose, modes, safety, and workflow for a complex tool (3 modes, 8 optional params). Lacks output format details, but modes are described sufficiently for agent to understand what each returns. No output schema, so description must compensate, and it does adequately.

  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 parameter descriptions. Description adds contextual grouping (e.g., 'limit' and 'offset' for candidates mode) and defaults, but does not significantly 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?

  Clearly states tool scans source code for content strings, lists three distinct modes ('graph', 'candidates', 'summary'), and is distinguished from sibling tools (e.g., contentrain_apply, contentrain_delete) which are write 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?

  Provides a recommended workflow: start with 'summary' or 'graph' then paginate 'candidates'. Explicitly notes read-only nature, helping agent decide when to use. No explicit exclusion of alternatives, but siblings are clearly different in purpose.

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

• contentrain_branch_deleteA
  4.2/5.0
  Behavior4/5

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

  Annotations already indicate destructiveHint=true, and the description reinforces the destructive nature by stating the branch and its unmerged commits are removed. It also adds the constraint that only cr/* branches can be deleted. No extra details on permissions or recovery, but given the annotations, this is sufficient.

  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 concise sentences, each serving a purpose: stating the action and examples, imposing a constraint, and noting destructiveness. No redundant or vague phrases. Efficient and well-structured.

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

  Completeness4/5

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

  For a tool with two simple parameters, no output schema, and annotations covering destructive nature, the description provides sufficient context: purpose, usage scenarios, constraints, and behavior. It could mention recovery impossibility or use cases like cleaning up, but the current content is mostly 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 coverage is 100% and both parameters have descriptions. The description adds minimal extra meaning: it contextualizes the branch parameter as a pending cr/* branch and implies confirm must be true, but this largely mirrors the schema. Baseline 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 clearly states the action (delete), the resource (pending contentrain cr/* branch), and provides examples of when it's appropriate. It distinguishes from siblings by specifying the branch type constraint and that the main branch is protected, 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 explicitly mentions when to use this tool (delete pending branches that won't be merged, e.g., failed operations or superseded drafts) and the constraint that only cr/* branches are eligible. It doesn't name alternative tools directly but implies that merging or other operations belong elsewhere, which is clear in context.

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

• contentrain_content_listA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds behavioral context by specifying the data source (.contentrain/) and issuing a warning not to manually create or modify content files. This goes beyond the annotations.

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

  Conciseness5/5

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

  The description is extremely concise with two sentences, no redundant information, and front-loads the core purpose. Every sentence adds value.

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

  Completeness4/5

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

  For a read-only list tool with 6 parameters fully described in the schema and annotations present, the description captures the essential purpose and a key constraint. It could mention pagination or filtering behavior, but the schema covers parameters adequately.

  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%, so all 6 parameters are documented in the schema. The description adds no additional parameter-level meaning beyond the schema, hence a baseline score of 3.

  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 'List content entries (read-only)' using a specific verb and resource. The read-only nature distinguishes it from sibling tools like contentrain_content_delete and contentrain_content_save.

  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 by indicating it returns data from the .contentrain/ directory and warns against manual file modification. However, it does not explicitly state when to use this tool versus alternative tools for mutations, though the read-only hint and sibling names make it implicit.

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

• contentrain_vocabulary_deleteA
  4.2/5.0
  Behavior5/5

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

  The description adds meaningful behavioral context beyond the annotations: it clarifies that existing content using the terms is unaffected, the vocabulary is merely advisory, and changes are auto-committed to git. These details are not present in the annotations and significantly enhance the agent's understanding of side effects.

  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 extremely concise: two sentences, front-loaded with the core purpose, followed by two key behavioral caveats. Every word earns its place with no filler or repetition.

  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 delete tool with only two parameters and no output schema, the description covers the essential operational context: what is deleted, what is not affected, and how persistence works (git commit). It lacks explicit success-failure response details, but that is not critical for this low-complexity 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?

  Schema coverage is 100%, so the schema already documents both parameters (terms and confirm). The description's phrase 'by slug' is redundant with the schema's description for terms. It adds no new parameter-specific semantics 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 uses a specific verb ('Remove') and a clear resource ('canonical vocabulary terms by slug'), which unambiguously states the tool's function. It effectively distinguishes the delete operation from the sibling save tool (contentrain_vocabulary_save).

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

  Usage Guidelines3/5

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

  The description implies usage for deleting vocabulary terms, but it does not explicitly provide when-to-use guidance or mention alternatives. The statement about content not being touched offers context on impact, but no explicit exclusions or alternative tool references.

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

• contentrain_content_saveA
  4.3/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral traits: auto-commit to git and media field normalization behavior, which go beyond annotations without contradiction.

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

  Conciseness4/5

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

  The description is relatively long but well-structured with clear sections for each model kind. It is front-loaded with the main purpose and every sentence adds value, though could be slightly more concise.

  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 save operation with no output schema, the description covers input variations comprehensively and includes important context like git auto-commit and media field handling. It does not describe errors or return values, which is acceptable given the tool type.

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

  Parameters4/5

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

  Schema coverage is 100% with descriptions for all properties. The description adds significant meaning by explaining how 'id', 'slug', and 'data' are treated per model kind, and specifics about media fields, enhancing understanding 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 'Save content entries' and provides detailed explanations for each model kind (DICTIONARY, COLLECTION, DOCUMENT, SINGLETON), which is specific and distinguishes this tool from siblings like contentrain_content_delete and contentrain_content_list.

  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 implicitly indicates when to use this tool (to save content entries) and includes a warning against manually editing .contentrain/ files after calling, but does not explicitly mention alternatives or when not to use it. Given no sibling save tools, this is adequate.

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

• contentrain_describe_formatA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context by specifying the return content ('comprehensive specification') and scope ('any language/platform'), but it does not disclose additional traits such as output format or potential errors, which is acceptable given the strong annotation coverage.

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

  Conciseness5/5

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

  The description is a single, well-structured sentence that front-loads the core purpose and lists specific deliverables without extraneous words. Every phrase earns its place.

  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 zero-parameter, read-only tool with no output schema, the description sufficiently covers the return value by enumerating the specification categories (file structure, JSON formats, markdown conventions, meta files, locale strategies). It is complete enough to set expectations without additional context.

  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 no parameters, so the baseline is 4. The description compensates by explaining what the tool operates on, and there is no need for parameter-level details because none exist.

  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 'Describes' and clearly identifies the resource: the Contentrain content file format. It lists concrete aspects (file structure, JSON formats, markdown conventions, meta files, locale strategies), distinguishing it from the generic sibling contentrain_describe.

  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 that the tool is used to retrieve format specifications, but it does not explicitly state when to use it instead of alternatives. No exclusions or alternative scenarios are mentioned, leaving room for ambiguity alongside sibling tools like contentrain_describe.

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

• contentrain_content_deleteA
  4.4/5.0
  Behavior4/5

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

  Annotations indicate destructiveHint=true, and the description adds that changes are auto-committed to git and warns against manual edits, providing additional behavioral context beyond annotations.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the purpose, and every sentence adds necessary information without 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?

  Given no output schema, the description sufficiently covers the tool's behavior, parameters, and cautions. It is complete enough for the tool's complexity.

  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 100% schema coverage, the schema documents all parameters. The description adds value by explaining that omitting 'keys' deletes the entire locale file for dictionaries, which goes beyond the schema's description.

  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 'Delete content entries' and distinguishes between dictionary and collection/document deletion. It is specific and differentiated from sibling tools like contentrain_content_save and contentrain_content_list.

  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 'keys' for dictionaries and warns against manual edits after calling the tool. It lacks explicit mention of alternatives or when not to use, but the context is clear.

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

• contentrain_describeA
  4.4/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds the behavioral detail that this tool retrieves a full schema and reinforces the read-only nature. No contradictions.

  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-load the purpose and provide a critical usage warning. Every word earns its place without redundancy.

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

  Completeness4/5

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

  Given the simple read-only operation, good annotations, and full schema coverage, the description covers essential usage. It could mention the output format (JSON schema) but is not required for completeness.

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

  Parameters3/5

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

  Schema coverage is 100%, so the input schema already documents all three parameters (model, locale, include_sample). The description adds no additional 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 clearly states 'Get full schema of a single model (read-only)', providing a specific verb and resource. It distinguishes itself from siblings by warning against manual content file creation and directing to contentrain_content_save.

  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 says not to manually create content files and recommends an alternative (contentrain_content_save). However, it does not differentiate from other read-only siblings like contentrain_describe_format, which might also retrieve schema.

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

• contentrain_reconcileA
  4.4/5.0
  Behavior5/5

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

  Annotations (readOnlyHint: false, destructiveHint: false, idempotentHint: true) are already present, but the description goes well beyond them: it reveals merge granularity ('entry-, key-, term+locale-level'), the two-parent commit mechanism, base-branch fast-forward, and a subtle behavior where stale resolutions are 'dropped and the conflict re-reported.' This is exactly the kind of non-obvious state-machine context agents can't infer.

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

  Conciseness4/5

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

  Every sentence earns its place, and the ALL-CAPS 'DRY RUN'/'EXECUTE' markers make the two modes scannable. The description is dense and could theoretically benefit from paragraph breaks, but it front-loads the purpose and flows logically from behavior to conflict handling to workflow. No filler.

  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 tool with 2 optional params, 4 annotations, and no output schema, the description covers all behavioral surface area: the two execution modes, merge semantics, conflict detection, resolution validation, and a recommended invocation workflow. There's no meaningful gap left unexplained.

  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% — both `dry_run` and `resolutions` are documented in the schema with defaults and formats, meeting the baseline-3 bar. The description's prose reinforces the dry_run default ('Defaults to preview mode') and resolution flow but doesn't add semantics the schema leaves ambiguous.

  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 first sentence, 'Reconcile a diverged contentrain ↔ base-branch pair with a content-aware three-way merge,' names a specific verb (reconcile), resource (diverged pair), and method (three-way merge). It clearly differentiates from the sibling `contentrain_merge` by emphasizing content-awareness and reconciliation of divergence.

  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?

  'Recommended workflow: always run dry_run first, review the summary and conflicts, then execute' is explicit when-to guidance. The DRY RUN vs. EXECUTE contrast also implies when each mode is appropriate. It doesn't explicitly name sibling alternatives or exclusions, but the workflow prescription is actionable and clear.

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

• contentrain_vocabulary_saveA
  4.4/5.0
  Behavior5/5

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

  Beyond annotations (idempotent, non-destructive), the description discloses the merge behavior, auto-commit to git, and an explicit caution against manual file editing. These add meaningful side-effect context that the annotations alone do not convey.

  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 the action front-loaded. Each sentence serves a purpose: action, structure, and a critical warning. 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?

  The description covers purpose, merge behavior, git side-effect, and a caution. It lacks details about return values or error handling, but given the idempotentHint and lack of output schema, the information is sufficient for safe invocation.

  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% and already includes a descriptive example for the 'terms' parameter. The description reinforces the nesting and merge semantics but does not introduce new parameter-specific details beyond what the schema provides.

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

  Purpose5/5

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

  The description clearly states 'Add or update canonical vocabulary terms' with a specific verb and resource. It also explains the nesting structure, distinguishing this vocabulary-save tool from sibling tools like contentrain_vocabulary_delete and contentrain_content_save.

  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 usage: it's a merge operation where omitted terms are untouched, implying incremental updates. It also warns against manual editing of the vocabulary file. However, it does not explicitly name alternatives or state when not to use, though the sibling list and tool name make differentiation straightforward.

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

• contentrain_branch_listA
  4.5/5.0
  Behavior5/5

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

  Annotations already mark readOnlyHint=true and destructiveHint=false. Description adds value by detailing pending branches, merge status against contentrain, and health limits (warning at 50, blocked at 80 unmerged), providing context beyond 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 purpose, then usage guidance and constraints. No wasted words. Efficient and clear structure.

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

  Completeness5/5

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

  Given the tool's simplicity, high schema coverage, and strong annotations, the description fully covers purpose, usage, and behavioral limits. No gaps observed.

  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 clear descriptions for both parameters (remote, unmerged_only). Description does not add new meaning beyond what the schema already provides, so baseline 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 clearly states it lists 'pending contentrain (cr/*) branches with their merge status,' a specific verb+resource. It distinguishes from sibling tools by mentioning it discovers branch names for merge/delete operations and monitors branch-health limits.

  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?

  Explicitly states when to use: 'discover branch names for contentrain_merge / contentrain_branch_delete, and to monitor branch-health limits.' Provides context on limits (warning at 50, blocked at 80 unmerged). No explicit exclusions but sibling list provides implicit differentiation.

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

• contentrain_doctorA
  4.5/5.0
  Behavior5/5

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

  Annotations already indicate read-only and idempotent. Description adds: local-filesystem only, unavailable over remote providers, and lists all checks performed. Also explains the effect of the 'usage' parameter.

  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 efficiently cover purpose, scope, and parameter. Front-loaded with key info. No redundant text.

  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?

  No output schema, but description details return content and includes parameter explanation and local-only constraint. Complete for a health-report 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?

  Schema covers all parameter info (type, default, description). Description adds that deeper analysis is 'heavier', which provides minor extra context beyond schema.

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

  Purpose5/5

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

  The description clearly states the tool provides a project health report with specific checks, and it is read-only. It distinguishes itself from siblings by listing unique checks like 'git', 'node', 'structure', etc., and the name 'doctor' implies diagnostic role.

  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?

  Provides clear context for use: generating health reports. Mentions the 'usage: true' parameter for deeper analysis. Does not explicitly exclude alternatives, but the tool is unique among siblings.

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

• contentrain_statusA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds a crucial behavioral warning about not editing .contentrain/ based on the output, which provides context beyond what annotations convey.

  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 extremely concise with only two sentences. The first sentence covers purpose and return, the second adds a critical warning. Every word earns its place; no 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?

  Given zero parameters, a full set of annotations, and no output schema, the description sufficiently covers what the tool does and what it returns (config, models, context). No additional information is needed for correct invocation.

  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?

  There are zero parameters, so the baseline is 4 per calibration guidelines. The description adds no parameter information, but none is needed.

  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 ('Get'), the resource ('full project status'), and the components returned ('config, models, context'). This distinguishes it from sibling tools like contentrain_apply or contentrain_scan, which are not read-only or return different data.

  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 includes an explicit 'Do NOT manually edit .contentrain/' warning, guiding the agent on what not to do. However, it does not explicitly compare to siblings or state when to use this tool over others, leaving some ambiguity in tool selection.

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

• contentrain_submitA
  4.6/5.0
  Behavior4/5

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

  The description reveals the push behavior and boundary (contentrain/* branches). Annotations indicate idempotentHint=true, which is consistent with normal push semantics. No contradiction, though force push behavior is not clarified.

  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 redundant information. The purpose and key guidance are 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?

  For a simple push tool with two optional parameters and no output schema, the description is adequate. It could mention return value or error states, but the low complexity makes this acceptable.

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

  Parameters4/5

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

  Schema coverage is 100% with descriptions for both parameters. The description adds the crucial 'contentrain/*' pattern context for branches, but does not elaborate on the 'message' parameter beyond 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 specifies the action 'Push', the resource 'contentrain/* branches', and the destination 'remote'. It clearly distinguishes from siblings like contentrain_branch_delete or contentrain_merge by stating 'MCP is push-only'.

  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?

  Explicitly instructs not to manually push or create PRs, and clarifies that PR creation is handled by the platform. This provides clear context on when to use the tool versus alternative actions.

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

• contentrain_applyA
  4.7/5.0
  Behavior5/5

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

  The description discloses significant behavioral details beyond annotations, such as 'DRY RUN... NO changes to disk or git' and 'EXECUTE... writes files to disk, commits to a branch, and requires branch health check to pass.' It also specifies that extract mode leaves source untouched while reuse patches source files, providing clear side-effect 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 five sentences, each conveying essential info: the tool's purpose, mode differentiation, dry run vs execution behavior, recommended workflow, and the never-auto-merge policy. No filler or redundancy; every sentence earns its place.

  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?

  The description covers the tool's operational lifecycle, including preview and execution phases, branch health check requirement, and the review workflow. Given the complexity of the tool with nested parameters, it provides a comprehensive high-level understanding, augmented by the schema's detailed parameter descriptions.

  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 already provides 100% coverage for all parameters with detailed descriptions. The description adds overarching semantics by explaining how the `mode` parameter selects between `extractions` and `patches`, and how `dry_run` controls the preview-vs-execute behavior, complementing the schema's per-parameter 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 states that this tool applies normalize operations with two distinct modes ('extract' and 'reuse'), and details what each does, distinguishing it from sibling tools like contentrain_validate or contentrain_merge. The verb 'Apply' and resource 'normalize operations' are specific and 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 explicitly recommends a workflow: 'always run dry_run first, review the preview, then call again with dry_run:false to execute.' It also clarifies that normalize operations always use a review workflow and never auto-merge. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of a perfect 5.

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