aik-mcp

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

No annotations are provided, so the description carries the full disclosure burden. It doesn't say whether this is a read-only operation, whether it contacts a remote knowledge base or needs network/auth, or whether it mutates local state; the word 'check' hints at read-only but nothing is confirmed.

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?

A single front-loaded sentence with no filler. The resource and the condition ('newer versions available') come first, so the agent gets the gist immediately.

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?

With no annotations and no output schema, the description should say more about what a 'check' returns (e.g., a list of outdated items) and whether anything is affected. It is minimally adequate for a simple 3-parameter tool but leaves the result shape and side-effect profile to inference.

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%, with agent and scope carrying enum descriptions and defaults, so the schema already documents all parameters. The description adds no syntax, defaults, or meaning beyond what the schema states, making the baseline 3 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 specific verb ('Check') and resource ('installed content items that have newer versions available in the knowledge base'), which clearly separates it from siblings like list_installed and update. It stops short of naming alternatives, but the scope is 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 implies the use case (checking for outdated items before updating), but never states when to call it versus update, list_installed, or reinstall. No prerequisites or exclusions are given, leaving the agent to infer the workflow.

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?

No annotations provided, so description carries full burden. Merely states 'Delete' without disclosing irreversibility, safety, or confirmation requirements.

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 sentence, no waste, but could benefit from additional behavioral context without losing conciseness.

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?

Minimal viable for a simple delete tool, but missing return value, error handling, and behavioral caveats given no output schema or annotations.

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 has 100% coverage with parameter description for 'path'. Tool description adds no extra meaning beyond what 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?

Description states 'Delete a content item by its path', using a specific verb ('delete') and resource ('content item'), clearly distinguishing from sibling tools like 'uninstall' (packages).

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?

Implies when to use (deleting content items by path), but no explicit guidance on when not to use or alternatives 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?

With no annotations, the description carries full burden but only states 'Retrieve', implying a read-only operation. It lacks disclosure of behavioral traits such as error handling, return format, or edge cases, though the simplicity of a 'get' tool makes the description minimally adequate.

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 with no superfluous words. Every word is necessary to convey the action and parameter, making it highly concise.

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 tools with one parameter and no output schema, the description explains the action and parameter usage well. It is mostly complete but could enhance by specifying return value format or common error scenarios.

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 the schema already documents the 'path' parameter. The description adds an example ('rules/coding-standards') but does not provide additional semantic depth beyond what the schema offers.

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 'Retrieve' and resource 'content item', with clear method 'by its path'. It effectively distinguishes from siblings like 'delete', 'update', and 'search', 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?

The description does not provide guidance on when to use this tool versus alternatives (e.g., 'search' for unknown paths). There is no mention of prerequisites or exclusions, leaving the agent to infer usage 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?

No annotations are provided, so the description carries the full burden. It conveys implicit read-only semantics via 'Read' and clarifies what an 'asset' is, but says nothing about failure modes (missing path/asset), the returned format (text vs binary), size limits, or whether the asset must exist in an installed bundle.

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?

A single front-loaded sentence with no filler; the core action and resource come first and the parenthetical examples clarify without bloat.

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?

