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

Annotations already declare destructiveHint=true, openWorldHint=true, and readOnlyHint=false, so the description's burden is to say which of the 18 actions are actually destructive. It does not: `deregister`, `reclaim_stale`, and `cleanup_registry` delete or steal state, while `list`, `get_activity`, `get_budget`, and `get_metrics` are pure reads, and nothing signals that split. Side effects of `converge_until_done` (looping up to maxIterations, mutating issues) are also undisclosed.

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, so it is compact for an 18-action tool, and the routing instruction is placed last where it is easy to find. However, the comma-separated keyword dump is unstructured and mixes registers ('list/deregister agents') with vague abstractions ('convergence'), so density comes at the cost of parseability.

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 18-branch union with 30 parameters, 10% schema coverage, no output schema, and a destructive annotation, this description is far too thin to call correctly without trial and error. It lists the action families but supplies none of the per-action contract (required fields, side effects, return shape, iteration limits) that an agent would need.

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 10% across 30 parameters, so the description must compensate, and it does not. The one parameter it names, `warningFraction`, is already documented in the schema, and there is no explanation of `staleAfterMinutes` vs `timeoutMinutes`, `maxAssignments`, `roleFilter`, `hardStop`, `reviewerId`, or the `subtasks` shape for `decompose_task`. At most it clarifies that `action` selects a union branch.

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 enumerates the domains covered (agents, activity, work products, budgets, reclaim, assignment, rebalancing, convergence, cleanup), so an agent can tell this is the agent-lifecycle/registry tool. But the enumeration is a bare noun list with verbs missing for most entries, and nothing distinguishes it from sibling `agent_work` (agent-side task operations) or `manage_project` (PM coordination). The scope is discernible but not sharply defined.

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 only guidance is 'Use the `action` field to select the operation', which restates the schema's discriminator rather than telling the caller when to pick this tool over `agent_work` or `manage_project`. There is no indication of which actions are read-only inspection versus mutating cleanup, nor any prerequisite or ordering advice (e.g. list before deregister, set_budget before record_usage).

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 that the tool is not read-only, is open-world, is non-idempotent, and is non-destructive. The description adds value by naming the state-changing operations it can perform, such as checkout, complete, heartbeat, and review submission, but it does not disclose permissions required, side effects, failure modes, or what completion/rejection actually changes.

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 and front-loads the operation inventory before the invocation instruction. It is efficient and free of filler, though the dense operation list is not structured by action sequence or workflow.

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 complex mega-tool with 12 actions, 31 parameters, a discriminated-union schema, and no output schema. The description provides only a high-level inventory and one invocation instruction; it omits per-action requirements, when each action should be used, handoff/review sequencing, and what each operation returns.

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 0% across 31 parameters, so the description must compensate and largely fails to do so. It only clarifies that `action` selects the operation; it gives no meaning for required per-action fields such as `agentId`, `taskId`, `reviewerId`, `summary`, `feedback`, `strategy`, or `status`.

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 is an agent work lifecycle tool and enumerates the supported operations, including registration, task checkout/release/complete, heartbeat, review, validation, and handoff context. It does not differentiate this tool from the sibling `agent_manage` tool, which likely overlaps with the 'register agents' operation.

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 only guidance is 'Use the `action` field to select the operation,' which explains invocation mechanics but not when to use this tool versus siblings like `agent_manage`, `manage_issues`, or `manage_prs`. There is no per-action guidance on prerequisites, sequencing, or exclusions.

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=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing about which of the eight actions actually mutate state, what `autoApply` does, or that these are non-deterministic AI calls with latency/cost implications — a meaningful gap for a non-idempotent multi-operation 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?

