Gluecron

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the key contention behavior: it returns lease null when another agent holds an active lease, which is exactly the outcome an agent must handle. It also states the write-permission requirement. It does not cover lease expiry/renewal semantics or what a successful lease payload looks like, but the annotations plus the null-contention note carry most of the burden.

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: what it does and under what permission, how to target the resource, and what happens on contention. No filler, and the return-on-contention fact is stated up front where an agent will see it.

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-parameter coordination tool with no output schema, the description covers purpose, permission prerequisite, both addressing forms, and the failure mode. An agent can call it correctly and interpret a null result without further documentation; lease lifetime details are already documented in the duration_ms schema field.

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 83% schema coverage the baseline is 3, and the description adds genuine meaning by spelling out the two targeting modes: owner+repo with a bare key, versus target_id in '<repository id>:<key>' form. That clarifies how the optional repo/owner combine with target_id, a relationship the schema only hints at. The duration_ms clamping and target_type values are already in the schema, so no credit there.

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 opens with a specific verb+resource ('Grab an exclusive lease') and enumerates exactly what can be leased (PR, issue, branch, file path) plus the write-access precondition. It clearly distinguishes this as an acquisition operation rather than a read or edit, though it never names the counterpart 'merjax_release_lease', so the acquire/release pairing is left 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?

