delete_flagPermanently remove a feature flag across all environments. Use when the flag has no dependents and must be fully removed; otherwise archive it instead.
PERMANENTLY delete a flag across all environments. Fails with FLAG_HAS_DEPENDENTS if other flags use it as a prerequisite. Prefer archive_flag unless the flag must be fully removed.
| Name | Required | Description | Default |
|---|---|---|---|
| flag | Yes | Flag key or id | |
| project | Yes |
Changes observed during successful MCP inspections.
v0.1.6Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description reinforces this by stating the deletion is permanent and applies across all environments. It adds the concrete error condition FLAG_HAS_DEPENDENTS, which is not present in the annotations. This goes beyond the structured metadata 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 three short, information-dense sentences with no filler. The most critical fact (permanent deletion) is front-loaded, followed by the error condition and the preferred alternative. 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?
For a destructive two-parameter operation, the description conveys the critical behavioral context: permanence, cross-environment scope, the dependency error, and the recommended alternative. The main gap is the undocumented 'project' parameter, but the overall operational context is otherwise sufficiently 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 only 50%: 'flag' is documented in the schema but 'project' is not. The description does not compensate by explaining what 'project' refers to or how it interacts with the deletion. The only added meaning is the implicit focus on the 'flag' parameter, leaving the project parameter semantics under-specified.
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 as 'PERMANENTLY delete a flag across all environments,' which is specific about the verb, resource, and scope. It also differentiates itself from archive_flag by noting it should be preferred unless full removal is required. This unambiguously identifies the tool's purpose relative to its siblings.
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 'Prefer archive_flag unless the flag must be fully removed,' giving direct guidance on when to use this tool versus the archival alternative. It also mentions the failure condition FLAG_HAS_DEPENDENTS, which informs the user about a prerequisite that blocks deletion. This is strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.