Two sentences, front-loaded with the capability list, no filler. The enumeration largely restates the action enum rather than adding meaning, but it is short enough that the cost is low.

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 21-parameter, nested-object, eight-action dispatcher with no output schema, the description should map parameters to actions and flag which operations write. Instead it gives a one-line capability list, leaving an agent unable to construct a valid call without reverse-engineering the schema.

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 5%: 20 of 21 parameters, including nested `config`, `thresholds`, `relationConfig` and several issue-array shapes, are undocumented anywhere. The description only points at the `action` field and loosely implies that enrich/triage/label operations exist, without saying which of `issueId`, `issueIds`, `projectId`, `existingLabels` or `autoApply` belongs to which action.

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 family and resource (AI analysis over issues) and enumerates the concrete capabilities: enrichment, triage, label suggestion, duplicate detection, related issues. That maps well onto the action enum, though 'schedule triaging' is ambiguous versus `triage_all`, `enrich_issue_sections` is never mentioned, and nothing distinguishes it from siblings like `ai_plan` or `ai_generate`.

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 capability list implies which `action` value to pick for a given task, and the final sentence makes the dispatch mechanism explicit. But there is no guidance on when to prefer this over `ai_plan`/`ai_generate`, no prerequisites, and no statement of which actions have side effects.

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 that the tool is not read-only, is open-world, is not idempotent, and is not destructive. The description adds no behavioral context beyond listing operation names; it does not explain which actions mutate data, what side effects occur, whether generated artifacts are persisted, or what authorization is required. For a nine-action mutation-capable tool, this is a significant gap.

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 filler, but the long comma-separated operation list is dense and provides no structure for routing between actions. It is concise to the point of being under-specified for a tool of this complexity.

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 71 parameters, nine distinct actions, no output schema, and mutation-capable behavior, the description is far too sparse. It lacks per-action guidance, parameter-to-action mapping, return expectations, and safety context, leaving the agent with almost no information beyond the action names.

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 71 parameters with only 4% schema description coverage, so the description must compensate heavily but does not. It only points at the `action` field, whose enum is already fully documented in the schema, and says nothing about how the dozens of other parameters map to specific actions. An agent cannot infer parameter meaning from this 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 names a specific AI-generation resource and enumerates the supported operations (PRD generation/enhancement/parsing, feature addition, task selection, complexity analysis, task expansion, traceability matrices). This makes the tool's broad function clear. However, it does not differentiate this tool from siblings such as ai_plan or ai_analyze, which likely overlap in scope.

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 only usage instruction is to use the `action` field to select the operation, which is already evident from the schema. It provides no guidance on when to choose this tool over sibling AI tools, no prerequisites for individual actions, and no indication of which action fits which scenario beyond the action names themselves.

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=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds little beyond the purpose: it does not disclose that generate_roadmap with autoCreate can create milestones in GitHub, nor does it clarify which actions are purely analytical versus side-effecting.

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 and front-loads the tool's scope before the action-selection note. It is efficient with no filler, though the operation list is a dense run-on and could be structured by action.

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 six-action tool with 23 parameters, no output schema, and very low schema description coverage, the description is insufficient. It enumerates the operations but omits per-action parameter requirements, side effects, and what each operation returns.

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 23 parameters with only 9% schema description coverage, and the description mentions only the `action` field, which is already documented by the schema enum. It does not explain the many nested objects, required fields per action, or how parameters like `velocity`, `constraints`, `historicalSprints`, and `autoCreate` affect each operation.

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 names a specific resource, AI planning, and enumerates six concrete operations: capacity calculation, backlog prioritization, risk assessment, sprint composition, roadmap generation, and visualization. This lets an agent distinguish it from general-purpose siblings such as ai_generate and ai_analyze, though it does not explicitly compare itself to them.

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 only guidance is 'Use the `action` field to select the operation,' which explains invocation mechanics rather than when to choose this tool or a specific action. It does not state when to use ai_plan versus ai_generate/ai_analyze, nor which action fits which planning scenario.

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, idempotentHint, and destructiveHint=false, so the description's "read-only" restates structured data rather than adding to it. Nothing is said about how expensive these queries are, whether results are cached, or what happens with a missing/invalid projectId; with annotations carrying the safety profile a 3 is appropriate.

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 tight sentences with the core purpose front-loaded and zero filler. The second sentence is mildly redundant with the action enum's own schema description, keeping it from a 5.

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 five-way report dispatcher with six parameters and no output schema, the description leaves the agent guessing at what each report actually returns (time series? scalar? table?) and at expected cost or latency. It is adequate to invoke the tool but not to predict or use the results confidently.

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 documents defaults and per-report applicability for lastN, bucket, sprintId, sinceDays, and projectId. The description adds only the action-selection hint, 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 ("Read-only project analytics") and enumerates the five report types (sprint velocity, burndown, cycle time, throughput, project summary), which is enough to distinguish it from management siblings like manage_sprints or manage_iterations. It never explicitly contrasts itself with the analysis-oriented sibling ai_analyze, 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?