It gives a precondition ('a repository you can write') and a subject ('one of your agent sessions'), which implies the coordination use case, but there is no explicit when-to-use/when-not guidance, no mention of when to call release_lease, and no statement about whether acquisition blocks, retries, or fails fast.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful default behavior (falls back to caller's user spend), but says nothing about aggregation granularity, time window, or whether scopes can be combined — notable gaps for a reporting tool with no output schema.

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, front-loaded with the purpose and then the scoping modes; no filler. It is arguably over-compressed, since the ambiguity around scope vs. user_id could have been resolved with one extra clause, but nothing is wasted.

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, and the description does not need to describe return values in depth, but it also omits any hint of the shape of a 'rollup' or the time range covered. Combined with the missing user_id parameter referenced in the text, the definition is close to sufficient for a zero-required-param read tool but not fully self-consistent.

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 only 25% schema coverage, the description must carry the burden, and it does partially: it clarifies that repo scoping requires the owner+repo pair, which the flat schema does not convey. But it directs scoping via "user_id (self)", a parameter that does not exist in the schema (the schema uses scope='user'), and it never explains how the 'scope' param interacts with the other fields, leaving a genuine ambiguity.

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 opens with a specific verb and resource: "Return AI spend rollups," which tells an agent this is a read of aggregated cost data. It is reasonably distinguishable from cost-adjacent siblings like merjax_list_token_spend and merjax_get_agent_budget, though it never names those siblings to draw the line 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?

It states the three scoping modes and the default (caller's user spend), which implies when each scoping choice applies. However, it gives no explicit when-to-use/when-not-to guidance and no pointer to the alternative cost tools (list_token_spend, get_agent_budget) that an agent could easily confuse with this one.

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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing application mechanics (git apply --cached against branch head), branch auto-creation from base_branch, blank-context-line repair, compare-and-swap semantics for expected_head_sha, branch protection/ruleset/secret-scan enforcement, CI/webhook firing, a 2 MiB limit, and required 'repo' scope.

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

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

Front-loaded with the core purpose and then packed with high-value detail; nearly every clause earns its place. It is a single dense paragraph with layered parentheticals that reward careful reading but make it slightly harder to scan than a structured list would.

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?

Despite no output schema, the description enumerates the return fields ({branch, commit_sha, parent_sha, files_changed, files, commits, created} plus repair counters), and covers auth scope, size limits, enforcement, and format edge cases — everything an agent needs to invoke it correctly.

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 71% schema coverage the schema already documents most params, but the description adds real meaning: the mbox-vs-unified-diff distinction and that message is ignored for mbox, and that all-zeros expected_head_sha means the branch must not exist. It does not restate owner/repo, but those need no elaboration.

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 (commit a patch) plus resource (branch) and immediately distinguishes itself from whole-file writes: 'without sending whole files — the way to change a few lines of a large file.' An agent can tell this apart from write_file or atomic_multi_file_commit without opening any schema.

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

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

Gives clear context for when this is appropriate ('change a few lines of a large file') and explains the two accepted input formats and when message is required vs ignored. It does not explicitly name the alternative sibling tools (write_file, atomic_multi_file_commit) that an agent should consider instead when replacing entire files.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, the bare minimum for a mutation. The description goes well beyond that by disclosing that the review counts toward branch protection's required approvals and, notably, that it clears the caller's own earlier request for changes — a non-obvious side effect on prior state — plus the author-mismatch and closed-PR failure modes.

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 dense paragraph, but it is front-loaded with the action and effect, then preconditions, then the sibling escape hatch, then the return shape. Every clause carries distinct information — nothing is restated from the annotations or 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 a four-parameter mutation with no output schema, the description supplies the side effects, permission requirements, failure conditions, and even the return shape ({reviewId, number, state, url}). Nothing an agent needs in order to call it correctly or interpret the result is missing.

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 owner, repo, number, and body are already documented at the field level, and the description adds no syntax or format detail on top. This is the expected baseline when the schema carries the parameter burden, not a deficiency in the 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?

Opens with a specific verb and resource ("Approve a pull request") and immediately qualifies what that means: it records an 'approved' review by the caller. It distinguishes itself from the nearest sibling by naming merjax_request_changes as the opposite action, so an agent can route correctly without reading either schema.

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

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

Explicit preconditions are given (PR must be open, caller cannot be the author) plus the alternative action and when to pick it ("To request changes use merjax_request_changes"). It also states required permissions and scope, which is the kind of guidance an agent needs before attempting the call.

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 this is a non-read-only, idempotent, non-destructive write, and the description adds genuinely new behavioral context: a hard cap of 10 assignees per thread, the constraint that only users who can read the repository are eligible, the required 'repo' scope and write access, and a partial-failure model via the `skipped` array with reasons. This goes well beyond what the annotations 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?

The operative verb and the remove-mode qualifier are front-loaded, followed by eligibility rules, parameter guidance, auth requirements, and return shape in a logical order. It is a dense single block rather than cleanly separated lines, and the migration note is slightly tangential, but no sentence is wasted.

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 7-parameter mutation tool with no output schema, the description covers the operation, both modes, eligibility limits, auth requirements, and even the response shape ({assigned, skipped, removed, assignees}). An agent has everything needed to call this correctly and interpret partial success.

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 57%, and the description compensates meaningfully: it explains that `assignee` is one username while `assignees` is the array alternative, that `type` defaults to 'issue', and that `remove` inverts the operation. It does not spell out `owner`/`number`, but those are conventional and required, so the added meaning is proportionate.

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 verb+resource combination (assign/unassign users on an issue or pull request) and covers both modes in the first clause. The note that the old `assignee:<username>` labels were migrated distinguishes this from the label-based sibling tools (merjax_label_issue / merjax_unlabel_issue) without needing to open a schema.

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

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

It clearly states the condition that selects each mode (assign by default, unassign with remove: true) and gives the prerequisites ('repo' scope and write access). What it lacks is an explicit pointer to a named alternative sibling, but the migration note about labels effectively tells the agent not to use label tooling for assignees.

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?

Goes well beyond the annotations: it discloses the underlying blob/tree/commit/ref-update mechanics, that branch protection, rulesets, and secret scanning are enforced as with a real push, that CI and webhooks fire, and that a 'repo' scope is required. With readOnlyHint=false already covering the write nature, that is rich added context; the only notable gap is no statement of what the tool returns (e.g., commit SHA) despite there being no output schema.

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 core operation and its branch-creation caveat are front-loaded in the first sentence, and the change-entry format plus side effects follow logically. Minor waste in the self-promotional 'The killer agent tool' and the terse 'blob/tree/commit/ref-update sequence' which is jargon without much agent-facing value.

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

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

For a 6-parameter, 5-required mutation tool with no output schema, the description covers the important unknowns: atomicity, branch creation fallback, enforcement rules, CI/webhook side effects, and required scope. It falls short only on commit-message semantics and return value, which matter when the caller needs the resulting commit reference.

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 33%, and the description mostly restates the `changes` entry shape already present in the schema. It adds meaning for branch auto-creation (tied to base_branch) but says nothing about owner, repo, branch, or that the required `message` is the commit message, leaving two of the six parameters undocumented in both places.

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: apply a set of writes and deletes as a single atomic commit on a branch, with branch auto-creation called out. The atomic batch framing implicitly separates it from merjax_write_file and merjax_delete_file, but it never names those siblings or merjax_apply_patch, leaving the agent to infer the distinction.

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 context is implied rather than stated: 'single atomic commit' and 'The killer agent tool' suggest this is preferred over looping write_file/delete_file calls. There is no explicit when-not guidance, no mention of when to prefer merjax_apply_patch for patch-style edits, and no note that the branch must be resolved via base_branch when absent.

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

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

Beyond the annotations it discloses the auth scope required, the RED escalation criteria (stale, failed, local-only or never-drilled backup), that the request is asynchronous with a 15-minute pickup window, that queuing is audit-logged, and that target credentials are never returned ('host/bucket, never keys'). The mutation available via start is consistent with readOnlyHint=false and destructiveHint=false.

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?

Content is front-loaded: the access precondition and the core question come first, the RED rule next, the write path after, and the return shape last. It is dense and the opening sentence is a long comma-and-colon chain, but nearly every clause carries information an agent needs; nothing is padding.

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 output schema, the description compensates by naming the returned keys ({health, reasons, targets, problems, schedule, runs, started?}), and it explains the health semantics, the async caveat, and the credential-hygiene guarantee. An agent can call this correctly and interpret the result without further documentation.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point because it gives the two valid values ('backup' or 'drill') and, more importantly, their effect and latency: the job is queued for a worker, picked up within 15 minutes, and audit-logged. That is behavioral meaning the schema does not carry.

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 opens with a concrete verb and resource ('Backup and restore-drill health') and then enumerates the exact facts it reports: newest backup verified on an offsite target and its age, Object Lock immutability, last passing restore drill, worker liveness, targets, schedule and recent runs. That is far more specific than the tool name and lets an agent distinguish it from health-adjacent siblings such as merjax_ci_health or merjax_repo_health.

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 the access precondition clearly ('Site admins only (needs an admin-scoped token)') and explains both modes: read-only inspection by default, and passing start: 'backup' or 'drill' to queue work. It does not name an alternative tool or a when-not-to-use condition, but the resource is narrow enough that no close sibling competes.

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 and destructiveHint=true, so the mutation risk is known. The description adds a genuine requirement beyond annotations, the 'repo' scope, plus the state precondition, but says nothing about irreversibility, what happens to in-flight jobs, or whether logs are retained.

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 action and target front-loaded ahead of the scope prerequisite.

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 three-parameter mutation with no output schema, the definition covers the action and auth scope but leaves the agent guessing about side effects on running jobs and the result of the call. Adequate but 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 only 33%: run_id is well documented (including the '8+ hex characters' prefix-matching rule), but owner and repo have no schema descriptions. The description does not compensate at all, adding no meaning for any of the three required parameters.

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 ('Cancel') and resource ('workflow run') and narrows the target to runs that are queued or running. It is clearly distinct from read-oriented siblings such as merjax_get_workflow_run and merjax_list_workflow_runs, though no sibling is named 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 'queued/running' implies the applicable precondition, but there is no explicit when-not guidance (e.g. already-completed runs cannot be cancelled) and no routing to likely alternatives like merjax_prioritize_workflow_run or merjax_rerun_failed_jobs.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds genuinely new behavior: it returns the assistant's reply and, on AI service failure, raises a JSON-RPC error carrying {chat_id, ai_error} instead of a fake apology reply. That failure-mode disclosure is exactly the kind of context annotations cannot provide. It stops short of mentioning side effects like token spend or chat state 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?

Three short sentences, front-loaded with the action, then the return value, then the error contract. No filler, and the clarification about error-vs-apology directly prevents a misread of failure output.

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 output schema, the description usefully covers both the success return and the failure shape. However, for a stateful tool taking an opaque chat_id, it leaves the prerequisite (where chat_id originates) and parameter meaning undocumented, so an agent still lacks enough to call it confidently from a cold start.

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%, so the description must carry the load for both required parameters. It only obliquely hints that chat_id identifies an existing chat and message is the follow-up text; it gives no format, length, or content guidance and no indication of whether chat_id comes from a prior chat call.

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: 'Send another message to an existing repo chat', plus what it returns. The word 'another' distinguishes it from starting a fresh chat (the merjax_chat_with_repo sibling), though that sibling is never named 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?

Usage is implied rather than stated: 'existing repo chat' and 'another message' suggest it is the follow-up to an initial chat call, but the description never names merjax_chat_with_repo as the alternative or states when-not to use this tool. An agent must infer the routing.

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?

Goes well beyond the annotations: it discloses the write path (chat row created, reply persisted), the exact success payload {chat_id, reply}, the failure mode (JSON-RPC error carrying {chat_id, ai_error} rather than apology text), and the authentication requirement. That is materially more than destructiveHint=false tells the agent.

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 dense sentences, front-loaded with the action and followed by the return and error contracts; nothing is filler. The dash-heavy construction packs a lot into one sentence but remains parseable.

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 output schema, the description supplies the return shape and the error shape, which is the important missing piece. The remaining shortfall is caller-side: owner/repo semantics are unaddressed, which matters for a tool that scopes to one repository.

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 50%, and the two undocumented parameters are exactly the ones needing guidance: owner and repo are never explained (format, whether they are separate org/name fields). The description only restates 'repo' and 'message' at a high level, so it does not compensate for the coverage gap.

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 (start a new chat with a repo) and enumerates the concrete side effects: creating a chat row, sending the first user message, streaming and persisting the assistant reply. The word 'new' implicitly separates it from merjax_chat_continue, so an agent can pick between them without opening a schema.

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

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

The framing 'Start a new chat' clearly signals the opening turn of a conversation rather than a follow-up, which is the main usage decision here. It does not explicitly name merjax_chat_continue or say when to switch to it, so the alternative routing is left to inference rather than spelled out.

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 and destructiveHint=false, and the description supplies the missing context: the default path is a read, the write path requires admin scope, is estate-wide and audited, and the response then carries `saved`. It also discloses a domain rule ('In-process never runs while external runners are configured') and the meaning of holdReason. It does not say whether a declaration change is reversible or affects in-flight runs, keeping it off a 5.

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?

It is front-loaded with the purpose and every clause carries information — the runner-count list, the state enum, the holdReason gloss and the admin/write path. The dense em-dash chaining makes it harder to scan than it needs to be, but there is no filler to cut.

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 output schema, the description correctly carries the return burden by naming the fields an agent will get back (mode, declaration, source, runner counts, lastSeenAt, state, holdReason, saved). The read/write split and admin gating are both stated. Error or remediation paths for a degraded/unconfigured state are not described, which keeps it at 4.

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

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

Schema coverage is 100% and the sole parameter's description already covers the admin scope, the three allowed values and 'omit to read only'. The description adds only the audit/`saved` consequence, which is a genuine but small increment over the schema, 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 opening clause 'Where CI runs and why' plus the enumerated facets (mode, declaration and its source, runner counts, lastSeenAt, state, holdReason) makes the resource and scope concrete. It stops short of naming how it differs from siblings like merjax_ci_health, merjax_ci_queue_status or merjax_list_runners, even though it references the /admin/runners endpoint those tools likely wrap.

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 does give one clear conditional: omit `declare` to read only, and site admins may pass it to write. That is real when-to-use guidance for the two modes. However, there is no guidance on when to pick this over merjax_ci_health, merjax_ci_queue_status or merjax_list_runners, so sibling selection is left to inference.

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 establish read-only safety, and the description adds genuinely useful context beyond them: the `dashboard` block is gated on admin scope, poolCost only appears when CI_POOL_COST_PER_MINUTE is set (otherwise 'cost not configured'), and every number carries a `source` attribution. That scope-gating and conditional-field behavior cannot be derived from the annotations.

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

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

A single run-on paragraph dense with backticked field names, nested parentheticals, and internal spec references (CAP-0.4, CAP-1.4, ESTATE_PLAN §5) that mean nothing to an external agent. The reader gets no grouping or emphasis, so the most important facts (read-only, admin-gated dashboard) are buried mid-sentence.

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 output schema, the description carries the full burden of explaining return values, and it does so thoroughly enough to decide whether to call it. It is missing only practicalities like response size or performance cost, which matter for a tool that aggregates 24h/7d rollups.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly spends no space on parameter syntax and instead documents the returned shape.

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 opening sentence names the concrete resource ('CI health') and the endpoints it mirrors, then enumerates exactly what it returns (queue wait percentiles, outcome rates, capacity, firing measures). It is unambiguous what the tool is, though it never names the sibling it is not (e.g. merjax_ci_queue_status), so an agent must infer differentiation from the content list 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?

Usage is only implied: the breadth of the payload signals 'use this for an aggregate CI health overview.' There is no explicit when-to-use, no exclusions, and no mention of alternatives like merjax_ci_queue_status or merjax_ci_executor, which overlap on queue and runner speed data.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the 'Read-only' sentence is redundant, but the description adds real behavioral context: the output shape changes depending on whether owner+repo are supplied, and it notes the result is the same `ciQueue` block the write tools return, which helps an agent correlate responses. It omits cost/latency or rate-limit traits, so not a 5.

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?

Almost every clause carries information, largely because there is no output schema and the return fields must be described somewhere. But it is delivered as one sprawling em-dash-laden sentence that mixes purpose, output fields, and guidance, so it is neither front-loaded nor scannable; the 'Ask before a burst of pushes' cue is easy to miss.

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 output schema, describing the returned blocks (ciQueue, explanation, executor, holdReason) is necessary and is done thoroughly; parameters are covered and the read-only nature is stated. The remaining gap is relational: it does not clarify how this differs from merjax_ci_health or why an agent would call this instead of merjax_ci_executor for the executor portion.

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

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

Schema coverage is 100% and both parameter descriptions are adequate, so the baseline is 3. The description earns an extra point by spelling out the semantic effect of supplying owner+repo (repository-scoped runs, share of CI work, per-class slot holds, and per-run wait explanations) rather than just restating the fields.

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 opening clause ('How full the shared CI queue is, and what to do about it') plus the enumeration of level, queued/running runs, slots and wait estimate makes the resource and the payload unambiguous. However, it never distinguishes itself from siblings like merjax_ci_health or merjax_ci_executor, and by folding an `executor` block into its own output it actively blurs the line with merjax_ci_executor.

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 one concrete usage trigger, 'Ask before a burst of pushes', which is genuinely actionable. But it is buried mid-paragraph, there are no exclusions, and no alternative sibling is named for the overlapping health/executor questions an agent might have instead.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by stating the URL is authenticated, noting the credential-helper hint, and enumerating the returned object fields {url, owner, repo, defaultBranch, hint} in the absence of an output schema.

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, with the core action stated first, then the safety rationale, then the return shape. No filler or redundant restatement of the tool 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 simple two-parameter read with no output schema, the description supplies the return shape and the casing behavior, which covers what an agent needs to call and consume it. Missing only failure-mode context such as what happens when the repo does not exist or the caller lacks access.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns an extra point because 'using the repo's stored casing' tells the agent that lookups tolerate casing differences and that the response normalizes to the stored casing, which is meaning the schema does not convey.

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 opens with a specific verb and resource: 'Return the authenticated HTTPS clone URL for a repo', and immediately adds the credential-helper hint. This distinguishes it from the sibling token tools (merjax_get_token, merjax_list_repo_tokens) which return raw credentials rather than a clone URL.

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 explicit usage guidance: 'Use this instead of embedding tokens in URLs', which tells the agent the condition that selects this tool over credential-based alternatives. It stops short of naming specific sibling tools or excluding cases, so it is clear context without full when/when-not coverage.

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=true, and idempotentHint=true, so the idempotency sentence repeats structured data rather than adding to it. The description does add value beyond annotations by stating the auth/write-access requirement and the return shape {state}, but it says nothing about what side effects closing produces or how it relates to the existing reopen 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?

Three short sentences, with the action front-loaded and each sentence carrying distinct information: what it does, what it requires, and what it returns. There is no filler.

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

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

For a simple three-parameter mutation with no output schema, the description covers the action, the auth prerequisite, idempotency, and the return value, which is close to what an agent needs to call it correctly. The only notable gap is that it does not point to merjax_reopen_issue as the inverse 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 description coverage is 100%, with owner, repo, and number each documented in the schema, so the baseline of 3 applies. The description adds no additional meaning about parameter formats or constraints beyond what the schema already provides.

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

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

States a specific verb and resource ("Close an open issue"), which is enough to separate it from merjax_close_pr, merjax_reopen_issue, and merjax_comment_issue. It does not explicitly name a sibling, so it stops short of the top score.

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 prerequisite "Requires authenticated caller with write access" gives a real usage condition, and "closing an already-closed issue is a no-op" tells the agent it can call it without pre-checking state. There is no explicit guidance on when to prefer this over siblings such as merjax_reopen_issue or merjax_label_issue.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the repeated 'Idempotent' earns no credit, but the description does add value beyond annotations by naming the write-access/auth requirement and the return payload shape ({state}). It stops short of saying what the close does to the branch or whether it is reversible.

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?

Four terse sentences, front-loaded with the action and its scope, followed by permission, idempotency, and return value. Only 'Idempotent.' is redundant with the annotations, and it costs almost nothing.

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 three-parameter mutation with full annotation coverage of the safety profile and no output schema, the description covers action, auth requirement, idempotency, and return shape. The only remaining gap is downstream effect (does closing delete the branch or leave commit history intact), which is a minor omission here.

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% — owner, repo, and number are all documented in the schema — and the description adds nothing about their meaning or format. Baseline 3 applies since the schema carries the parameter burden entirely.

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 ('Close an open pull request') and immediately narrows scope with 'without merging', which is exactly the distinction an agent needs against siblings like merjax_merge_pr, merjax_approve_pr, and merjax_update_pr.

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?

'Without merging' implicitly routes the agent away from merge_pr and gives a clear precondition (an open PR, authenticated caller with write access), but it never explicitly names an alternative or states a when-not condition beyond the merge exclusion.

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 and destructiveHint=false, so the description's added value is the authentication/permission requirement (write access) and the return shape {commentId}. That is meaningful context beyond the structured fields, though it says nothing about failure modes such as locked or closed issues.

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 with the action front-loaded, then the permission requirement, then the return value. No redundant restatement of the title or name, and nothing could be cut without losing information.

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 mutation with full schema coverage and no output schema, the description covers purpose, access requirement and return value, which is close to sufficient. It stops short of noting whether the comment triggers notifications or whether a closed issue rejects the write.

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 owner, repo, number and body are already documented including the Markdown hint on body. The description adds no format or constraint detail beyond the schema, which is the expected baseline when the schema does the work.

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 ('Add a comment to an existing issue'), which cleanly separates it from the sibling merjax_comment_pr by resource type. It does not explicitly name the sibling or note that the issue must already exist beyond the word 'existing', but the operation is unmistakable.

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 by the resource scoping, but there is no explicit guidance on when to prefer this over merjax_comment_pr, merjax_edit_comment, or merjax_reply-style flows, and no when-not conditions. The write-access prerequisite is the only real selection constraint offered.

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

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

Annotations already flag this as a non-read-only, non-destructive write. The description adds genuine context beyond that: an authenticated caller with write access is required, and the response shape {commentId} is disclosed despite no output schema. It omits side effects such as reviewer notifications or whether duplicate comments are permitted, so it is solid but not rich.

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, then the prerequisite, then the return value. 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?

For a simple four-parameter write tool this covers the essentials: action, auth requirement, and return value in lieu of an output schema. It leaves gaps around failure modes (missing PR, insufficient permissions) and notification behavior that would matter to an agent deciding whether to call 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%, with all four parameters documented including the Markdown format for body. The description adds nothing about parameter meaning or valid values, so the baseline 3 applies.

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

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

States a specific verb+resource ('Add a comment to a pull request'), which is unambiguous on its own. It does not differentiate itself from close siblings like merjax_comment_issue, merjax_edit_comment, or merjax_list_pr_comments, so it falls 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?

The only usage signal is the implicit one in the tool name and first sentence. There is no guidance on when to use this versus merjax_comment_issue (issue comments) or merjax_edit_comment, and no note that existing comments should be listed first or that edits go through a different 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?

Adds substantial behavior beyond the annotations: the commit lands on the PR HEAD, never the base branch, and moves through push gates so CI runs before merging. It discloses compare-and-swap semantics for both shas and states that a moved branch is refused with nothing changed. It also notes trailers, a bot comment, and required scopes — all valuable for a write operation whose annotations only mark it non-read-only and non-destructive.

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 dense but front-loads the core action and target before preconditions, failure behavior, and side effects. Every sentence carries operational information, though the long em-dash-heavy sentence is harder to scan than necessary.

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 complex mutation with seven parameters and no output schema, the description covers the essential behavior: where the commit goes, what must be resolved first, how shas guard against races, what side effects occur, and what access is required. It leaves no major operational question unanswered.

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

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

Schema coverage is 100%, so the schema already defines each parameter. The description still adds meaning: `base_sha` and `head_sha` are compare-and-swapped and refusals leave nothing changed; `resolutions` can replace saved drafts; merge-rule-settled files need no entry. That goes beyond the schema's field descriptions.

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

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

States a specific verb and resource: committing saved conflict resolutions as a two-parent merge commit on the PR HEAD. It explicitly distinguishes the target from the base branch and references the draft-producing sibling merjax_resolve_pr_conflict, so an agent can tell what this tool does versus adjacent 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?

Provides clear preconditions: every unresolved file needs a draft or an explicit `resolutions` entry, and write access plus 'repo' scope are required. It also names the sibling that creates drafts. It stops short of explicitly comparing this tool against merjax_propose_pr_conflict_resolution or merjax_merge_pr, but the usage context is otherwise unambiguous.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds two genuinely useful behaviors beyond that: the plaintext token is returned exactly once and must be stored, and an admin scope is required. It does not mention session expiry or what happens on budget exhaustion, which would have pushed this higher.

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 zero waste; the critical one-time-token warning and the scope requirement are both front-loaded rather than buried. Nothing could be removed without losing information.

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 output schema, the description correctly covers the key return value (the plaintext token, delivered once) and the authorization requirement. For a four-parameter creation tool that is nearly sufficient; only lifecycle details such as expiry or revocation path are 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 coverage is 100%, so all four parameters including the budget default and uniqueness constraint on name are already documented in the schema. The description adds nothing about parameter meaning, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Mint a new agent-multiplayer session.' That is clearly distinct from credential siblings like create_repo_token or create_deploy_token, though the description never explicitly contrasts with them. An agent can identify the operation without opening the schema.

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

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

The description supplies a prerequisite ('Requires admin scope'), which helps gate usage, but offers no when-to-use guidance against the many token/credential siblings (get_token, create_repo_token, rotate_token). The context of use is implied by the name 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?

Goes well beyond the annotations (which only say readOnlyHint=false, destructiveHint=false): it discloses that creation is gated like a push, subject to rulesets, and triggers a secret scan of commits no other ref reaches, that CI/webhooks fire, and that the 'repo' scope is required. This is exactly the kind of side-effect and prerequisite disclosure a mutating tool needs.

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?

Six dense clauses with no filler, front-loaded with the operation and followed by side effects, auth scope, and return shape in descending order of importance. Every sentence carries information an agent can act on.

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, yet the description supplies the return shape ({ref, sha}), the auth scope, and the gating/CI side effects. For a 4-required-param mutation tool, nothing material is missing.

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%: sha and branch are documented in-schema, owner and repo are not. The description reinforces that sha must be an existing commit and branch is a new short name, but adds nothing about owner/repo. Baseline 3 is appropriate given the partial schema coverage.

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

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

States a specific verb+resource+constraint: 'Create a new branch ref pointing at an existing sha', plus the equivalent REST endpoint. An agent can distinguish it from merjax_delete_branch or merjax_update_pr_branch without opening the schema.

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

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

Usage is implied by the verb (create a branch), but there is no explicit when-to-use/when-not guidance and no routing against adjacent siblings such as merjax_create_pr or merjax_open_draft_pr, which may also produce branches. The agent must infer when a bare branch ref is the right call.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false; the description supplies the behavior that actually matters — by default no secret is returned at all, the exchange URL is single-use and dies in 60 s, default lifetime 2 h with a 24 h cap, owner/collaborator/team/org access plus 'repo' scope required, and the operation is audit-logged. It also explains that each exchange rotates the secret and that push-capable secrets are refused in the transcript path. 'Read-only by default' refers to the token's grant scope and is consistent with the write-creating annotation, not a contradiction.

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 critical facts — what it mints, that no token is returned by default, and the 60 s single-use URL — are front-loaded, and each subsequent clause carries a distinct operational fact. It is dense but not padded; a few clauses (lifetime defaults) duplicate the schema and could be trimmed.

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 output schema, the description still spells out the return shape ({id, exchangeUrl, exchangeExpiresAt, gitConfig, url}), the default behavior, the alternative delivery mode, prerequisites, lifetime bounds, and the revocation path. An agent has everything it needs to call this correctly on the first attempt.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics beyond the schema: why `token_id` exists (rotate the secret while keeping the same grant) and the security rationale for refusing `deliver: "token"` with `read_only: false`. It largely restates the defaults for `read_only` and `expires_in_hours` that the schema already documents, which keeps it from a 5.

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

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

The first sentence gives a specific verb and resource — 'Mint a short-lived, repository-scoped HTTPS clone credential (a deploy token)' — plus the exact target scenario (sandbox or CI box with no PAT). That scope distinguishes it from generic token siblings like merjax_create_repo_token or merjax_clone_url without needing to name 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?

It clearly states the situation that selects this tool (no PAT available on a sandbox/CI box), when to use the gitConfig exchange flow vs. the `deliver: "token"` fallback, and when to pass `token_id` to re-mint an exchange URL for an existing grant. It also routes revocation to merjax_revoke_token. It stops short of explicitly contrasting this with other token-minting siblings, so it is a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's added value is the authorization requirement (write access on the target repo) and the response shape {number, url}, both of which the agent would otherwise have to guess. It doesn't cover failure modes (duplicate titles, archived repos, rate limits), which keeps it from a 5.

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, zero filler, with the action stated first and the permission and return-value facts following. Every sentence carries distinct information.

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 four-parameter create tool with no output schema, the description covers purpose, authorization, and the return shape, which is enough to call it correctly. Minor gaps remain around error/duplicate behavior, but nothing essential is missing.

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 each of the four parameters is documented in the schema (owner as username or org slug, repo name, title, optional Markdown body). The description adds no meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource pair ("Create a new issue") plus the hosting platform, which is unambiguous and separable from siblings like merjax_close_issue, merjax_comment_issue, or merjax_search_issues. It stops short of naming a sibling or stating scope boundaries (e.g., single repo, no bulk creation), so 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?

The description gives a prerequisite ("Requires authenticated caller with write access on the target repo") but no when-to-use/when-not-to-use guidance and no routing to alternatives such as merjax_comment_issue for adding to an existing issue. Usage is implied by the verb, not explained.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries real weight here and delivers: it states the authenticated-caller plus write-access requirement and the return shape {number, url}. It does not cover edge-case behavior such as what happens when the head branch does not exist or a PR already exists for that pair.

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, then the parameter defaults, then the auth and return contract. Nothing is wasted, though the first two sentences partly duplicate 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 a six-parameter mutation tool with no output schema, the description supplies the essentials: the auth/write prerequisite and the return payload. The main missing piece is the draft-PR distinction, which matters given the sibling tool set.

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 every parameter is already documented, and the description's notes about head_branch being required and base_branch defaulting are restatements of the schema rather than new semantics. Baseline 3 applies; no additional constraint such as branch-name format or cross-repo head syntax is 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?

States a specific verb and resource: 'Open a new pull request.' An agent can distinguish it from read-oriented siblings like merjax_get_pr or merjax_list_prs. It stops short of differentiating itself from the close sibling merjax_open_draft_pr, which is the one case where an agent could pick the wrong 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?

There is no explicit when-to-use guidance and no stated alternative. The presence of merjax_open_draft_pr in the sibling list makes the omitted distinction costly, since 'open a new pull request' could plausibly cover both. The write-access prerequisite is stated, but that is a precondition, not usage routing.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds substantial context beyond that: the token is returned once, effective access is capped by the caller's current repo access and re-checked on every use, branch protection applies, 'repo' scope is required, and the action is audit-logged. This is exactly the behavioral disclosure a mutation tool needs.

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

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

Front-loaded with the core action and scope, then permissions and expiry details. It is dense and long but nearly every clause carries operational meaning; a minor cost is the run-on sentence packing many constraints together.

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-param mutation tool with no output schema, the description covers authentication scope, permission model, expiry rules, access capping, and even the return shape ({id, name, repository, permissions, expiresAt, tokenPrefix, token}). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: admin and settings are never grantable, runners is read-only, omitted keys default to none, at least one must be read/write, and expires_in bounds (5 min to 1 year) with accepted formats. It reinforces rather than merely repeats 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 (mint) and resource (fine-grained repository token) with explicit scope: ONE repository, returned once. The scope and single-repo constraint distinguish it from siblings like create_deploy_token, create_runner_registration_token, and get_token without needing to open any schema.

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

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

It clearly explains what the token authenticates (REST v2/v3, git over HTTPS, container registry) and the 'repo' scope prerequisite, which implies when to use it. However, it never explicitly contrasts with sibling token tools such as create_deploy_token or get_token, leaving the agent to infer the choice.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond them, disclosing token lifetime (expires in an hour), one-time use with a resulting long-lived credential, immutability of exclusive/repositories after registration, and the exact return shape {owner, token, expiresAt, exclusive, repositoryIds, gluecronUrl}.

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 purpose and constraints are front-loaded and every clause carries information, but the prose is dense and runs long with parenthetical asides ('a Mac for Xcode, a GPU box'), which slightly taxes scanning for an agent.

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

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

No output schema exists, but the description enumerates the returned fields, covers all four parameters with behavioral consequences, and states authorization scope ('platform' as a site admin). Nearly complete for a credential-minting mutation, with only sibling-alternative routing left implicit.

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 baseline is 3; the description still adds real meaning beyond the schema by giving a concrete label example ([self-hosted, macos, xcode]), stating exclusive runners never take runs-on: self / ubuntu-*, that the account keeps its shared lane, and that both flags are fixed for the runner's life.

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 ('Create a one-time CI runner registration token') plus the valid owner scopes, which cleanly separates it from siblings like merjax_create_deploy_token, merjax_create_repo_token, merjax_list_runners, and merjax_revoke_runner.

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?

Explains the concrete usage context — a runner started with RUNNER_REGISTRATION_TOKEN registers once and gets a long-lived credential — and describes when to set exclusive: true (Mac/Xcode, GPU box). It lacks explicit routing to alternatives such as revoke_runner or list_runners, so it stops short of full when-not guidance.

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

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

Beyond destructiveHint/idempotentHint, it discloses that write access is required, that branch protection (allow_deletion), rulesets and push inspection gate the call, that webhooks and CI fire as side effects, that the default branch is protected, that the operation is audit-logged, and the exact error semantics for a stale SHA or a missing branch.

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

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

Front-loaded with the action and the mechanism, then preconditions, then return shape. Very dense and nearly every clause carries new information; the git-analogy clause is the only mildly redundant framing since the endpoint mirror is given later.

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, no-output-schema mutation, it covers the permission gate, protection/ruleset checks, side effects, protected-target exclusion, failure modes and the literal return value, so an agent can call it and anticipate the outcome without further sources.

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

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

Schema coverage is 100%, so the baseline is 3. The description's note on expected_sha (delete only if the branch still points there) largely restates what the schema already says, including the conflict behaviour, and it adds no format or constraint detail for owner/repo/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?

States a specific verb and resource ("Delete a branch") and immediately scopes it with the `git push --delete` analogy plus the endpoint it mirrors. That distinguishes it from adjacent siblings such as merjax_create_branch, merjax_delete_repo and merjax_purge_repo without opening any schema.

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

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

Gives concrete usage conditions: it is the git-push-delete path with write access, protection and rulesets applying; the default branch is never deleted; pass expected_sha for compare-and-swap; a missing branch is not-found. It stops short of naming competing tools (e.g. why not delete_repo/purge_repo) but the preconditions make selection unambiguous in practice.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description adds real context: edit history is destroyed along with the comment, authorization is limited to the author or a repo writer, missing comments error rather than silently succeeding (a meaningful nuance against idempotentHint), and the action is audit-logged with actor identity but not content. It also names the response shape.

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?

Five compact sentences, front-loaded with the action and scope, then permissions, error semantics, audit behavior, and return shape. No filler and nothing repeated from the schema or annotations.

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 mutation with no output schema, the description covers preconditions, side effects, error behavior, audit trail, and return payload, which is nearly everything an agent needs. The residual gap is the unexplained optional `thread` parameter, which is the only element an agent could mis-handle when constructing the call.

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 75%, so the baseline is 3. The description adds only the 'by comment id' qualifier; it does not explain the optional nested `thread` object (kind/number) or why a thread reference is supplied alongside a globally unique comment id — the one genuinely under-documented input. It reinforces rather than extends 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?

The description opens with a specific verb and resource ('Delete a comment on an issue or pull request (by comment id)') and scopes it to the comment plus its edit history. It also identifies the id source via merjax_list_pr_comments. It does not explicitly contrast with merjax_edit_comment, but the operation is unambiguous against the sibling set.

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 the authorization precondition ('Its author or a repository writer only') and the failure semantics ('A missing comment is a not-found error, never reported as deleted'), which tells an agent what to expect and how to react. It stops short of explicitly saying 'to remove content without deleting, use merjax_edit_comment', so the alternative is left implicit.

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

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

Goes well beyond the destructiveHint annotation: it discloses optimistic concurrency semantics via the blob sha, the required auth scope, that branch protection, rulesets and secret scanning all apply, and that CI and webhooks fire exactly as on a push. Those downstream side effects are precisely what an agent needs before performing an irreversible write.

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?

Four short sentences, action and resource front-loaded, then prerequisites, then side effects, then the REST analogue. No filler and nothing repeated from the schema or annotations.

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 mutation with no output schema, the description covers side effects, concurrency requirements and auth scope well. The remaining gap is that it never says what comes back (e.g. the new commit sha), which matters for chaining follow-up calls.

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 17%, so the description must carry the load. It explains 'sha' (current blob sha, used for optimistic concurrency) and clarifies 'repo' as a scope, but 'message' (presumably the commit message), 'branch' and 'path' semantics are left entirely to inference from their names.

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 ('Delete a file from a branch') plus an implementation detail ('via git plumbing') and a REST equivalent, which is precise enough to act on. It does not explicitly name a sibling to contrast with (e.g. merjax_delete_branch for whole branches, merjax_write_file for overwrite), so differentiation is inferable rather than stated.

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?

Prerequisites are clear: the caller must already hold the current blob sha and the 'repo' scope, which implicitly tells the agent to read the file first and that it cannot delete blind. What's missing is a when-not-to-use clause, e.g. using merjax_apply_patch or merjax_atomic_multi_file_commit for multi-file changes.

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

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

Annotations already flag destructive=true and idempotent=true, but the description adds real value beyond them: a missing secret is a not-found error and never reported as deleted (clarifying why idempotency does not mean silent success), the call is audit-logged, ownership/authorization requirements differ per scope, and the exact return value {name, deleted: true} is stated.

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

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

Front-loaded with the action and resource, then layered scope, auth and return details. It is one dense semicolon-chained sentence whose clauses all carry information, though a reader must parse carefully to separate the loop path from the org path.

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 3-parameter mutation with no output schema, everything an agent needs is present: scope selection and required privilege, name constraints (enforced in schema), the not-found failure mode, audit logging, and the return shape. Nothing material is left 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 coverage is 100%, so the 3 baseline is met by the schema alone; the description nonetheless adds meaning the schema does not carry — what 'loop' is (a hosted Claude loop id from /connect/claude/deploy), what 'org' implies about token scope and inheritance, and the special status of ANTHROPIC_API_KEY (CAP-S.8, platform never lends its own key; BYOK override at org level).

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

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

Opens with a specific verb+resource ('Delete a hosted-loop (or organisation-level) secret by name') and immediately distinguishes the two scopes plus the name-override relationship, which separates it from sibling deletion tools like merjax_delete_repo_secret or merjax_delete_variable.

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

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

Gives concrete selection criteria: pass 'loop' for the loop's own secret (owner only) or 'org' for an organisation-wide secret requiring an admin-scoped token, and notes a loop-level name overrides the org's. It even points to where the loop id comes from (/connect/claude/deploy). It stops short of naming sibling tools such as merjax_list_loop_secrets for discovery, so not a 5.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, and the description goes well beyond that by disclosing the soft-delete semantics, the 90-day restorable_until window, scope of disappearance across git/web/REST/MCP/CI/webhooks/search/pages, name reservation, CI cancellation, and stopped webhook deliveries. It also covers token scope ('admin'), audit event (repo.delete), and owner notification, which are exactly the kinds of side effects annotations cannot express. It stops short of timestamp/format detail for restorable_until, so it is not flawless, but it is substantively richer than the annotation bar requires.

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 critical fact (soft delete, restorable) is front-loaded in the first clause, and the remaining sentences each carry distinct operational information: effects, permissions, scope, audit, alternative tool, and return shape. It is a dense single block rather than scannable lines, and the embedded date '(2026-10-19)' is noise, which keeps it just below 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?

There is no output schema, and the description compensates by describing the return shape ('{deleted: true, soft: true, id, restorable_until}'). Combined with the permission model, scope requirement, cascade behavior, and the named recovery and purge alternatives, an agent has everything needed to decide and call correctly.

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% for both required parameters (repo, owner), so the schema already carries the semantics and the baseline is 3. The description does add one piece of interpretive value for 'owner' by spelling out that it must be the personal owner or an org owner, but that is a permission rule rather than added parameter syntax or format guidance.

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

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

Opens with a specific verb and resource ('Delete a repository') and immediately qualifies it as a SOFT delete, which is the single most important disambiguation an agent needs. It is clearly distinguished from the sibling tools that do something similar but different: merjax_purge_repo (permanent) and merjax_restore_repo (undo).

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

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

Explicitly states when to use the alternative: 'To remove it for good before then, use merjax_purge_repo', and names the restore path with its time bound. It also states who is allowed to call it and who is refused (admin collaborators, org admins), which functions as a precondition/exclusion list rather than generic advice.

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 and idempotentHint, yet the description adds substantial context beyond them: the exact idempotent result shape (deleted:false, already_deleted:true), the consequence that referencing workflows stop receiving the secret, required permissions and scope, and audit logging with name only.

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

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

Front-loaded with the action and target, then idempotency, side effects, auth, and return shape in compact sentences. No filler, and the inline return-shape summary substitutes usefully for the absent output schema.

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

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

For a destructive, unannotated-output tool this covers everything an agent needs: scope, casing rule, idempotent semantics, side effects on workflows, permission requirements, audit behavior, and return fields despite there being no output 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 100%, so the baseline is 3, but the description adds real meaning the schema lacks — the name normalization rule that cron_secret is read as CRON_SECRET, which affects what an agent must pass.

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 (Delete), resource (one workflow secret), and scope (repository, by name), which is enough to separate it from sibling operations like merjax_set_repo_secret, merjax_list_repo_secrets, and merjax_delete_loop_secret without opening any schema.

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

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

Gives clear operational context: idempotent retry is safe, admin access plus 'repo' scope are required. It stops short of explicitly routing the agent to alternatives (e.g. set_repo_secret to update, delete_loop_secret for loop-scoped secrets), so no exclusion guidance is present.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description goes beyond them with what an agent actually needs: a non-existent variable is a not-found error rather than a silent success, the org path requires an admin-scoped token, and the call is audit-logged. It also states the return shape, which matters because there is no output schema.

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?

Sentences are short, front-loaded with the action, then the required scoping shape, then failure and return semantics. Every clause carries information; the only slight redundancy is restating the return value after already saying a missing variable is an error.

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, six-parameter tool with zero required parameters and no output schema, the description covers scoping, auth requirements, failure semantics, audit logging, and return value. The remaining hole is the undocumented `id` parameter as an alternative to `name`.

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 adds real meaning by explaining the conditional combinations of otherwise all-optional parameters — something the schema cannot express. It loses a point for describing deletion 'by name' while never mentioning the schema's `id` alternative.

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

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

Opens with a specific verb and resource ('Delete an Actions variable'), and the resource is narrow enough (variables, not secrets) to separate it from neighbours like merjax_delete_repo_secret and merjax_delete_loop_secret. It then enumerates the three scoping modes, so an agent knows exactly what class of object this acts on.

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

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

It gives concrete routing rules for invocation: owner+repo for repository variables, owner+repo+environment for environment variables, org for organisation variables. The one gap is that it never explicitly contrasts with merjax_set_variable or merjax_get_variable, but the operation is unambiguous enough that the missing sibling callout is minor.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false; the description adds real value by disclosing the required 'repo' scope, the write-access prerequisite, and that a reason is mandatory and audited. It does not contradict the annotations, since dismissing a review is a state change rather than a destructive deletion. It stops short of saying what happens to blocked merge state afterwards or what errors arise without write access.

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 action and its scope front-loaded, followed by prerequisites and audit note. No filler, no restating of the title, every clause carries information.

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 mutation tool with no output schema, the description covers the essentials: scope of the operation, auth requirements, and the audited reason. The remaining gap is that it says nothing about outcomes or failure modes, but that is a minor omission given the absence of an output 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 only 40%, so the description has to compensate: it clarifies the meaning of 'reviewer' (only this one's request) and confirms 'reason' is required and audited. It adds nothing about owner, repo, or number, which remain 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?

States a specific verb ('dismiss'), a specific resource ('standing changes-requested reviews on a PR'), and the effect ('so they no longer hold the merge'). It also scopes the operation (all reviews or one reviewer's), which distinguishes it from the inverse sibling merjax_request_changes without needing to be named.

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 by the stated effect: an agent can infer this is used when requested-changes reviews are blocking a merge. However, it never states when NOT to use it, nor names alternatives such as merjax_request_changes or merjax_approve_pr, so routing depends on inference.

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?

Goes well beyond the annotations: it explains that the previous text is preserved in edit history, that repeat submissions are idempotent no-ops, that concurrent edits surface as conflicts instead of silent overwrites, and that newly added mentions trigger notifications. This directly qualifies the destructiveHint=true flag by showing the operation is recoverable and never clobbers stale state.

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?

Dense but front-loaded: the primary action and its permission gate lead, and each semicolon clause carries distinct information (history, idempotency, conflict, notifications, endpoint, return shape). The PATCH-path sentence is arguably only useful to API-familiar agents, but nothing is padded.

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 mutating tool with no output schema, the description supplies the authorization model, mutation semantics, failure/idempotency behavior, and even the return shape ({id, kind, number, effect}), which is more than an agent needs to call it correctly. The only unaddressed element, the nested thread parameter, is fully specified in the schema itself.

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 already 80%, so most parameters are self-documenting (body, owner, repo, comment_id with a pointer to merjax_list_pr_comments). The description adds only the 'by comment id' framing and leaves the nested `thread` object (kind/number) and its required-ness unmentioned, so it does not meaningfully extend the schema's coverage.

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 ('Replace the text of a comment on an issue or pull request') plus the addressing key (comment id). This cleanly separates it from the creation siblings (merjax_comment_issue, merjax_comment_pr) and from merjax_delete_comment without needing to open a schema.

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

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

Gives real preconditions: 'Its author or a repository writer only', and describes the no-op case ('the same text again is unchanged') and the conflict case ('never overwritten'), which tells an agent when the call will not do what it expects. It does not explicitly name alternatives such as merjax_delete_comment or merjax_list_pr_comments (the latter only appears in the schema), so routing guidance is implied rather than spelled out.

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 only readOnly/destructive annotations supplied, the description carries real behavioral weight: it discloses the signal normalisation ('normalised error signature'), the privacy scoping of cross-repo lookups ('this repo, your other repos with the same owner or org, and platform-wide counts only'), the fallback behaviour ('the class's standard remedy'), and the guardrail that infra and flaky failures never suggest a code change. None of that is derivable from the annotations.

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

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

It is front-loaded with the task statement and is a single dense sentence, but the long em-dash-delimited list of outputs makes it a run-on that is harder to scan than a short bulleted enumeration would be. The content mostly earns its place, but the packaging costs readability.

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 must describe the return payload itself — and it does, down to per-step class, chosen rule, signature, prior occurrences with fix rate, and the shape of the suggested fix. Combined with the prefix rule and the no-code-change guardrail, an agent has what it needs to call and interpret this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the run-id prefix rule already present in the schema and only indirectly implies include_diff ('its diff limited to the relevant files'), adding no new parameter meaning.

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 opens with a concrete verb+resource ('Explain a failed CI run') and then enumerates exactly what is produced: per-step failure class, chosen rule, normalised signature, failing tests, touched files, prior occurrences with fix rate, and a suggested fix. That is far more specific than a sibling like merjax_get_workflow_logs, but no sibling is named, so the differentiation is inferred rather than stated.

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 by the opening scope ('a failed CI run') and the run-id prefix rule ('with owner + repo an 8+ hex prefix also works'), but there is no explicit when-to-use/when-not guidance and no named alternative such as get_workflow_logs for raw output or list_flaky_tests for flake detection. The agent must infer which tool to pick from the output list alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds genuinely new behavioral context: the result is cached and no generation is triggered. However, it is silent on the most important behavioral question for a cache-only read — what happens on a cache miss (empty result, error, or stale content) — and gives no hints about size or structure of the returned Markdown beyond the format.

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 behavior (cached read) front-loaded and the caveat immediately after. Nothing is repeated from other fields or padded.

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, so the description carries the return-value burden, and it does state the return type (Markdown). But it omits cache-miss behavior and any parameter format guidance, which are the two things an agent still needs to call this correctly.

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% with two required parameters, owner and repo, neither of which has a description. The description only alludes to 'a repo' and does not clarify the owner/repo split, accepted formats, or whether org-scoped names work. With low coverage the description has to compensate, and it does not.

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?

Specific verb and resource: 'Return the cached AI "explain this codebase" Markdown for a repo.' The agent knows exactly what comes back. It does not name the obvious sibling, merjax_repo_explain_codebase, which likely generates the artifact, so differentiation is left 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?

Gives a clear exclusion — 'Pure read — never triggers a new generation' — and redirects to an alternative ('use the web UI for that'). The redirection is to the UI rather than to the sibling tool merjax_repo_explain_codebase, which is the alternative an agent could actually call.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. Beyond that, the description only mentions the internal implementation function it wraps ('src/lib/symbols.findDefinitions'), which says nothing about behavior an agent needs — whether multiple definitions per repo are returned, whether results include file paths and line spans, or how large repos are handled.

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 purpose front-loaded and no padding. The second sentence is an implementation detail of marginal value to an agent but costs little space.

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 output schema, the description carries the burden of describing the return shape, yet says nothing about what a 'definition' result contains (path, line, snippet, count) or any result limits. Combined with two undocumented required parameters, the definition is too thin for reliable invocation.

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

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

Schema coverage is only 33%: 'name' is described as 'Symbol name', but 'owner' and 'repo' have no descriptions in either the schema or the description. The description does not compensate by clarifying required repo/owner scoping (e.g., 'OWNER/REPO' format) or whether name is case-sensitive or fully qualified.

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 and object: 'Find definitions of a symbol by name within a repo.' An agent can tell this is a symbol-definition lookup scoped to a repo. It does not explicitly differentiate itself from adjacent siblings such as merjax_search_code or merjax_semantic_search, 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?

There is no guidance on when to use this over merjax_search_code, merjax_semantic_search, or merjax_read_file, and no preconditions or exclusions are stated. The agent must infer that this is for jumping to definitions rather than free-text search.

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 and destructiveHint=false, so the mutation/safety profile is covered. The description adds genuinely non-structured context: the required 'repo' scope and the exact return payload {owner, repo, url}, which tells the agent what it gets back without an output schema. It doesn't cover rate limits, idempotency, or what happens on an existing fork.

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?

Four short sentences, zero filler, and the core action is front-loaded. Each remaining sentence carries a distinct fact: endpoint mapping, return shape, and auth requirement.

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

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

For a two-parameter mutation with no output schema, the description supplies the destination semantics, the auth scope, and the return shape — enough to call it correctly. Only edge-case behavior (duplicate fork, naming collisions, permission failures) is 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 both parameters are already documented as the source owner and source repo. The description adds only the framing that the fork target is implicitly the caller's namespace, confirming there is no destination parameter. That is a small clarification over the schema, consistent with the baseline 3.

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

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

States a specific verb and resource ("Fork a repository") plus the destination (the authenticated caller's namespace), which is the detail an agent needs to distinguish it from a plain create/update repo operation. It stops short of naming a sibling alternative, so it lands at 4 rather than 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?

Usage is implied by the purpose statement — the agent can infer this is the right call when it wants a copy of someone else's repo under its own account. There is no explicit when-to-use/when-not guidance, no note on prerequisites beyond the scope, and no mention of behavior when a fork already exists.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds only that it shares an engine with the PR-description tool; it says nothing about accepted diff format, output shape, determinism, or whether the result is a raw string.

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 purpose front-loaded and no filler. The second sentence is slightly redundant with the name but does carry cross-tool context.

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 indicate what is returned (a plain commit message string, subject line only or subject plus body). It omits that, and also omits input format guidance for the required diff parameter.

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%: the 'style' parameter documents 'conventional'/'plain' and its default, but 'diff' has no schema description and the tool description does not compensate by specifying format (unified diff? git diff output?) or size expectations.

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 ('Generate a commit message for a diff') and explicitly names the sibling it parallels (merjax_generate_pr_description), so an agent can tell the two apart by output artifact.

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 the use case via 'explicit for the commit-message use case', but never states when to prefer this over merjax_generate_pr_description or what prerequisites (e.g., a diff source) are needed. Guidance is inferable but not spelled out.

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

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

Beyond the readOnlyHint=true / destructiveHint=false annotations, which correctly signal a non-mutating operation, the description discloses the LLM-backed implementation and, importantly, the graceful degradation to a heuristic when ANTHROPIC_API_KEY is missing — a real behavioral caveat an agent should know. With no output schema present, the stated return shape '{subject, body}' also adds genuine value.

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 purpose followed by behavior and return shape, with no filler. The reference to src/lib/ai-commit-message.ts is an implementation detail that earns only partial keep as the context for the fallback behavior.

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

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

For a two-parameter generation tool this covers purpose, dependency, degraded-mode behavior, and return shape — enough to invoke it correctly without an output schema. The remaining gap is sibling disambiguation against the closely named commit-message and release-notes generators.

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 'diff' documented as a unified-diff body and 'style' as 'conventional' (default) or 'plain'. The description adds nothing about either parameter, so the schema carries the full burden and the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Generate an AI commit-message-style description for a diff.' That is concrete enough to act on, but it never separates itself from the very similar sibling merjax_generate_commit_message, which the wording ('commit-message-style') arguably overlaps 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?

Usage is only implied: the required diff argument and the phrase 'for a diff' make it clear you call this when you have a diff and want PR text. There is no explicit statement of when to prefer this over merjax_generate_commit_message or merjax_generate_release_notes, and no exclusions or prerequisites 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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful return-shape context ('rendered Markdown + section data'), which matters because no output schema exists. It does not disclose cost/latency of the underlying AI call or what happens when from_tag is omitted.

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 the return-format note earns its place given no output schema. The middle sentence exposing the internal module path (src/lib/ai-release-notes.generateReleaseNotes) is implementation detail that adds little for an agent selecting or invoking the tool.

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 4-parameter read-only tool with no output schema, the description covers purpose and return shape adequately. It leaves two gaps an agent would care about: the optionality/fallback behavior of from_tag and the expected format of owner/repo identifiers.

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%: to_tag and from_tag are described there, owner and repo are bare strings. The phrase 'between two tags' reinforces the from_tag/to_tag pairing but never states that from_tag is optional or what the tool does when it is absent (e.g., auto-detect last release). Baseline 3 at this coverage level.

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 ('Generate release notes between two tags'), which is clearly distinct from the mutation siblings in the list. It does not differentiate itself from the closest related generators (merjax_generate_commit_message, merjax_generate_pr_description), so an agent must infer the boundary from the name 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?

There is no explicit when-to-use guidance, no prerequisites, and no reference to the sibling generators that also produce commit/PR/release narrative text. The only contextual cue is the tag-range phrasing, which an agent must interpret as 'I have two release tags'.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description usefully goes further: 'follow-up-pr' opens a new PR while 'append-commit' commits onto the head branch, which tells the agent exactly what side effects each mode produces. It also discloses the required 'repo' scope. It stops short of saying whether generated tests are committed atomically, what happens on failure, or cost implications of an AI call.

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 scope requirement. The internal source path reference is the one sentence fragment that does not earn its place for an agent invoking the tool.

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, yet the description explains what each mode produces (a new PR vs. a commit on the head branch), which is the key return-behavior information. Combined with the scope prerequisite and annotations covering the safety profile, an agent has enough to call this mutation tool correctly.

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%: 'mode' and 'number' are described, while 'owner' and 'repo' are bare. The description adds genuine meaning to the mode values by explaining their outcomes, compensating for the schema's terse enum-like listing, but it adds nothing for the two undocumented parameters. Baseline 3 is appropriate given partial coverage and partial compensation.

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 ('Generate tests for a PR') and clearly differentiates from siblings like merjax_generate_commit_message and merjax_generate_pr_description. The mention of the internal module ('Wraps src/lib/ai-test-generator.generateTestsForPr') adds no distinguishing value for an agent choosing a tool, but it doesn't obscure the purpose.

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 by naming the two modes and their divergent behavior, plus a 'requires repo scope' prerequisite, but it never states when to choose this tool over alternatives (e.g., a plain PR review) or when the modes are inappropriate. An agent must infer selection rules from the mode names alone.

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 establish a non-destructive read, and the description adds useful output behavior by naming the three measures and their cents unit. It does not clarify snapshot timing, handling of unknown or expired sessions, or representation of sessions without a cap.

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 conveys the operation, scope, returned fields, and units without filler. The slash-separated phrasing is compact but remains understandable.

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 one-parameter read, the definition is sufficient to infer the basic call and expected budget information. With no output schema, however, it remains thin about response shape and edge cases, and it lacks session-ID acquisition and alternative-tool guidance.

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

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

The sole parameter has no schema description, and the description only indirectly supports it through the phrase 'for an agent session.' It does not document the expected identifier format, validity requirements, or where to obtain agent_session_id.

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 clear verb, resource, and scope, and specifies the returned values: spent, cap, and remaining cents for an agent session. It does not explicitly distinguish this session-level view from siblings such as merjax_ai_cost_summary or merjax_list_token_spend.

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 agent-session scope implies using the tool to check one session's budget, but there is no explicit when-to-use or when-not guidance. It also does not direct agents to aggregate cost or token-spend alternatives when those are more appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces that with 'Read-only'. Beyond the annotations it discloses the fallback behavior ('Returns {protected: false, ...} when no rule applies') and the full return shape for both branches, which is meaningful for a tool with no output schema; it does not cover auth or rate-limit behavior.

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 core action is front-loaded in the opening clause, and the subsequent field enumeration is dense but informative. The long semicolon-chained middle sentence is heavy, yet nearly every clause (merge_train, gate_test states, fallback shape) carries distinct information an agent needs.

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

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

For a read-only tool with no output schema, the description compensates well by documenting the return structure and the protected:false case. It also decodes the gate_test state enum and names the setter for that field; the only gap is not naming merjax_set_branch_protection as the counterpart for the other fields.

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 baseline would be 3, but the description adds real meaning: the branch argument accepts an exact name or a glob that covers the branch, which is not in the schema. Owner/repo add nothing beyond their existing schema descriptions.

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

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

States a specific verb and resource ('Read the branch-protection rule that applies to a branch') and immediately enumerates what that rule contains, so it is unmistakable versus merjax_set_branch_protection or merjax_get_pr_checks. It even clarifies the branch selector semantics (exact name or the glob that covers it).

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

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

Gives clear context: 'Read-only' and points to merjax_update_repo gate_test_enabled for changing the gate_test value, which tells the agent where the write path lives. It does not explicitly direct mutation of other fields to merjax_set_branch_protection, and offers no when-not-to-use guidance, so it stops short of a 5.

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

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

Annotations already establish this as a safe read (readOnlyHint=true, destructiveHint=false), so the description only needed to add scope, and it does: it enumerates the returned fields and explicitly warns that patch bodies are absent, preventing an agent from assuming diffs come back. It does not cover auth, rate limits, or behavior for unknown SHAs, which keeps it below a 5.

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 tight clauses with zero filler: what it returns, how it maps to the underlying endpoint, and the one thing it deliberately omits. The critical exclusion is front-loaded right after the scope statement.

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

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

For a read-only single-resource fetch with no output schema, the description supplies the closest thing available: an explicit field list of what comes back and a clear statement of what does not. Nothing an agent needs in order to call it correctly is missing.

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 only 50% schema coverage, the description carries real weight: it explains that lookup is keyed by SHA and that the default payload includes the files-changed list, which is the meaning behind the include_files flag. The REST path it cites also grounds owner/repo, though those two parameters are still not described anywhere.

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 pairs a specific verb and resource ('Fetch a single commit by SHA') with the exact payload contents (metadata, changed files with path/status/additions/deletions) and maps itself to GET /api/v2/repos/.../commits/:sha. That is enough for an agent to distinguish it from siblings like merjax_get_diff or merjax_list_tree without opening any schema.

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

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

It gives an explicit exclusion plus the alternative: 'Patch bodies are NOT included — use merjax_get_diff for those,' which is the main routing decision an agent faces here. What is missing is guidance on when to prefer this over other commit-level lookups (e.g. workflow runs or PR views), but the primary fork is covered.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description usefully adds behavior beyond that: patch text is byte-capped and output can be truncated, and it shows the return shape. However it does not explain what truncation means for the caller (e.g., how to retrieve the remainder) or hint at size/permission 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?

Three tight sentences, front-loaded with the operation, then the two calling modes, then the return shape and the size control. There is no filler, and each sentence carries decision-relevant information.

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 output schema, the description steps in by sketching the returned object ({files, stats, truncated}) and the fields per file. For a 7-parameter read tool with two mutually exclusive calling modes, that is close to complete; only the exact truncation/retrieval semantics and max_patch_bytes guidance are missing.

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 71%, and the description adds real meaning beyond it: it specifies that `sha` diffs against the first parent and that base/head uses the merge base, plus the practical effect of include_patch=false. The `max_patch_bytes` parameter is only indirectly covered by 'byte-capped', leaving its tuning semantics to 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 resource ('actual changes in a commit or a branch range'), and 'actual changes' implicitly distinguishes it from metadata readers like merjax_get_commit or merjax_get_pr. It stops short of naming any sibling explicitly, so the differentiation is inferential rather than stated.

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 explicit mode-selection guidance: pass `sha` for a single commit vs its first parent, or `base`+`head` for everything head adds since the merge base, framed as 'what a PR proposes'. It also offers a lightweight alternative ('set include_patch=false for a files-changed summary only'). No sibling-tool routing is offered, which keeps it from a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: the auth gate, the meaning of null for mergeable, the mergeState status vocabulary, and that the probe is the same one the merge gate uses. However, it discloses no failure modes (missing PR, permissions beyond auth) or response envelope behavior.

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 content is front-loaded and every clause maps to a real return field, so little is wasted. But it is delivered as one semicolon-chained run-on spanning three payload groups (record, mergeState, conflictRisk), which is hard to parse; a short structured breakdown would convey the same facts more clearly.

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 output schema, the description legitimately must describe return shape, and it does so thoroughly for the mergeability and conflict-risk fields, including enum vocabularies. The auth preconditions are stated. Minor gaps remain around error behavior and how this differs from the status-summary sibling, but an agent can call it correctly from this text.

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% across all three required parameters (owner, repo, number), so the schema carries parameter meaning fully. The description adds nothing about parameter formats or constraints, which is acceptable at full coverage but earns only the baseline.

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

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

The description opens with a specific verb and resource ('Fetch the full detail record of a pull request') and enumerates what the record contains (title, body, state, branches, draft, author, timestamps) plus the conflict-probe enrichments. It implicitly distinguishes itself from list/status siblings by emphasizing full detail plus mergeable/mergeState/conflictRisk, though it never names an alternative tool 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 explicit usage condition is the authentication requirement ('Authenticated callers only, the read tool surface still works anonymously'), which is genuinely useful preconditioning. There is no guidance on when to prefer this over merjax_pr_status_summary, merjax_list_pr_conflicts, or merjax_get_diff, so the agent must infer the selection.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so 'Read-only' adds nothing. What does add value is the disclosure of behavior beyond the schema: the shape of the failure payload (failed job and step, up to 8 file:line rows linked to head sha, a 'What now?' guidance block), the `budget`/`timed_out` case that still blocks the merge, and the `{withheld, required, hint}` state plus the 'repo' scope requirement for private repos. This is meaningful operational context, though it stops short of rate limits or pagination behavior.

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 core capability is front-loaded in the opening clause and the return shape is stated compactly at the end. It is dense, with long run-on clauses and a redundant 'Read-only' sentence that repeats the annotations, but for a tool with no output schema nearly every sentence carries real payload information.

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 output schema, the description carries the burden of describing returns, and it does so explicitly ({head_sha, total_count, check_runs, required, ci}) while also covering the failure sub-payload, the withheld-logs case with its auth requirement, and the timed_out semantics. For a read-only tool of this complexity, an agent has everything needed to call it and interpret the result.

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 owner, repo and number are already documented, which sets the baseline at 3. The description adds only an indirect detail — that results are anchored to the PR's head sha — and gives no extra syntax or format guidance 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?

The description states a specific verb and resource with tight scope: 'List every check at a PR's current head — workflow runs, gates and commit statuses', and enumerates the returned fields. That scope implicitly separates it from single-run siblings like get_workflow_run or get_workflow_logs, but no sibling is named explicitly, so differentiation is inferred rather than stated.

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

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

Usage is only implied: the mention of required-check state and the merge gate's CI verdict suggests it is the tool for judging merge readiness, and the withheld-log hint points at diagnosis. There is no explicit 'use this when…' / 'use X instead' routing, and no prerequisites section, leaving the agent to infer selection among the many CI-related 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the wrapper it delegates to (branch-previews.getPreviewForBranch) and the exact failure envelope {ok:false, reason:'not enabled on this host'}, which tells the agent how to interpret a non-result. It stops short of describing the success payload shape beyond 'URL + status'.

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 with zero filler: purpose first, implementation second, failure mode third. Every sentence contributes distinct information and nothing is repeated from the title or annotations.

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 lookup with no output schema, the description covers purpose, delegation target, and the no-preview-host failure case, which is what an agent needs to call and interpret it. The remaining gaps are the undocumented owner parameter and the success return shape, both minor relative to the tool's simplicity.

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%, so the description must carry the full burden for three required parameters. It names only repo and branch as a key pair and says nothing about owner (required but unmentioned), nor about formats such as repo slug vs. name or branch naming conventions. The gap leaves one parameter entirely unexplained and adds little meaning beyond the schema's property names.

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: 'Return the branch-preview URL + status for a (repo, branch) pair.' No sibling tool covers preview URLs, and the description names the underlying capability explicitly, so an agent can identify the tool's job immediately.

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 by defining the lookup (get preview URL for a repo/branch) and explains one negative condition, the host lacking PREVIEW_DOMAIN. It gives no explicit 'use this when' framing, no prerequisites, and no comparison to any alternative path for obtaining a preview link.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description still adds real value by promising the audit trail with before/after diffs and by stating 'Never the secret', which is a key expectation about sensitive output. It stops short of describing audit-trail size, ordering, or behavior for unknown ids.

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?

Everything the agent needs is in three short clauses, with scope and return contents front-loaded and the type enumeration kept to a trailing sentence. No filler or restatement of the tool name beyond what carries information.

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

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

For a two-parameter read tool with no output schema, the description covers what is returned, what is deliberately withheld (the secret), and the authorization profile. Missing only edge behavior such as not-found handling and audit-trail pagination/size.

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

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

Schema coverage is 100%, and the description's type enumeration (pat/glc_, repo/gcft_, deploy/gcdt_) is essentially a verbatim repeat of the `type` property description, so it adds little beyond the schema. The only genuine addition is the note that ids come from merjax_list_tokens, which justifies the baseline 3 rather than lower.

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?

It identifies a single token resource retrieved by type and id, and specifies the payload as 'everything list shows plus the audit trail (create, edits with a before/after diff, rotations, revocation)'. The retrieval verb is only implied by the phrasing rather than stated, and the sentence opens with a fragment, but the resource and return contents are unambiguous against siblings like merjax_list_tokens or merjax_rotate_token.

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 parenthetical '(from merjax_list_tokens)' explicitly routes the agent to enumerate ids via the sibling tool first, and 'Same scopes as merjax_list_tokens' tells the agent the permission profile matches that sibling. It does not state exclusions, e.g. that mutation operations (rotate/revoke) belong to other tools, so it falls short of full when/when-not 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?

Annotations already cover readOnly, idempotent, non-destructive and closed-world, so the description's added value is the auth constraint (admin-scoped token for org variables) and the failure mode (not-found raises an error rather than returning empty), plus the explicit return shape. That is real context beyond the annotations, though encryption/masking of the value is not discussed.

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 tight sentences: action first, scope rules second, failure and return shape last. No filler, and the most decision-relevant information (scoping) is front-loaded.

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

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

For a five-parameter read tool with no output schema, it covers action, scope resolution, auth requirement, error behaviour and the returned fields – everything needed to call it correctly and interpret the result.

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; the description exceeds it by stating how parameters combine – which fields form each scope and that org replaces owner. The schema itself only says "omit when passing org" on the owner field, so the combination rules are genuine added meaning.

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?

"Read one Actions variable by name" gives a specific verb (read) and a single, bounded resource, and the phrase "one ... by name" implicitly separates it from merjax_list_variables and merjax_set_variable. No sibling is named explicitly, so it stops short of the top mark.

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 spells out the exact scope combinations that select each variant: owner+repo for repository scope, owner+repo+environment for environment scope, org alone for organisation scope. It also flags the admin-scoped token prerequisite for the org path and that a missing variable is an error, though it never says when to prefer merjax_list_variables instead.

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

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

Annotations already declare readOnlyHint/destructiveHint, yet the description adds substantial behavior beyond them: 'repo' scope / write:repo OAuth requirement, per-token audit logging, masked logs, truncation with a `fullLog` artifact fallback, and the rule that repository tokens are not accepted on /mcp. That is exactly the auth, audit and data-truncation context an agent cannot get from the schema.

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?

Purpose is front-loaded in the first sentence, but the body is one dense paragraph with deeply nested parentheticals covering the flaky/known/infra/new taxonomy and forensic metadata. That content is needed given there is no output schema, yet it is packed into a wall of text rather than separated into readable structure.

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

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

With no output schema, the description carries the return-shape burden and does so thoroughly — run metadata, per-job/per-step status, failedSteps, testFailures and fullLog are all defined. Gaps remain around failure modes (unknown run_id, non-unique prefix) and any size/pagination limits on returned logs.

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 60% (owner and repo are undocumented), so the description must compensate. It does so by explaining the interaction the schema omits: full per-job logs only when neither `step` nor `tail_lines` is given, plus `step` accepting a name or 1-based position and `tail_lines` capping at 5000 lines. The owner/repo parameters still carry no added meaning.

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 opening sentence gives a specific verb and resource ('Return a workflow run's logs plus a failure summary') and the 'JSON-friendly companion to the ZIP-download endpoint' line scopes it against a non-MCP alternative. It never names a sibling such as merjax_get_workflow_run or merjax_explain_failure, so an agent still has to infer the boundary against those.

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 gives clear conditional usage internally: passing `step` returns only that step's output, `tail_lines` keeps the last N lines, and full per-job logs are returned only when neither is supplied. It also spells out the credential path for read-only CI audit (ci-audit preset or REST endpoints). It stops short of excluding any sibling tool explicitly.

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 cover the read-only safety profile, so the description is free to spend its words on behavior: it explains which fields appear conditionally (queueReason, queue, coalescedFires/coalescedNote, retryOf/retriedAs) and why. That gives the agent real insight into how run state maps to returned data, though it omits any mention of auth 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?

The core purpose is front-loaded in the first sentence, but the bulk is a dense enumeration of conditional output fields that reads closer to an output schema than to guidance. It is not padded with filler, yet the balance is skewed toward field listing.

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 output schema, documenting return fields is genuinely necessary and the description does so thoroughly. However, it leaves owner/repo semantics and any sibling routing unaddressed, so it is complete on returns but incomplete elsewhere.

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%: run_id is documented ('id, or a unique leading part of it, 8+ hex characters') but owner and repo have no schema description, and the description says nothing about any parameter. With low coverage the description should compensate for owner/repo semantics and does not.

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: 'Fetch a workflow run's metadata + status,' and adds that it mirrors GET /api/v2/repos/.../actions/runs/:id, which pins down exactly what is retrieved. It does not explicitly contrast with siblings like merjax_list_workflow_runs or merjax_get_workflow_logs, 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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The description never tells the agent to prefer this over merjax_list_workflow_runs when scanning or over merjax_get_workflow_logs when logs are needed; usage is only inferred from the verb.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's closing 'Read-only' merely echoes them. Beyond that, it discloses genuinely useful behavior: data comes from live git and CI rather than documentation, results are conditional (the capacity plan block only appears when docs/plans/capacity-plan.json exists), build drift is reported only when the repo is the one this Gluecron instance serves, and plans are capped at 10.

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 opening clause is well front-loaded, but the body is one sprawling sentence chained with semicolons and nested parentheses, which makes it hard to scan for a specific return field. The content is largely justified by the lack of an output schema, but the packaging could be restructured into a bulleted list of returned sections without losing information.

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 output schema and a broad aggregate surface, the description correctly takes on the job of enumerating every returned section, including the conditional plan/plans blocks. It is nearly complete for an orientation tool; the only softness is that the plans/idPrefix behavior and the ordering semantics of blockers ('most urgent first') are stated so densely that an agent may need a second read.

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 owner, repo and merged_since_hours are already documented in the input schema. The description restates the 48-hour default for merged_since_hours and adds that plans are read with each ledger's declared idPrefix (default CAP, at most 10), which is contextual rather than parameter-level detail. Under the 100%-coverage baseline, 3 is the correct ceiling here.

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 clear framing: 'the live state of a repository, read from git and CI rather than from a handoff doc', which states the resource and its authoritative-source angle. It then enumerates the exact sections returned (summary, blockers, CI per workflow, build drift, open PRs, merged PRs, queue, plan/plans), so an agent knows precisely what it gets. It stops short of naming which specific sibling tools (e.g. merjax_ci_health, merjax_pr_status_summary) it supersedes when a narrower query is wanted.

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?

'Start here when picking up work' gives an explicit entry-point cue for the fresh-session/orientation case, which is the key when-to-use signal. What's missing is the inverse: no statement of when a narrower sibling (ci_health, pr_status_summary, list_prs) is the better call, so an agent must infer that this tool is the heavyweight aggregate option.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds substantially beyond that: single-ref scope per call, the mirror namespace it writes into, idempotent upsert behavior on re-import, audit logging, and the returned fields including previousSha. For a write tool with no output schema, this is close to the full behavioral picture an agent needs.

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

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

Front-loads the access precondition and the core action, then layers rationale, idempotency, and return shape in short declarative clauses. No filler; every sentence carries either a constraint or a consequence the agent would otherwise have to guess.

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?

Despite having no output schema, the description enumerates the return object keys, and it covers auth, ref scope, mirror destination, and re-import behavior for a 3-parameter mutation tool. Nothing material is missing for a correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by constraining ref to one tag/branch/full SHA and by showing how `action` (as written in workflows) maps to the mirror path. The upstream_url override is left to the schema, which already documents its default, so this stops short of a 5.

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 (import), a specific resource (a third-party GitHub Action at exactly one ref), and the exact destination (gluecron-actions/<owner>--<repo>). It also explains the downstream effect in workflow terms (`uses: owner/repo@ref`), so the agent can distinguish this from any other mutation sibling without opening a schema.

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

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

Gives the prerequisite (site admins only, 'admin'-scoped token), the condition that motivates use (workflow runs never fetch from github.com, so an unimported action is skipped), and the re-import semantics for refreshing an existing ref. That is explicit when-to-use plus the operational consequence of not using it.

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