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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations are largely uninformative (readOnly false, destructive false), so the description carries the burden and does so well: it discloses that every operation auto-commits to git, that dry-run uses a throwaway worktree, that nothing is committed in preview, and that no branch survives. This is exactly the behavioral context an agent needs before mutating content.

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

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

Three compact sentences, each earning its place: what the tool is, the git side effect, and the recommended preview workflow. The critical dry-run caveat is front-loaded before the execution guidance.

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

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

For a 10-parameter mutating tool with no output schema, the description covers the key workflow and side effects. It does not over-explain because the schema documents confirm, locale, slugs, and enums; a small gap is that the description does not spell out the delete confirmation guard, but the schema covers it.

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

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

Schema description coverage is 90%, so the schema already documents the parameters thoroughly. The description adds no parameter-level meaning beyond framing dry_run as the preview mode, which the schema also states; baseline 3 is appropriate.

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

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

States a clear resource ('content entries') and that it performs batch operations, with operation type enumerated in the schema (copy_locale, update_status, delete_entries). It is distinguishable from the single-entry sibling tools by the word 'Batch', though it does not explicitly name those alternatives.

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

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

Gives a concrete workflow: preview with dry_run:true, review counts, then call again to execute. It does not explicitly contrast with single-entry tools or state when not to use it, but the batch/dry-run guidance is clear enough for correct invocation.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations only declare destructive/not-idempotent/non-readonly; the description adds substantive behavior: changes are auto-committed to git, .contentrain/ files must not be hand-edited afterward, and media paths are normalized to absolute public URLs in cloud mode but preserved relatively in local mode (including inside markdown bodies). That is exactly the kind of side-effect detail an agent cannot infer from 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.

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

Front-loaded purpose followed by tightly scoped per-kind rules and a media-handling block; each paragraph maps to a decision the caller must make. The media paragraph is the longest and slightly repetitive about cloud vs. local normalization, but no sentence is filler.

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

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

For a two-parameter but semantically branching write tool, it covers entry shape for all four model kinds, media normalization, and git side effects. With no output schema, it still doesn't state what a successful save returns (created vs. updated entries, per-entry errors), which is the main remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: DICTIONARY ignores id/slug and treats data keys as identities, DOCUMENT requires slug and uses the 'body' key inside data, SINGLETON takes only locale and data, and media fields accept storage paths or URLs. It does not discuss publish_at/expire_at, which the schema already covers well.

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

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

Opens with a specific verb+resource ('Save content entries') and immediately distinguishes itself from content_list/content_delete by defining an exact per-model-kind entry payload contract. An agent can identify this as the write path for content without inspecting the schema.

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

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

Gives concrete when-to-do-what guidance per model kind (which fields to supply and which are ignored), and routes status changes to the sibling 'contentrain_bulk update_status' rather than implying this tool publishes. It lacks explicit exclusions (e.g., when to prefer contentrain_bulk or submit instead), which keeps it below a 5.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations already flag destructive=true and non-idempotent, but the description adds real substance beyond them: it enumerates the concrete side effects (base branch advanced via update-ref, .contentrain/ selectively synced to the working tree, merged branch pruned). An agent knows exactly what state changes and what is destroyed before calling.

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

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

Three sentences, front-loaded with the core action, then the operational nature, then targeting. Dense but every clause carries information; only the update-ref/working-tree detail borders on implementation trivia for a calling agent.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers side effects, environment, and targeting adequately. It does not say what the tool returns or what happens on merge conflict/failure, which an agent would benefit from knowing.

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

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

Schema coverage is 100%, so every parameter is already documented, and the description mostly restates the same resolution rules (branch exact, or model + optional locale/latest). It adds only marginal value, such as implying branch takes precedence, so the baseline 3 applies.

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

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

States a specific verb+resource: "Merge a review-mode branch into contentrain," and names the exact mechanism (feature branch → contentrain branch). This is distinguishable from siblings like contentrain_apply, contentrain_submit, or contentrain_reconcile without opening any schema.

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

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