"Use the `action` field to select the report" tells the agent how to switch reports but not when this tool is the right choice versus ai_analyze or the manage_* tools. No conditions for choosing between sprint_velocity, cycle_time, or project_summary are given, leaving selection to inference from the enum names.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds one genuinely useful behavioral fact, that the tool remains callable regardless of group filters, but says nothing about result size, pagination, or how actions are grouped in the response.

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, zero filler, with the core purpose stated first and the availability caveat second. Nothing to trim.

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-optional-parameter read-only discovery tool with no output schema, the definition covers purpose, scope of results, and availability. The main remaining gap is the shape and volume of the returned tool catalogue, which an agent building a plan 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 description coverage is 100% and both parameters carry their own descriptions plus a 16-value domain enum, so the schema does all the parameter work. The description adds no syntax, matching behavior, or interaction detail (e.g., whether query and domain combine) 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 (discover) and resource (available compound tools) plus what the results contain: actions and parameters. This clearly differentiates it from every manage_*/ai_* sibling, which perform actions rather than enumerate them, though it never names a sibling 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 only usage signal is 'Always available regardless of group filter,' which tells the agent the tool is never gated but not when to reach for it (e.g., before invoking an unfamiliar compound tool) or when the query/domain filters should be preferred over listing everything.

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, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds almost nothing beyond that: it doesn't say whether delete is permanent or reversible, what happens to runs/history of a deleted workflow, whether permissions beyond project access are needed, or that list/get are safe reads.

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 resource and the operation list front-loaded, and the dispatch hint immediately after. No filler or repetition of the title.

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 mixed read/write tool containing a destructive operation, with no output schema and two undocumented parameters. The description should clarify per-action parameter requirements and deletion consequences; without that, an agent cannot confidently call get_workflow or delete_workflow.

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 only 33%: `action` is documented in the schema, but `projectId` and `workflowId` have no descriptions anywhere. The description mentions 'of a GitHub project' hinting at projectId, but never states which identifier each action requires (workflowId for get/delete). With two-thirds of parameters undocumented, it fails to compensate.

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 and resource ('Manage Project Automations') and enumerates the three operations (list, get, delete) with scope limited to a GitHub project's automation workflows. It doesn't differentiate this from the sibling manage_workflows, so an agent could plausibly confuse the two GitHub workflow concepts.

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 tells the agent to use the `action` field to select the operation, which is implied dispatch guidance, but there is no when-to-use, when-not-to-use, or alternative routing versus manage_workflows or manage_project. The agent must infer all selection logic from the enum.

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 declare destructiveHint=true, non-idempotent, open-world, but the description adds nothing about consequences: that delete_protection strips protections for all contributors, that update_protection overwrites unspecified settings, or that admin permissions are required. For a destructive multi-action tool, that is the exact context the description should carry.

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 no padding, and the operation list is front-loaded. But the second sentence spends space on a low-value pointer to the action field rather than on content an agent cannot already read from the 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 an 18-parameter destructive dispatcher with no output schema, the description covers only the action names. It omits what a successful get returns, what an update requires or replaces, and the danger semantics of deletion — the gaps an agent would actually need filled.

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 61%, leaving lock_branch, allow_deletions, block_creations, allow_force_pushes, allow_fork_syncing, required_linear_history and required_conversation_resolution undocumented anywhere. The description does not compensate with any explanation of the protection toggles or their defaults.

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?

Names a specific verb set and resource: get, update, delete branch protection rules plus listing repository branches. The four capabilities map to the four action enum values, so an agent can tell it is not manage_prs or manage_releases. It stops short of explicitly enumerating the action strings.

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?