With no annotations and no output schema, the description does a reasonable job of implying the return value (the file's contents) and scoping the two required params, but it omits error behavior and output format for a reader tool where those could matter.

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 the baseline is 3; both 'path' and 'asset' are documented in the schema with examples. The description adds only marginal meaning (assets are 'referenced by its README') and no syntax or format detail 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?

States a specific verb ('Read') and a well-scoped resource ('supporting asset file bundled with a content item'), with concrete examples (example, script, template). It is clearly distinct from generic siblings like 'get' or 'search', though it never explicitly names the sibling it contrasts with.

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 explains what the tool does but not when to choose it over 'get', 'search', or 'list'. There is only an implicit usage context (you have a content item and want a bundled asset), with no prerequisites, exclusions, or alternative-routing 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?

With no annotations, the description carries the full burden and does disclose the key persistence trait (loaded automatically in future sessions). However it omits that this writes/modifies project config, what happens on conflicts, and the gating behavior referenced by the force 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, front-loaded with the action and target, no filler. The second sentence earns only partial keep since it partly restates the schema enum while omitting one 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?

There is no output schema, so the description should ideally explain what install produces (files/config touched) and clarify gating, which it does not. For a mutation tool with no annotations, the explanation of side effects and preconditions is thinner than ideal.

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 documents all five parameters, making 3 the baseline. The description adds no parameter detail and in fact lists only four supported agents (opencode, Claude Code, Cline, Codex), omitting 'copilot' from the enum, which slightly under-informs.

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 (install) and resource (content item: rule, skill, workflow, or agent) plus the effect (auto-loaded in future sessions). It does not explicitly differentiate from close siblings like reinstall, update, or write, so it stops short of 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?

Gives implied context ('into the current project so it is loaded automatically in future sessions') but never says when to use install versus reinstall, update, or write, nor any exclusions or prerequisites. Usage is inferable rather than 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?

With no annotations, the description carries the full behavioral burden and does not say whether this is a read-only listing, how results are ordered or paginated, how multiple filters combine, or what 'available' means. Only the content-type enumeration adds useful context.

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?

A single, front-loaded sentence with zero filler; the tool's subject matter is communicated immediately without redundant restatement of the name.

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 four-parameter, multi-filter listing tool with no annotations and no output schema, the description leaves too much unsaid: result ordering, pagination, filter combination semantics, and the distinction from list_installed and search are all absent.

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 four filter parameters are already documented in the schema, making 3 the baseline. The description adds no extra meaning about filter composition or defaults beyond what the schema states.

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 verb (List) and resource (content items) and enumerates the four content kinds it covers, which sharpens the otherwise generic name 'list'. It does not explicitly distinguish itself from siblings like list_installed or search, so an agent must infer the boundary.

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?

There is no statement of when to use this tool versus the many siblings (search, get, list_installed). The reader is left to infer that this lists all content while search filters, and no preconditions or exclusions are given.

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?

With no annotations, the description carries the full burden; 'List' implies a safe read, and it discloses the supported agent set. But it says content is in 'the current project config' while the schema allows a global scope, and it does not describe return format, ordering, or behavior for a missing project config.

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 scope, with zero 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 simple read-only list tool with a complete schema, nothing critical is missing, but the global-scope behavior, projectDir fallback semantics, and return shape are left unexplained and there are no annotations or output schema to compensate.

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 three parameters are already documented in the schema, giving a baseline of 3. The description adds which agents are supported but actually omits 'copilot', which the agent enum includes, so it adds little and is slightly incomplete.

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 and resource ('List all aik-installed content items') with the config location, which is clearer than sibling 'list'. However it does not distinguish itself from the sibling 'list' tool, so an agent cannot tell the two apart from the description alone.

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 guidance on when to use this versus the sibling 'list' or 'search'/'get' tools, and no prerequisites stated. It only enumerates supported agents, which is capability info rather than usage direction.

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?

With no annotations, the description carries the full burden. It usefully discloses the replace-in-place behavior (uninstall then reinstall latest version) and the supported agents, but says nothing about permissions, failure modes, what happens to locally modified files, or the effect of the force/scope gating it references only indirectly.

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 short sentences, front-loaded with the core action and mechanism; little waste. The closing agent list is somewhat redundant with the schema enum but does clarify supported targets.

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 5-parameter mutating tool with no annotations and no output schema, the description covers the essential action and replacement semantics but leaves gaps around permissions, gating behavior, and result reporting that an agent would want before invoking.

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 the schema already documents path, agent, force, scope, and projectDir in detail; baseline 3 applies. The description adds no parameter syntax or format detail, and its agent list (opencode, Claude Code, Cline, Codex) omits copilot, which appears in the schema enum.

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 (reinstall) plus the resource (previously installed content item) and explains the mechanism: uninstall old entry, install latest version from the knowledge base. This implicitly separates it from install/uninstall siblings, but it never names an alternative explicitly.

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 phrase 'previously installed content item' implies this is for items already present rather than fresh installs, which gives usable context. However, there is no explicit when-to-use vs install/update/check_updates guidance and no stated prerequisites.

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?

With no annotations, the description carries the full burden. It does disclose genuine behavior: matching is full-text and fuzzy, and the scope is all content items. It says nothing about result ordering, ranking, permissions, or whether the operation is read-only, leaving real gaps for a non-annotated tool.

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?

A single front-loaded sentence with no filler. It is efficient, though arguably too sparse given that no other section compensates for the missing usage and behavioral detail.

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?

There is no output schema and no annotations, so the description is the only source for behavioral and routing context, and it covers only the search mechanics. Return shape, ranking behavior, and when to prefer siblings like list or get are unaddressed.

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 query, limit, category, and projectDir are already documented in the schema. The description only echoes the query semantics ('full-text fuzzy') and the cross-content scope, adding little beyond the structured fields. 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?

The description states a specific verb and resource: full-text fuzzy search across content items. That is unambiguous about what the tool does, though it never distinguishes itself from the sibling list/get tools that could also retrieve content.

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?

There is no statement of when to use this over list or get, nor any prerequisite or exclusion. The word 'search' implies query-driven retrieval, but the agent must infer the routing decision entirely from the tool name.

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?

With no annotations, the description carries the full burden, and it does disclose the core side effect (file + config reference removed), which is real value. It omits reversibility, error behavior when the item isn't installed, and permission requirements, and its supported-agent list (opencode, Claude Code, Cline, Codex) silently drops copilot, which the schema's enum includes.

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 short sentences, front-loaded with the action and resource, then the side effect. No padding, though the trailing agent-support sentence is the weakest and partially redundant with the schema enum.

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?

A mutation tool with no annotations and no output schema; the description adequately covers what it does and what changes, and the schema is fully documented. It falls short on error/edge-case behavior and on routing among the several removal-related siblings.

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 the schema already documents all four parameters (path, agent, scope, projectDir) including the config-walking fallback behavior. The description adds no parameter meaning and its agent enumeration is actually less accurate than the enum, so baseline 3 rather than higher.

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 and resource ('Uninstall a content item') and clarifies the effect ('removes the file and the config reference'). However, it never distinguishes itself from close siblings like delete and uninstall_all, leaving the agent to guess which removal tool to pick.

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 when-to-use guidance, no prerequisites, and no named alternatives, despite delete, uninstall_all, and reinstall being present as siblings. The agent must infer the selection criteria entirely.

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?

With no annotations, the description carries the full burden. It discloses that it removes 'all aik-managed files and config references,' which is useful behavioral context. However, it omits irreversibility, permission requirements, and any warning about the destructive nature beyond the word 'Uninstall.'

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 succinct sentences, front-loaded with the primary action and scope. No wasted words; every sentence contributes to understanding.

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 is broadly adequate for a destructive tool, but given no annotations and a scope parameter that allows 'global,' the claim 'from the current project' is potentially incomplete or misleading. It also does not mention the required 'agent' parameter, though 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 100%, so the schema fully documents all three parameters including enums and default. The description adds no parameter information, which is the baseline 3 when the schema does the heavy lifting.

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 ('Uninstall') and resource ('ALL aik-installed content items') with clear scope ('from the current project'). It distinguishes itself from a singular 'uninstall' sibling via 'ALL', but does not explicitly name alternatives or contrast with the sibling tool.

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 (mass removal) through 'ALL' but offers no explicit when-to-use guidance, no exclusions, and no mention of the sibling 'uninstall' or other alternatives. Adequate but bare minimum.

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?

No annotations are provided, so the description carries full behavioral burden. It states the version precondition but says nothing about what happens when no newer version exists (no-op vs. error), what happens if the item was never installed, whether existing files are overwritten or backed up, or what permissions are needed for a mutation.

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, with the core action and its precondition front-loaded. The trailing agent-support sentence is compact but partially inaccurate, which costs it the top mark.

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 mutation tool with no annotations and no output schema, the description covers the 'what' and the version precondition but omits the outcome/return information an agent would want given no output schema exists, plus error behavior for uninstalled items.

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 would be 3, but the description actively narrows the agent set to 'opencode, Claude Code, and Cline' while the schema enum allows five values (opencode, claude-code, cline, codex, copilot). That omission risks steering agents away from valid targets, so it detracts rather than adds.

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 ('update a previously installed content item') and adds a crucial qualifier ('if a newer version is available in the knowledge base') that meaningfully separates it from siblings like install/reinstall. It stops short of naming those siblings, so an agent must still infer the boundary.

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 implied: update content that is already installed when a newer version exists. There is no explicit guidance on when to prefer this over check_updates, reinstall, or install, nor any stated precondition failure behavior.

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?

With no annotations provided, the description carries the full behavioral burden, yet it discloses almost nothing beyond the mutation implied by 'Create or update'. It does not explain that writing over an existing path destroys prior content unless 'overwrite' is set, nor any permission or gating behavior around 'requires'/'appliesTo'.

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 efficient phrase with the action and resource front-loaded and zero waste. It is arguably too terse given the tool's complexity, but every word 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 10-parameter mutating tool with no annotations and no output schema, the description is thin but the schema covers every parameter thoroughly, so an agent can still call it correctly. The missing piece is routing logic against the 'update' sibling and overwrite risk disclosure.

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 ten parameters are self-documented, establishing a baseline of 3. The description adds no parameter-level meaning (e.g. frontmatter vs body handling) beyond what the schema already states.

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 pair ('Create or update') and resource ('content item'), and even enumerates content categories (rules, skills, workflows, agents). However it does not differentiate from the sibling 'update' tool, which appears to overlap directly with the update half of its function.

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?

There is no guidance on when to use this tool versus the sibling 'update', nor any mention of prerequisites or when-not-to-use. The agent must infer the distinction from the overlapping name alone.

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