Gives clear usage context: it applies to review-mode branches and is a local git operation requiring no external platform, plus two targeting modes (exact branch vs. model resolution). It does not explicitly say when NOT to use it or name an alternative sibling, so it stops short of a 5.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds genuinely new context: changes are auto-committed to git and .contentrain/ files must not be hand-edited afterward. It stops short of explaining why the operation is destructive (e.g., whether an update replaces existing fields and can orphan content).

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

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

Two short sentences, front-loaded with the core action and followed by the operational hazard. Nothing is redundant and the warning is placed where it will be read.

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

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

For an 11-parameter mutation tool with nested objects and no output schema, the description covers purpose and the git side-effect but leaves update semantics (does an update replace the whole definition?), failure behavior, and the meaning of the returned result unexplained. Adequate as a minimum-viable definition, not complete.

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

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

Schema description coverage is 100%, so all 11 parameters, including the nested field-definition object, are already documented in the schema. The description adds no parameter-level meaning such as merge-versus-replace semantics for `fields` or required ordering of `id` versus `name`, so the baseline 3 applies.

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

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

The description gives a specific verb+resource pair ("Create or update a model definition") that is unambiguous about the operation. It does not explicitly distinguish itself from siblings such as contentrain_model_delete or contentrain_scaffold, but the resource noun (model) already separates it from the content/vocabulary tools.

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

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

Usage is only implied by "Create or update" — an agent can infer this is the upsert entry point for model definitions, but there is no explicit when-to-use versus contentrain_scaffold, contentrain_model_delete, or contentrain_init. No prerequisites (e.g., whether init must run first) are stated.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations already disclose non-readonly, non-destructive, idempotent behavior. The description adds useful operational context beyond annotations: the tool is push-only and PR creation is handled externally, with an explicit warning not to manually push or create PRs. It does not describe authentication, failure modes, or return behavior, but is meaningfully more informative than the annotations alone.

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

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

The description is two short sentences, front-loads the action and scope, and every phrase carries operational meaning. There is no redundant restatement of the tool name or schema.

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

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

For a low-complexity two-parameter push tool with complete schema descriptions and annotations, the description provides enough context to invoke it correctly. It does not explain success/failure or return behavior, and no output schema exists, leaving a minor completeness gap.

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

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

Schema description coverage is 100%, and the schema already explains the optional message and branches parameters, including that omitting branches targets all cr/* branches. The description adds little parameter-level detail beyond the schema baseline.

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

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

The description states a specific verb and resource: push cr/* branches to remote. It also clarifies the boundary that MCP is push-only and PR creation is handled by the platform, which helps distinguish this tool from PR-creation workflows.

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

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

It gives clear usage context: use for pushing cr/* branches, and do not manually push or create PRs because the platform handles PR creation. It does not explicitly route the agent away from sibling tools such as contentrain_merge or contentrain_apply, so it stops short of full alternatives guidance.

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

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

Beyond the annotations, the description explains mutation behavior in detail: what fix:true changes, when title_field is backfilled, how content without meta gets published status, and how delivery-changing fixes are recorded in visibility_changes and left on the branch. This gives strong operational context for a tool whose annotations mark it as non-read-only but non-destructive and idempotent. There is no contradiction with 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.

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

The description is front-loaded with the core validation purpose and then covers fix behavior efficiently. The parenthetical list of auto-fix cases is long and makes one sentence dense, but the information earns its place. It avoids unnecessary repetition.

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

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

For a two-parameter tool without an output schema, the description gives enough detail to invoke it correctly, especially around auto-fix risk and review behavior. It mentions visibility_changes and notices but does not describe the general validation response shape or error reporting format. Overall it is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so both parameters are already documented in the input schema. The description adds some behavioral framing around fix:true, but most of that detail is also present in the schema parameter description. It does not add meaning beyond the schema for the model parameter.

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

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

The description states a specific verb and resource: validate project content against model schemas. It clearly lists the issue classes it detects, so an agent knows what the tool does. It does not explicitly differentiate itself from similar siblings such as contentrain_doctor or contentrain_scan, which keeps it from a 5.

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

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

It gives concrete guidance for using the fix flag, including what gets auto-fixed and that visibility-changing fixes are held for review rather than auto-merged. It also warns not to manually edit .contentrain/ files. It does not name alternative tools or say when to prefer contentrain_doctor or contentrain_scan over this validation path.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.