'Use the `action` field to select the operation' only restates the schema's enum mechanism. There is no guidance on when to pick get vs update vs delete, no prerequisites (admin scope on the repo), and no warning that delete_protection removes safeguards rather than merely editing them.

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 annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the description does not need to restate the safety profile. But it adds no behavioral context: it does not explain which actions have side effects, what subscribing creates, whether replay is safe to repeat, or any auth/persistence/rate-limit implications.

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 tightly written sentences with the operation list front-loaded and no wasted wording. The brief title repetition is negligible and does not hinder clarity.

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 12-parameter, multi-operation tool with no output schema and very low schema description coverage, two sentences are far from complete. The description does not explain the parameters, operation-specific conditions, return behavior, or side effects, leaving an agent unable to invoke it correctly without guessing.

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 8% across 12 parameters. The description only points to the `action` field and repeats the three operation names, leaving `limit`, `filters`, `clientId`, `endpoint`, `eventType`, `expiresAt`, `transport`, timestamps, and resource filters undocumented in both schema and 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 enumerates three concrete event operations (subscribe, get recent, replay) and identifies the resource as project events, so the purpose is clear. It does not explicitly distinguish this tool from the many sibling manage_* tools, which keeps it at a 4 rather than 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 states that the `action` field selects the operation, and lists the three operations, which implies how to invoke it. However, it gives no guidance on when to use subscribe versus get_recent versus replay, and names no alternatives or exclusions.

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 tell the agent this is destructive, non-idempotent, and open-world, which sets a lower bar. However, the tool bundles 22 actions with very different risk profiles and the description discloses none of them — it never says that delete_comment, delete_draft, remove_sub_issue, or remove_blocker are irreversible, nor which actions honor idempotencyKey. For a destructive mega-tool, this is a meaningful gap.

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 tight sentences, front-loaded with the verb and capability list, ending with the dispatch instruction. No wasted words. The brevity is arguably over-aggressive for a 22-action tool, but nothing extraneous is present.

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 dispatcher spanning 22 actions, 36 parameters (17% described), no output schema, and destructive semantics, the description covers only a fraction of what an agent needs. It never maps parameters to actions, lists required per-action inputs, or explains pagination, so successful invocation depends almost entirely on guesswork from the schema.

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 17%, so the description must compensate and it does not. Beyond naming the required `action` dispatcher, it gives no meaning to repo, owner, issueNumber, cursor, perPage, type, dependencyDirection, or the many action-specific fields — an agent must infer which of the 36 parameters apply to each action purely from the schema, where most have no description either. This warrants the lowest tier. (Corrected score: 2.)

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?

Names a specific verb and resource ('Manage GitHub Issues') and enumerates the main capability clusters: CRUD, comments, drafts, search, sub-issues. It is clearly distinguishable from siblings like manage_prs or manage_labels. It falls short of 5 because the enumeration is incomplete against the 22-action enum — dependencies/blockers, issue types, and reprioritization are never hinted at.

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 only guidance is 'Use the `action` field to select the operation,' which is a mechanical instruction, not a when-to-use rule. There is no advice on choosing between 22 actions, no note on which actions require which parameters, and no differentiation from siblings such as manage_project (for project fields) or manage_labels (for label definitions).

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 declare the tool is not read-only, not idempotent, and non-destructive, but the description does not clarify which actions are reads versus writes. In particular, `assign_items` is a mutation, yet the description does not explain what it changes, whether it replaces or adds assignments, or what permissions are required.

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 short and front-loaded, listing the operations immediately and then explaining how to select one. It avoids waste, though it is arguably too terse given the tool's multi-action complexity.

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 five actions, seven parameters, low schema description coverage, and no output schema, the description is missing critical details. It does not explain action-specific parameters, mutation behavior for `assign_items`, or what each operation returns.

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 14%, so the description must compensate but largely does not. It implies `date` for `get_by_date` and `itemIds` for `assign_items`, but leaves `fieldName`, `projectId`, `iterationId`, and `limit` unexplained and does not map parameters to actions.

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 names the specific resource (Project Iterations) and enumerates the operations: get configuration, current iteration, items, find by date, and assign items. This is clear enough to distinguish it from general project tools, though it does not explicitly differentiate it from similar siblings such as manage_sprints or manage_milestones.

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 only says to use the `action` field to select the operation, which is structural guidance rather than usage guidance. It does not explain when to choose each action, which parameters are required for each action, or when to use an alternative sibling tool.

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 declare readOnlyHint=false, destructiveHint=false, openWorldHint=true and non-idempotent, so the safety profile is largely covered. The description adds the useful nuance that 'list' is a read operation while 'create' mutates, but says nothing about permissions, duplicate-label behavior, or whether create is safe to retry.

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 capability and followed by the control-field hint. No wasted words, though the brevity comes partly at the cost of the missing parameter 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?

With five parameters at 20% schema coverage, no output schema, and a dual-action tool, the description should map parameters to actions and hint at results (e.g., what a list returns). It omits all of that, so an agent must infer which fields matter for which action.

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 20%, so the description must carry the burden — but it only names the `action` field, which the schema already documents via enum and description. It never explains that `name`, `color`, and `description` apply to create, or that `limit` applies to list, leaving four of five parameters uninterpreted.

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 concrete verb set and resource: 'create and list labels' for a repository, which is more specific than the generic name 'manage_labels'. It does not explicitly distinguish itself from the many sibling manage_* tools, but the label resource is distinct enough for selection.

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 tells the agent to use the `action` field to pick the operation, and the enum limits that to create/list. However, it gives no guidance on when to choose this tool over siblings, no prerequisites, and no explanation of when create vs list is appropriate beyond the obvious.

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 annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows writes and deletions are possible. The description adds nothing beyond that: it does not say which of the seven actions mutate or destroy data, whether deletes cascade to linked issues, or what permissions are required. For a multi-action mutation tool this leaves the behavioral picture thin.

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 compact sentences, operation list front-loaded, no filler or repetition of the title. It is arguably too terse for its complexity, but nothing present is wasteful.

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 13-parameter, seven-action dispatcher with no output schema and no per-action documentation, which puts a heavy burden on the description. The description does not tell the agent which parameters belong to which action, what each action returns, or how pagination via limit/sort/direction works. It is far from complete for a tool of this 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?

Schema description coverage is only 15%, well under the 50% threshold, so the description must carry the load and does not. It identifies `action` as the selector but says nothing about the other 12 parameters — notably the redundant-looking `state` vs `status` enums, `daysAhead`, `includeIssues`, or which params are required per action. An agent must guess parameter applicability from enum names alone.

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 names the specific resource (milestones) and enumerates the concrete operations: create, list, update, delete, get metrics, get overdue, get upcoming. An agent immediately knows the tool's scope. It does not explicitly differentiate from siblings such as manage_iterations or manage_sprints, 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?

"Use the `action` field to select the operation" gives basic dispatcher guidance and the enumerated action list implies when each mode applies. However, there is no guidance on when to pick this tool over a sibling, no prerequisites, and no explanation of which parameters apply to which action (e.g., daysAhead only makes sense for get_upcoming).

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 annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false, and readOnlyHint=false, so the high-level safety profile is known. The description lists operation categories including delete and remove, but it does not disclose action-level behavior such as which actions are destructive versus read-only, what permissions are required, whether operations are reversible, or how partial failures behave.

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 and front-loads the core purpose before listing operation categories. It is compact and avoids filler, though the long run-on operation list becomes hard to parse for a tool with 38 actions.

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 high-complexity tool with 34 parameters, 38 enum actions, nested objects, and destructive behavior, but the description never explains action-specific requirements or side effects. The annotations cover general safety hints, yet the description remains too thin for an agent to invoke most actions correctly without studying the schema.

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 34 parameters, 21% schema description coverage, and only the `action` field mentioned in the description, the definition provides almost no parameter meaning beyond the schema. It does not map actions to required or optional parameters, explain nested objects like `filter` or `collaborators`, or clarify when fields such as `org`, `owner`, `projectId`, and `contentId` are 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 names a specific resource, GitHub Projects v2, and lists the main operations: create, list, get, update, delete, plus readme, fields, views, items, templates, and repo/team links. This distinguishes it from issue-, PR-, and label-oriented siblings, but it does not explicitly name sibling tools or clarify edge cases where a project operation overlaps with those 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?

The only usage guidance is 'Use the `action` field to select the operation,' which restates the required schema field rather than explaining when to choose this tool over alternatives. It gives no guidance on choosing among the 38 actions, no when-not-to-use conditions, and no prerequisites for destructive or permission-sensitive operations.

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=false, destructiveHint=false, idempotentHint=false, openWorldHint=true, so the safety profile is covered. The description adds no behavioral context of its own: nothing about merge irreversibility, review side effects, pagination via perPage, or rate limits. For a multi-operation mutation tool this is a real gap 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?

Two short sentences, front-loaded with the resource and operations. It is well-sized with no filler, though the second sentence largely restates what the action enum already shows.

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 14 parameters, seven dispatchable operations, no output schema, and near-zero schema documentation, the description is far too thin. An agent cannot tell which parameters belong to which action, what a merge response looks like, or how pagination works without guessing.

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 7% across 14 parameters, so the description must compensate and it does not. It only mentions `action` (already documented in the schema) and explains nothing about base/head, mergeMethod, commitTitle/commitMessage, event, comments[].path/position, or perPage — leaving most parameters semantically opaque.

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 names the resource (Pull Requests) and enumerates concrete operations (create, get, list, update, merge, list_reviews, create_review), which distinguishes it from sibling tools like manage_issues or manage_milestones. It stops short of 5 because the operation list is essentially a restatement of the action enum rather than a clarification of scope differences.

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?

"Use the `action` field to select the operation" tells the agent how to dispatch among the seven operations, which is useful implied usage. However there is no guidance on when to pick this over siblings, no prerequisites (repo/owner context, auth), and no indication of which parameters are required for which action.

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, idempotentHint=false, and openWorldHint=true, so the description does not need to re-state that. It adds nothing beyond them: no statement that delete is irreversible, no note that create requires tag_name (only in schema), no auth or rate-limit context. For a destructive multi-action tool this is thin.

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 resource and operation list, no filler. Slightly wasteful because the verb list repeats the action enum already visible in the 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?

Eleven parameters across six action modes is non-trivial, but the schema carries the per-action parameter mapping well and there is no output schema to explain. What is missing is behavioral context a caller needs for a destructive dispatcher: which actions need write scope, whether delete can be undone. Adequate, with clear gaps.

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 itself documents per-action requirements (tag_name 'required for create', releaseId 'required for get, update, delete', target_commitish/generate_release_notes 'create only'). The description only mentions the action field, which the schema already explains. 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?

Names the specific resource (GitHub Releases) and enumerates the six operations, which line up exactly with the action enum. It is distinguishable from siblings by resource, though the 'manage_' prefix pattern shared with manage_issues, manage_prs, etc. means the only differentiator is the noun.

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?

Tells the agent to use the action field to select the operation, which is minimal routing guidance, but gives no when-to-use or when-not-to-use context, no prerequisites (e.g. permissions to create/delete releases), and does not point to any alternative tool or mention that get_latest differs from list+filter.

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, openWorldHint=true, and idempotentHint=false, so the safety profile is carried structurally. The description's main behavioral note, 'delete requires confirm: true', duplicates the schema's own confirm parameter description, and it says nothing about permissions, per-action side effects, or the effect of idempotencyKey on retries.

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?

One tight block that is front-loaded with the operation list and ends with the dispatch instruction; nothing is padding. It loses a little by restating the title verbatim ('Manage Sprints:') before saying anything new.

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 multi-action dispatcher with no output schema and a nested object parameter, the description omits the most valuable information: which parameters are required for which action. A caller cannot tell from this text what `create` needs versus what `get_metrics` needs, and no return shape is hinted at.

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 13 parameters, a nested sprint object, and only 31% schema description coverage, the description must compensate and largely does not: sprint, status, startDate/endDate, issueIds, includeIssues, and description are given no meaning at all. It only mirrors the delete-confirm rule and the action enumeration, both already present in 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?

Names a specific verb set plus resource ('create, list, update, delete sprints') and enumerates the operation surface (get current sprint, add/remove issues, get metrics and plan). An agent knows exactly what the tool covers, but it never distinguishes itself from plausible siblings such as manage_iterations or ai_plan, which likely overlap.

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 one piece of routing guidance — 'Use the `action` field to select the operation' — which tells the agent how to drive the dispatcher. There is no guidance on when to pick this tool over manage_iterations/ai_plan, and no per-action preconditions 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 already declare that this is mutating (readOnlyHint=false), open-world, non-idempotent, and non-destructive, but the description adds no behavioral context beyond that. It does not mention permissions, side effects of create, or how list pagination behaves.

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 no filler, and the operation list is front-loaded. The extreme brevity leaves gaps, but the wording itself is efficient and easy to parse.

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 tool with three distinct actions and no output schema, this definition is far too thin. An agent cannot infer required parameters per action or what a successful response will contain.

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 20%, and the description explains only the already-documented `action` field. It does not clarify the roles of body, status, projectId, startDate, targetDate, statusUpdateId, first, or after, nor which parameters apply to which action.

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 names the resource (project Status Updates) and enumerates create, list, and get, so an agent can tell what the tool does. It does not distinguish this tool from related siblings or clarify the scope of 'project'.

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 only says to use the `action` field to select the operation, which is an invocation instruction rather than guidance on when to choose this tool over alternatives. No when-not conditions, prerequisites, or sibling comparisons 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?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is largely carried by structured data. The description could have added real value by disambiguating which of the six actions are destructive (cancel_run, trigger_dispatch) versus read-only (list_workflows, get_run) — a tool-wide destructiveHint is potentially misleading without that breakdown. No mention of auth/permission requirements or rate limits.

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, zero waste, operation list front-loaded ahead of the control-field instruction. Nothing redundant.

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 exists, so the description should have said something about what each action returns (workflow list vs run object vs log text) — an agent cannot infer the response shape for six distinct operations. Eleven parameters across a conditional action dispatch also merit a sentence on combinations, though the schema covers those requirements.

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 per-parameter text already specifies which action each param applies to (e.g. runId for get_run/get_run_logs/cancel_run, ref for trigger_dispatch). The description adds nothing beyond pointing at the `action` enum, 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 names a specific resource (GitHub Actions Workflows) and enumerates all six supported operations: list, trigger dispatch, inspect run status/logs, list runs, cancel. An agent can tell exactly what the tool covers, though it does not contrast itself against any sibling (none of the siblings are workflow-related, so differentiation is implicit).

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?

'Use the `action` field to select the operation' is a routing hint, not usage guidance. It never says when to prefer this tool over, say, manage_prs checks or direct API calls, nor does it explain prerequisites (auth scopes, which actions mutate state). Adequate but with clear gaps.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, but the mixed nature of the bundled operations is never clarified — health_check appears read-only while setup_project_fields mutates project configuration. The description says nothing about what setup_project_fields creates or overwrites, whether it is safe to re-run, or what permissions are needed.

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 operation list and followed by the dispatch instruction. Nothing is padded, though the second sentence carries almost no information beyond what the schema already shows.

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 multi-operation dispatcher with no output schema and only 50% parameter coverage, the description should describe what each action does and returns. Instead it only names them, leaving the agent unable to predict behavior or output for either operation.

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 50%: `action` has an enum, but `projectId` has no schema description at all. The description does not state that projectId is only relevant to setup_project_fields and can be omitted for health_check, which is the single most useful clarification it could have added.

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 names the two concrete operations (health check and project field setup) and states the dispatcher pattern via the `action` field. It is distinguishable from every sibling (all of which are manage_*/ai_*/agent_* tools), though the umbrella label 'System operations' is vague on its own.

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 only guidance is mechanical: 'Use the `action` field to select the operation.' It never says when an agent should call health_check versus setup_project_fields, whether setup must precede other project work, or what prerequisites exist. The agent must infer the trigger for each action from the enum names alone.

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