Gluecron

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes beyond that by disclosing that a null lease is returned when another agent holds an active lease, and by stating the write-access prerequisite. It stops short of explaining expiry/renewal semantics beyond what the schema's duration_ms already says.

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 with the core action and constraint front-loaded, no filler. Dense enough to be a little packed, but 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 6-parameter coordination tool with no output schema and minimal annotations, the description covers the write prerequisite, the return semantics (null on contention), and addressing modes. Missing only a pointer to the release counterpart and lease-expiry expectations, which are minor relative to what's covered.

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 83%, so the schema already documents target_id, duration_ms, target_type, owner, and repo. The description usefully synthesizes the two target-addressing patterns, but mostly restates format information the schema provides, so it sits at 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?

Names a specific verb (acquire) and resource (exclusive lease) scoped to PRs, issues, branches, or file paths, and states the precondition 'in a repository you can write.' It's clearly distinct from the sibling gluecron_release_lease, though it never names that counterpart 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?

Explains the two addressing modes (owner+repo with a bare key, or target_id '<repository id>:<key>') and ties the tool to 'one of your agent sessions.' It gives clear invocation context but does not say when to prefer this over, or pair it with, the release counterpart, nor when to avoid leasing.

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. Description adds scoping and default behavior but does not disclose return format, data freshness, or other behavioral traits like 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?

Description is concise (two sentences) and front-loaded with the core purpose and scope options. No wasted words.

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 is provided, and the description does not explain the rollup structure (fields, time period). The agent lacks full context to interpret the return value appropriately.

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 25%. Description adds meaning by explaining how to combine scope, repo, owner, and agent_session_id. However, it introduces 'user_id' which is not a parameter in the schema, potentially causing confusion.

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

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

The description clearly states it returns AI spend rollups and specifies scope options (user, repo, agent). It distinguishes itself from sibling tools that perform mutations or unrelated queries.

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 instructions on how to scope by user, repo (owner+repo), or agent_session_id, and notes default behavior. Does not explicitly mention when not to use or alternatives, but sibling tools are sufficiently distinct.

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 far beyond the annotations (readOnlyHint=false, destructiveHint=false): discloses server-side `git apply --cached` against branch head, branch creation from `base_branch`, blank-context-line restoration, compare-and-swap semantics, branch protection/ruleset/secret-scan enforcement, CI/webhook firing, 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-loads the core purpose and keeps every sentence information-bearing with no filler. However, it is one dense parenthesis-heavy paragraph, and a bulleted split of format rules vs side effects would be easier to scan.

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 tool with no output schema, the description covers the safety/side-effect profile, permission scope, size limit, failure-relevant CAS behavior, and even enumerates returned fields. 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 71%, and the description reinforces/interprets key parameters: `message` required vs ignored by format, `expected_head_sha` all-zeros meaning 'branch must not exist', and `base_branch` as the fork point. It adds interaction semantics beyond the schema, though much of it partially duplicates 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 ('Commit a patch to a branch') and immediately distinguishes the mechanism from alternatives: 'without sending whole files — the way to change a few lines of a large file.' An agent can tell it apart from write_file / atomic_multi_file_commit without opening schemas.

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 precisely when each input format applies: unified diff = one commit with `message` required, format-patch mbox = one commit per patch with own message/author and `message` ignored. The 'change a few lines of a large file' framing implies when to prefer it over whole-file writes, but sibling tools are never named as alternatives.

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 added weight: it explains the review counts toward branch protection's required approvals, that it clears the caller's own earlier request for changes, the auth/scope requirements, and the open-PR/author constraints. This is exactly the behavioral context annotations cannot convey.

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

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

Dense but front-loaded: the core action leads, followed by equivalence/effect, preconditions, permissions, the alternative tool, and the return shape. Every clause adds decision-relevant information with 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?

Although there is no output schema, the description supplies the return shape ({reviewId, number, state, url}), and covers preconditions, permissions, side effects, and the sibling alternative. Nothing needed to invoke or select the tool 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 (including the Markdown nature of body). The description adds no per-parameter syntax or format detail beyond the schema, so 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?

States a specific verb+resource ('Approve a pull request') and immediately disambiguates by naming the sibling alternative gluecron_request_changes. It also clarifies the semantic meaning of the action (records an 'approved' review, same as the web form/POST endpoint), so an agent can distinguish it from close_pr, merge_pr, or dismiss_review.

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: the PR must be open and its author cannot approve it. It names the alternative tool (gluecron_request_changes) and states the inverse case. Requirements (write access and 'repo' scope) are spelled out, leaving little 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), it discloses concrete behavioral traits: a hard cap of 10 assignees per thread, the constraint that only repo readers can be assigned, the required 'repo' scope plus write access, and the exact return shape. These are meaningful operational facts not present in structured fields, and idempotentHint is consistent with the assign semantics.

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 reverse mode, then layers constraints, parameters, and return shape efficiently. It is dense and slightly packed with migration trivia, but essentially every clause carries 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 mutation tool with no output schema, the description covers permissions, limits, parameter conventions, and the response structure, and the annotations cover the safety profile. An agent has everything required 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?

Schema coverage is only 57%, but the description compensates by explaining the assignee-vs-assignees alternative, the type default ('issue' or 'pull_request'), and the remove flag. The three required params (owner, repo, number) are self-descriptive by name, so little is left ambiguous.

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

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

States a specific verb (assign/unassign) and resource (users on an issue or PR), and the parenthetical 'remove: true' immediately disambiguates the reverse operation. It is clearly separable from siblings like gluecron_label_issue and gluecron_comment_issue 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?

Explains the in-tool branch (remove: true to unassign) and the migration away from `assignee:<username>` labels, giving clear operational context. It does not, however, name an alternative tool or an explicit when-not-to-use condition, so it stops short of full routing guidance.

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

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

Goes well beyond the annotations: it discloses the underlying blob/tree/commit/ref-update sequence, that branch protection/rulesets/secret scan apply as with a push, that CI/webhooks fire, that the branch is created if missing, and the required 'repo' scope. This is exactly the behavioral context an agent needs for a mutation 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?

Front-loaded with the core action and the change-entry format early; every sentence carries information. The parenthetical 'The killer agent tool' is marketing filler that adds no selection value, costing a point.

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-required-param mutation tool with no output schema, the description covers mechanics, safety gates, side effects, and auth scope. It omits conflict/non-fast-forward behavior and what the response returns, but those are minor gaps given the coverage provided.

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 33% schema coverage, the description compensates by documenting the shape of each `changes` entry ({path, content?, content_base64?, deleted?}) and the branch-creation semantics tied to `base_branch`. The remaining params (owner, repo, branch, message) are self-evident, so this is close to complete.

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 (apply), resource (file writes + deletes as one atomic commit), and scope (on a branch, creating it if absent). This clearly distinguishes it from single-file siblings like gluecron_write_file, gluecron_delete_file, and gluecron_create_branch.

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 'single atomic commit' framing plus branch-creation behavior gives clear context for when this tool is the right choice over per-file writes. It never explicitly names an alternative or states exclusions, 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 (readOnlyHint=false, destructiveHint=false) only signal a non-read, non-destructive call. The description goes well beyond: it names the required admin scope, discloses that queueing is picked up within 15 minutes and audit-logged, and explains the RED-vs-healthy interpretation rule. That is substantial context the structured fields do not 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?

Dense but front-loaded: the admin restriction and the core purpose lead, then the health criteria, then the trigger and return shape. Every clause carries information, though the single long paragraph is heavier than ideal for scanning.

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 contract itself, listing {health, reasons, targets, problems, schedule, runs, started?} and the RED-state semantics. Combined with the auth, trigger, and timing details, an agent has everything needed to call and interpret 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 coverage is 100% and there is only one parameter, so the baseline is 3. The description adds real meaning beyond the schema by explaining the consequence of setting start (queued for the worker, 15-minute pickup, audit-logged) rather than just restating the enum values.

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 resource (backup and restore-drill health) with concrete facets: newest backup set verification/age, Object Lock immutability, drill pass history, worker liveness, targets, schedule and runs. No sibling tool touches backups, so it is trivially distinguished. An agent knows exactly what this returns before 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?

Gives prerequisites (admin-scoped token) and a clear trigger action: pass start: 'backup' or 'drill' to queue work, with the 15-minute pickup window noted. It does not state explicit when-not-to-use conditions, but no alternative backup tool exists to route against, so this is close to complete.

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 readOnlyHint=false, so the bar is lower. The description adds genuinely new context: which run states are eligible (queued/running) and the required OAuth scope, both of which affect whether the call will succeed.

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, front-loaded sentences with no filler; the action and its prerequisite come first. It is efficient, though arguably too terse for a destructive mutation.

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 annotations covering the safety profile and no output schema, the essentials are present. However, it says nothing about idempotency, effect on the run's jobs, or the meaning of two of the three parameters, leaving real 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 documented with a useful leading-hex-part hint, but owner and repo carry no meaning in either schema or description. The description's mention of 'repo scope' refers to OAuth scope, not the repo parameter, so it does not compensate for the 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 (cancel) plus the resource (workflow run) and narrows the scope to 'queued/running', which distinguishes it from read-oriented siblings like get_workflow_run and get_workflow_logs. It does not name any sibling explicitly, 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?

The only guidance is a prerequisite ('Requires repo scope'), which tells the agent about auth but not when to choose this over alternatives or when not to use it. Usage is implied by the verb 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?

The description goes well beyond the annotations by disclosing the failure behavior: if the AI service does not answer, it fails with a JSON-RPC error carrying {chat_id, ai_error} instead of returning apology copy. It also states that the tool returns the assistant's reply, which is not derivable from the readOnly or destructive flags.

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

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

The description is two tight sentences that front-load the core action, then add return-value and error-disclosure information. Every sentence adds value and there is no redundant filler.

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

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

For a two-parameter tool with no output schema, the description covers what it does, what it returns, and how it fails. It does not explain how to obtain chat_id or explicitly connect to the sibling gluecron_chat_with_repo, but 'existing repo chat' is enough context for invocation in most cases.

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

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

The schema provides only names and types with zero description coverage, but the description compensates by characterizing chat_id as the identifier of an existing repo chat and message as the content of the follow-up message. Given only two simple string parameters, this is sufficient semantic guidance, though it could explicitly name the 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?

The opening phrase 'Send another message to an existing repo chat' names a specific verb, resource, and continuation scope, which clearly distinguishes it from starting a new chat such as gluecron_chat_with_repo. It also states the return value, the assistant's reply.

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?

'Another message to an existing repo chat' clearly implies this is the continuation tool, for use after a chat already exists, which separates it from sibling gluecron_chat_with_repo. It does not explicitly name the alternative or state a when-not-to-use condition, so it falls one step short of fully explicit 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?

The description reveals several non-obvious behaviors: it creates and persists a chat row, streams the reply, returns {chat_id, reply}, fails via JSON-RPC error with {chat_id, ai_error} instead of apology copy, and requires authentication. This adds substantial context beyond the annotations (readOnlyHint=false, destructiveHint=false), with no 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 description is three tight sentences: purpose/action first, return value second, failure behavior and auth third. Every sentence earns its place, with no repetition or 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?

Without an output schema, the description explains the return shape and error behavior. It covers authentication and persistence. Missing items are explicit definitions for owner/repo and any rate-limit or streaming specifics, but for a moderately complex chat-start tool this is largely complete.

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

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

Schema coverage is 50%, and the description only clarifies 'message' as the first user message. The required parameters 'owner' and 'repo' are not semantically explained beyond the tool name's reference to 'repo'; 'title' is covered in the schema. This partially compensates for the gap but leaves required parameters under-documented.

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: 'Start a new chat with a repo', then details the actions: creates a chat row, sends the first user message, streams and persists the reply. This clearly distinguishes the tool from siblings like gluecron_chat_continue (new vs. continue) and explain/agent-session tools.

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

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

The description gives clear context that this is for starting a new chat, implicitly separating it from continuing an existing chat (gluecron_chat_continue). It does not explicitly name alternatives or state 'when not to use', so it falls short of a 5, but the intended usage is 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 mark readOnlyHint=false and destructiveHint=false, so the mutation capability is flagged, but the description adds real context beyond that: the write requires admin scope, is audited, and the response then carries `saved`. It also explains the holdReason semantics and the in-process/external precedence rule, which annotations do not cover.

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, but the body is a dense run-on paragraph dense with parentheticals and jargon ('declaration and its source', 'CI_EXECUTOR on the box'). It is information-rich yet hard to scan, so structure is only adequate.

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 response burden and does so reasonably: it names the returned fields (mode, declaration, source, runners, lastSeenAt, state, holdReason, saved, per-runner rows). It stops short of describing pagination/format but is otherwise complete for both the read and admin-write paths.

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 goes further: it explains that `declare` sets the estate-wide setting with enum values external/in-process/auto, that omitting it is read-only, and that the write is audited and returns `saved`. That is meaningful added context over 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 opening 'Where CI runs and why' plus the enumerated fields (mode, declaration, source, runners, state, holdReason) clearly frame this as a CI executor status/configuration tool. It is distinguishable from siblings like gluecron_ci_queue_status and gluecron_list_runners, though it never explicitly contrasts itself with 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 notes that site admins (admin scope) may pass `declare` to write the estate-wide setting, and that in-process never runs while external runners are configured, which is useful context. However, it gives no explicit when-to-use-this-vs-alternative routing (e.g. vs list_runners or ci_queue_status), leaving the agent to infer usage.

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

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

Annotations already declare read-only/non-destructive, and the description's 'Read-only' merely repeats that. What it does add is auth behavior—site admins get the extra `dashboard` block—plus precise metric definitions (e.g. runner_slow, compute_trigger firing conditions) that help interpret results.

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

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

The description is a single dense run-on sentence enumerating dozens of return fields, with the auth-scope caveat buried mid-paragraph. It is neither front-loaded nor scannable, and several clauses ('each day', 'a cost only where...') are awkward 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?

With no output schema, the field inventory is the only return-value documentation, and it is thorough, including per-field `source` provenance and admin-only sections. It still omits response shape/format details, but for a zero-parameter read tool it is close to sufficient.

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 implies no input is needed, and there is nothing parameter-related for it to clarify.

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 names the resource ('CI health') and pins it to concrete endpoints, so an agent knows it retrieves CI health metrics. However, it never uses a verb and never distinguishes itself from siblings like gluecron_ci_queue_status or gluecron_ci_executor, leaving overlap ambiguous.

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 when-to-use guidance and no comparison to the many CI-related siblings. The only conditional information is the admin-scope gating of `dashboard`, which describes access rather than task 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 declare readOnlyHint=true and destructiveHint=false, and "Read-only" merely restates that. The description does add real context beyond annotations: the `holdReason` when no runner can take a run, the `explanation` codes for why a run waits, and the note that this is the same `ciQueue` block the write tools return. It omits auth/permission requirements and any 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?

It is front-loaded with the purpose, and the length is partly justified because there is no output schema to carry the return-value detail. However, it is essentially one enormous run-on sentence stitched together with em-dashes and parentheticals, which makes it hard to scan for the single fact 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?

With no output schema, the description carries the full burden of describing returns and does so thoroughly — levels, counts, slots, ETA, per-repo scoping, work-class breakdown, recommendation, and executor/holdReason states. Combined with annotations covering the safety profile and 100% param coverage, an agent has everything needed to call 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?

Schema coverage is 100% and both params are optional, so the schema baseline applies. The description still adds meaning: it explains that supplying owner+repo switches the response to that repository's runs, its share of CI work, the slots it may hold, a recommendation, and per-run wait explanations — detail the terse schema strings do 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 opening clause states a specific resource and scope: reporting how full the shared CI queue is, with level, queued/running runs, slots and ETA. It is clear what the tool does, but it never explicitly distinguishes itself from the close sibling `gluecron_ci_executor`, which the description also folds in as an `executor` output block.

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 concrete use case: "Ask before a burst of pushes," and frames the tool as answering "what to do about it." There are no exclusions and no named alternatives, so it stops 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 declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by specifying the returned fields, the credential-helper hint, and that the repo's stored casing is preserved. This goes beyond the annotations and helps set expectations for the response.

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

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

Three concise sentences each earn their place: the core action, the important security/usage guidance, and the exact return shape. No filler or redundancy, and the most important information is front-loaded.

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

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

For a simple read-only lookup tool with 100% schema coverage and annotations for safety, the description is complete. It names the parameters, the output fields, and the key behavior about stored casing. With no output schema present, the explicit return shape sufficiently fills that gap.

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

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

Schema description coverage is 100% for both required parameters, so the schema already fully documents owner and repo. The description does not add additional parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns an authenticated HTTPS clone URL for a repo, along with a credential-helper hint. The verb 'Return' plus the specific resource and output fields make the purpose unambiguous and distinct from the sibling tools.

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

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

The description explicitly instructs when to use this tool: when a clone URL is needed and to avoid embedding tokens in URLs. It does not name an alternative tool or provide when-not-to-use conditions, but the guidance is clear and actionable for the primary use case.

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

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

Annotations already indicate idempotency and destructive intent; the description adds value by spelling out the authenticated-write-access requirement, the concrete no-op behavior on already-closed issues, and the return shape. No contradiction with 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?

Three short, information-dense sentences with no filler. The core action is front-loaded, and each supporting sentence covers a distinct useful behavior: auth, idempotency, and return 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?

Given the low complexity and rich annotations, the description covers the essential behavioral context. It could be slightly more explicit about the actual content of the returned state (e.g., 'closed'), but the tool remains fully callable without that detail.

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

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

The schema already documents all three parameters with 100% coverage, so the description need not repeat parameter details. It adds no extra parameter semantics beyond the schema, which matches the baseline for full 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?

The description states a specific action ('Close') on a specific resource ('open issue'), making the tool's purpose immediately clear. The name and description also naturally distinguish it from close_pr and reopen_issue.

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 useful context by noting that authenticated write access is required, which is a prerequisite. However, it does not explicitly discuss when to prefer this tool over alternatives like close_pr or when not to use it.

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

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

The description adds the auth requirement and return value ({state}) beyond what annotations provide. It also states 'without merging,' which clarifies behavior. The idempotent claim is redundant with annotations, but the extra context about auth and return is valuable. No contradiction with annotations.

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

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

The description is a single sentence that front-loads the primary action, then provides necessary context (auth, idempotency, return). It is concise, with no filler words, and every clause adds value.

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

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

For a simple 3-parameter tool with no output schema, the description covers the essential aspects: purpose, auth, idempotency, and return value. It doesn't discuss error handling (e.g., if PR is already closed), but that is not critical for a basic tool. The information is sufficient for an agent to call 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?

Schema description coverage is 100%, so the schema already documents all three parameters (owner, repo, number). The description does not add any additional parameter-specific meaning, so it meets the baseline for high coverage without further 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?

The description clearly states the action: 'Close an open pull request without merging.' It specifies the resource (pull request) and the distinguishing condition (without merging), which differentiates it from merge_pr and close_issue. The verb 'close' is specific and unambiguous.

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

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

The description implies the use case by saying 'without merging,' which contrasts with merge_pr, but it doesn't explicitly name alternatives or state when not to use it. It does provide a prerequisite ('Requires authenticated caller with write access'), which gives context but not explicit exclusions.

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

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

Annotations already indicate a mutating but non-destructive operation. The description adds useful context beyond annotations by disclosing the write-access requirement and the return payload {commentId}. It does not cover side effects in detail, but with annotations present and a simple action, this is sufficient.

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

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

The description is three short sentences, each earning its place: action, auth prerequisite, and return value. It is front-loaded with the core purpose and contains 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 4-parameter action with fully documented schema and clear annotations, the description covers the essential missing information: auth requirement and return shape. There is no output schema, but the {commentId} mention fills that gap. Nothing needed to invoke the tool 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 description coverage is 100%, so all four parameters are already documented in the schema. The description adds no new parameter-level detail; it only mentions the return value. This meets the baseline but does not exceed it.

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: 'Add a comment to an existing issue' (comment, issue). It clearly distinguishes this from sibling tools like gluecron_create_issue (creation), gluecron_close_issue (state change), and especially gluecron_comment_pr (pull request comments) by scoping to issues.

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 usage context: use it for existing issues, and it states the prerequisite of an authenticated caller with write access. It does not explicitly name alternatives or exclusions such as 'use comment_pr for pull requests,' 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 indicate this is not read-only and not destructive. The description adds meaningful context beyond annotations by requiring authenticated write access and revealing the return shape as {commentId}. This gives the agent useful behavioral expectations without contradicting the annotations.

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

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

The description is one tight sentence that front-loads the core action, then adds the two most important operational facts: auth requirement and return value. There is no filler or redundant restatement of the title or schema.

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

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

For a simple four-parameter mutation with no output schema, the description covers the essential context: action, auth requirement, and return value. It does not discuss error cases or rate limits, but the operation is simple enough that this is not a critical gap.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description adds no extra parameter-level detail, which is acceptable given that the schema already carries the semantic load. A baseline score of 3 is appropriate.

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

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

The description states a specific verb-resource pair: add a comment to a pull request. It clearly distinguishes this from the sibling gluecron_comment_issue by naming the target resource (pull request), so an agent can choose correctly without opening schemas.

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 makes the primary use case obvious and adds a prerequisite: authenticated write access. It does not explicitly mention alternatives for commenting on issues, but the purpose itself and the sibling naming provide enough context for this straightforward operation.

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 past the annotations: the commit runs through the push gates so CI executes before anything merges, both shas are compare-and-swapped so a moved branch is refused with nothing changed, and the call emits `Conflict-Resolution:` trailers plus a gluecron[bot] comment. It also discloses the auth requirement (write access and 'repo' scope), which annotations do not cover.

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 action and the critical scope constraint ('never on the base branch') in the first sentence, and every later clause carries distinct information (gates, CAS, side effects, auth). It is dense and long-ish, but no sentence is filler.

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

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

For a complex mutation with no output schema, the description supplies everything an agent needs: where the commit lands, what prerequisite resolution state is required, the concurrency-failure mode, the side effects, and the permissions needed. Nothing material is implied only by the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `base_sha`/`head_sha` are compare-and-swap guards, not just IDs, and `resolutions` is an alternative supply path to saved drafts with merge-rule fallback for settled files. The enum values and content requirement are left 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 (commit) and resource (saved PR conflict resolutions) plus precise scope: it lands on the PR HEAD as a two-parent merge commit and never on the base branch. That scope line alone separates it from gluecron_merge_pr and gluecron_resolve_pr_conflict.

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 precondition for calling it – every unresolved file needs a draft from gluecron_resolve_pr_conflict or an entry in `resolutions` – and names that sibling explicitly. It stops short of stating when *not* to use it (e.g. against a non-conflicted PR or before drafts exist), so it isn't a full when/when-not pairing.

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, leaving the auth and secret-handling burden to the description — and the description delivers: 'admin' scope required, and the token is returned exactly once and must be stored. That one-time-secret behavior is a critical trait an agent could not infer from structured fields.

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 caveat, then the auth requirement. Every sentence earns its place with 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?

With no output schema, the description correctly supplies the key return fact (single-use plaintext token) rather than leaving it unknown. Parameter semantics are fully covered by the schema. Minor gap: it doesn't say what a session is subsequently used for, but nothing needed to invoke 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 description coverage is 100%, so all four parameters (name, repository_id, branch_namespace, budget_cents_per_day) are already documented in the schema. The description adds no parameter-level detail beyond the auth scope, so 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?

States a precise verb+resource ('Mint a new agent-multiplayer session') that is clearly distinct from the many create_* siblings (create_branch, create_issue, create_pr) — none of those produce a session token. An agent can route to it 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 gives a hard prerequisite ('Requires admin scope'), which is genuinely useful for deciding whether the call can succeed. However, it never says when to prefer this over alternatives or what condition triggers session creation, so usage is only implied.

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 the gating behavior (rulesets, secret scan of unreachable commits), CI/webhook side effects, and required 'repo' scope. This is rich context an agent needs before invoking. It does not contradict 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?

Three tight sentences with zero filler; behavioral constraints and the response shape are front-loaded and each clause does distinct work.

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

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

Given no output schema, the description usefully declares the return shape {ref, sha}, covers auth scope, side effects, and gating. It falls short on when-to-use guidance and does not document the owner/repo parameters, but overall it is complete enough for correct invocation.

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

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

Schema coverage is 50%; owner and repo lack descriptions while sha and branch are documented in the schema. The description adds only marginal parameter context (existing sha target, short-form branch name), with no format or constraint details beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Create a new branch ref') and clarifies the target is an existing sha, plus maps to the underlying API endpoint. This distinguishes it from sibling write tools like gluecron_apply_patch or gluecron_create_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?

The description explains what happens when the tool runs (gating, CI) but provides no explicit when-to-use vs alternatives guidance. There is no mention of when a branch should be created versus using gluecron_create_pr, gluecron_fork_repo, or other ref-manipulation tools.

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?

Discloses rich behavior beyond the annotations: no token returned by default, single-use URL expiring in 60 s, 2 h default lifetime, permission/scope requirements, audit logging, rotation of the secret on each exchange, and refusal of deliver:'token' for push access. 'Read-only by default' refers to token scope, not the minting operation, so it is consistent with readOnlyHint=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?

Front-loads the purpose and the surprising default (returns NO token), then layers the operational detail. Dense but almost every sentence earns its place; the backticked field lists make it slightly busy but not wasteful.

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

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

For a 7-param credential-minting tool with no output schema, it explains the return shape (id, exchangeUrl, gitConfig, url), the gitConfig usage flow, expiry, permissions, and revocation. An agent has everything needed to call it correctly and safely.

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 already 100%, but the description adds real semantics: what token_id does (fresh exchange for existing grant, rotates secret), what deliver:'exchange' vs 'token' means, and that read_only:false needs write access. This goes beyond the schema field text.

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: 'Mint a short-lived, repository-scoped HTTPS clone credential (a deploy token)', which is more precise than the tool name alone. It clearly scopes the intended consumer (sandbox/CI with no PAT). It does not explicitly differentiate against siblings like gluecron_clone_url or gluecron_create_repo_token, 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?

Gives concrete when-to-use context (has no PAT), explains the token_id redemption path, and routes revocation to gluecron_revoke_token. It does not compare against the other token/clone-url siblings, so the alternative-selection guidance is incomplete.

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

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

The description adds useful behavioral detail beyond the annotations by disclosing the authentication and authorization requirement and specifying the return shape as '{number, url}'. Since the annotations already indicate readOnlyHint=false and destructiveHint=false, the description's added context is meaningful, though it does not address side effects or idempotency.

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

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

The description is three short sentences and each one earns its place: the action, the access requirement, and the return value. There is no filler, repetition, or unnecessary detail.

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

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

Given that there is no output schema, describing the return as {number, url} is valuable. The description also covers the key behavioral requirement (write access) and leaves parameter semantics to the complete schema. It could go slightly further by addressing potential error cases or alternative tool routes, but it is sufficiently complete for a simple creation tool.

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

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

Schema coverage is 100%, so the parameters owner, repo, title, and body are all already described in the input schema. The description does not need to add parameter-level detail; it also does not go beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific action ('Create a new issue') on a specific resource ('a Gluecron repository'), making the tool's purpose unambiguous. It also distinguishes itself from related siblings like gluecron_create_pr, gluecron_close_issue, and gluecron_assign_issue by making clear it is specifically for creating a new issue.

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

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

The description implies the primary use case — creating a new issue — and gives a useful access prerequisite by requiring an authenticated caller with write access. However, it does not explicitly say when to prefer this tool over alternatives or when to avoid it, such as distinguishing it from creating a pull request or commenting on an existing 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 indicate this is a mutating, non-destructive operation(?). The description adds valuable behavioral detail: the required authenticated write access, the base_branch default behavior, and the return shape {number, url}. This goes beyond what annotations and schema provide.

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, each carrying necessary information: the action, the key parameter behavior, and the auth/return contract. No filler or repetition.

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

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

The description covers the core requirements, auth prerequisite, default branch behavior, and return format, which is complete enough for a tool with no output schema. It could add a brief note distinguishing from open_draft_pr, but that is more of a selection aid than a calling requirement.

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 parameters already have descriptions. The description largely repeats schema details like head_branch being required and base_branch defaulting to the repo default branch witout adding new semantic information 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: 'Open a new pull request.' It is clear and actionable. However, it does not explicitly differentiate from the sibling tool open_draft_pr, so an agent must infer that this tool is for non-draft PRs.

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 useful prerequisites: head_branch is required, base_branch has a default, and the caller needs write access. It does not explicitly compare to alternatives like open_draft_pr or merge_pr, so usage guidance is implied rather than explicit.

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 the non-read-only, non-destructive profile; the description adds substantial behavior beyond them: the token is returned exactly once, effective access is capped by the caller's current repo access and re-checked on every use, branch protection applies, and the action is audit-logged. A minor gap is that revocation/rotation lifetime management is only implied by the expiry rules rather than pointed at the revoke sibling.

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 purpose and scope before the permission and expiry rules; nearly every clause carries information an agent needs. The single dense paragraph packing purpose, auth surface, permissions, expiry, access model and return shape is harder to scan than a short structured list would be, but 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 credential-minting mutation with a nested permissions object and no output schema, the description covers prerequisites ('repo' scope), authorization semantics, expiry bounds, the grantable key set, audit logging, and an inline description of the returned fields. Nothing an agent needs to call it safely 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 the schema already carries per-parameter detail (including the runners key, which the description omits). The description still adds non-obvious semantics — that admin and settings are never grantable, and the concrete expiry format bounds (min 5 minutes, max 1 year, 'never') — which go beyond a restatement of 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?

Specific verb and resource ('Mint a fine-grained repository token (gcft_…) for ONE repository') with an explicit scope constraint and a statement of what the credential unlocks (REST v2/v3, git over HTTPS, container registry for that repo only). This is clearly separable from siblings such as create_deploy_token, create_runner_registration_token and get_token without opening their schemas.

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 guidance is present for parameter choices (when to omit expires_in, which permission levels exist, that admin/settings are never grantable), and it states the 'repo' scope prerequisite. However, it never names an alternative tool or states when to prefer create_deploy_token, create_runner_registration_token or get_token instead, leaving the selection between credential-minting siblings 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 only declare non-readonly/non-destructive; the description adds real behavioral context beyond them: one-time token, one-hour expiry, runner obtains its own long-lived credential, and that exclusive/repositories are fixed for the runner's life. It also lists the return shape despite 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?

Front-loaded with the core action, then semantics, then return value. Dense but each clause carries useful information; slightly long-sentence phrasing, but appropriate for a tool with non-obvious fixed-at-registration 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?

Given a mutation tool with no output schema, the description covers expiry, one-time nature, credential lifetime, flag effects, and the return fields — everything an agent needs to call 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?

Schema coverage is 100%, so the baseline is 3, but the description elaborates meaningfully beyond the schema: 'platform' as site-admin owner, exclusive runners never take runs-on: self/ubuntu-* and keep the account's shared lane, and repositories narrowing. This clarifies the effect of the flags, not just their types.

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) and immediately distinguishes it from sibling token/runner tools by describing the one-time register-then-long-lived-credential flow. An agent can tell exactly what it produces.

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 usage context clearly (a runner started with RUNNER_REGISTRATION_TOKEN registers once), and details when to use exclusive vs default and when to use repositories. It doesn't explicitly name a sibling alternative to avoid, but the scenario guidance is strong.

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 destructiveHint=true annotation, it discloses permissions required (write access), protections that apply (allow_deletion, rulesets, push inspection), side effects (webhooks and CI fire), audit logging, error behavior, and the exact return payload.

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 core action and the default-branch safety rule, with each sentence adding a distinct behavioral fact. It is dense but nearly every clause earns its place; the API endpoint mirror is the only borderline redundant element.

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 permissions, protection interactions, side effects, failure modes, idempotency semantics, and return shape—everything an agent needs to invoke it safely.

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/branch/expected_sha are already documented. The description restates the expected_sha compare-and-swap behavior and branch-name convention but adds little beyond what the schema already conveys, matching the baseline for high 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 (delete a branch) and anchors it to a familiar behavior (`git push --delete`). It is unambiguously distinct from siblings like create_branch, delete_repo, or delete_file.

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 conditions: the default branch is never deleted, expected_sha enables conditional deletion, and a missing branch yields not-found. It does not explicitly route to alternatives (e.g., create_branch), but the operational context is well 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 only declare destructive/idempotent/no-readOnly; the description adds material facts beyond them: edit history is destroyed too, permissions required, a missing comment returns not-found instead of a false success, and the deletion is audit-logged without comment content. That is exactly the extra context an agent needs before a destructive 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?

Five tight clauses, each adding new information — target, permissions, error semantics, route, audit behavior, return shape — with the destructive scope front-loaded. No filler or repetition of the identifier.

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 tool with no output schema, the description supplies the return shape ({id, kind, number, deleted: true}), the failure mode, audit behavior, and the upstream route. Only the nested thread parameter's role is left unstated.

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 schema carries most of the load; the description reinforces only that deletion is keyed by comment id. The nested `thread` object (kind/number) is undocumented in both schema and description, so the description does not fully compensate for the remaining 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?

Specific verb+resource ('Delete a comment on an issue or pull request') plus scope ('with its edit history') and the underlying route DELETE /api/v3/repos/:o/:r/issues/comments/:id. It doesn't name the sibling it is distinguished from (gluecron_edit_comment), but the destructive intent is unambiguous.

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

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

Provides an authorization precondition ('Its author or a repository writer only') and an error contract for missing comments, which helps an agent decide whether the call can succeed. However it never states when to prefer this over gluecron_edit_comment or what to do instead when authorization fails.

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 give destructiveHint=true; the description goes well beyond them, disclosing that the operation passes branch protection, rulesets and secret scan like a push, and that it fires CI/webhooks. It also names the required auth scope, which is exactly the behavioral context an agent needs for a destructive 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 dense sentences with the action and mechanism front-loaded, followed by requirements and side effects. No filler, every clause earns its place.

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

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

No output schema exists and the tool is a destructive mutation, so the description must stand alone; it covers side effects, auth scope and the API mapping well. It could still say what happens on a stale/mismatched sha or describe the failure response, which is the only notable gap.

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

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

Schema description coverage is only 17% (just sha), so the description must carry the load. It usefully explains the sha as the 'existing blob sha' for optimistic concurrency, but leaves owner/repo/path/branch/message entirely unexplained, so it only partially compensates 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+resource ('Delete a file from a branch') and adds the mechanism ('via git plumbing') plus the API equivalent ('Mirrors DELETE /api/v2/contents'). This clearly distinguishes it from siblings like gluecron_delete_repo and gluecron_write_file 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?

Provides concrete preconditions: the existing blob sha (optimistic concurrency) and 'repo' scope are required. It does not, however, explicitly name when to prefer an alternative (e.g., apply_patch or write_file) or state exclusions, so it stops 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 only declare destructiveHint=true and readOnlyHint=false; the description goes far beyond by disclosing soft-delete semantics (immediate disappearance from git/web/REST/MCP/CI/webhooks/search, reserved name, 90-day restorable_until window), side effects (CI cancellation, webhook delivery stop), permission model, required token scope, audit event name, owner notification, and the exact return shape. This is exactly the extra context destructive operations need.

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-dense with essentially no filler — every clause adds a fact an agent needs (soft vs hard, restore path, permissions, scope, return value). It is front-loaded with the most decision-relevant fact (soft delete). It loses a point for being a single very long run-on passage, which makes the permission/scope details harder to scan than a short bulleted structure 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?

There is no output schema, so the description supplies the return contract itself ({deleted, soft, id, restorable_until}) plus the restore deadline. Combined with permissions, scopes, and side effects, nothing material is missing for a destructive, non-idempotent tool with no structured return metadata.

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% — both 'repo' and 'owner' are documented in the schema itself. The description only adds ownership context ('the personal owner, or an org owner for an org repository') which is about authorization rather than argument format, so the schema still carries the parameter burden. Baseline 3 is appropriate.

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

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

States a specific verb (delete) and resource (repository) and immediately qualifies it as a SOFT delete, which is the key distinction from the other deletion-flavored siblings (gluecron_purge_repo). An agent can tell exactly what happens and how it differs from purge without opening 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?

Explicitly routes the agent to alternatives and conditions: use gluecron_restore_repo to undo within the window, use gluecron_purge_repo to remove permanently before the window expires. It also states the authorization precondition (repository owner or site admin; admin collaborators and org admins refused) and the required 'admin' token scope, which is the deciding factor for whether the call will succeed.

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 past the annotations, which only flag destructive and idempotent. The description discloses the concrete idempotent response semantics (deleted:false, already_deleted:true), the downstream effect on workflows, required permissions (admin + 'repo' scope), and audit logging limited to the name.

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 action and target, then layers idempotency, side effects, permissions, and return shape in compact clauses. No filler or restatement of the schema, and each 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?

Despite no output schema, the description summarises the return object ({repository, name, deleted, already_deleted, at}) and covers permissions, audit behaviour, and downstream impact. Nothing an agent needs to call this destructive tool 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% and defines owner/repo/name adequately, so the baseline is 3. The description adds real meaning beyond the schema by explaining how the name value is normalised (cron_secret read as CRON_SECRET), which affects what callers should 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 and resource with scope: 'Delete one workflow secret from a repository by name'. It is immediately distinguishable from siblings list_repo_secrets and set_repo_secret, and even clarifies the name-normalisation rule (cron_secret -> CRON_SECRET).

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: retries are safe because deletion is idempotent, and workflows referencing the secret stop receiving it. It does not explicitly name alternative tools (set_repo_secret, list_repo_secrets) or state exclusions, so it stops short of the when/when-not/alternatives bar.

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 destructive=true and idempotent=true, yet the description adds what the agent actually needs: a missing variable is a not-found error and never falsely reported as deleted, the operation is audit-logged, and the org path needs an admin-scoped token. That is real behavioral context beyond the annotation set.

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, front-loaded with the action, then scope routing, then the error/idempotency guarantee, then the return shape. 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?

With no output schema, the description supplies the return shape ({name, deleted: true}), the auth requirement, the scope-selection contract, and the not-found failure mode. Nothing material for correct invocation 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 baseline is 3, but the description adds the combination semantics the schema lacks: which parameters pair to select which variable scope, and that org needs elevated auth. It only omits the fact that `id` can be supplied instead of `name`, so the 'by name' phrasing under-describes the alternate key.

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 ('Delete an Actions variable by name') and immediately scopes it by the three variable tiers. The delete verb cleanly separates it from the get_variable/list_variables/set_variable siblings 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?

Gives concrete when-to-use routing: owner+repo for repo variables, owner+repo+environment for environment variables, org for organisation variables, plus the admin-token prerequisite for the org case. It stops short of naming alternatives or stating when not to use it (e.g. use set_variable to update 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 only declare readOnlyHint=false and destructiveHint=false; the description adds real behavioral context beyond that: the required 'repo' scope, the write-access prerequisite, and that the reason is audited. It stops short of describing reversibility or the response, so it is not a full 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?

Two tight sentences: the action and its scope come first, the prerequisites and audit note second. No filler, and the parenthetical efficiently captures the two scoping modes.

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

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

For a mutation tool with no output schema, the description covers effect, scoping, prerequisites, and the audit trail on the required reason. Only the return/confirmation behavior and whether dismissal is reversible are left unstated.

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%, but the description compensates partially: it clarifies that 'reviewer' is optional ('one reviewer's' vs 'all of them') and that 'reason' is mandatory and audited. owner/repo/number carry no added meaning, so the coverage gap is not fully closed.

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') on a specific resource ('standing changes requested reviews on a PR') with explicit scope ('all of them, or one reviewer's'). The effect clause ('so they no longer hold the merge') makes the outcome unambiguous, and it is clearly distinguishable from the sibling gluecron_request_changes.

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 operative context (reviews that block the merge) and the prerequisite ('Requires repo scope and write access'), plus the constraint that a reason is required. It does not name an alternative tool or state when not to use it, but the situation for invoking it is clear.

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

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

Goes well beyond the annotations: the edit history retention qualifies what 'destructive' means here, 'same text again is `unchanged`' concretely explains idempotency, and the concurrent-edit conflict rule plus mention-notification behavior are otherwise undiscoverable. It even names the mirrored REST endpoint and return shape, which matters since 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?

Front-loaded with the action and key, then layered with constraints, with no filler sentences. It is dense (endpoint mirror and return shape in the same paragraph) but every clause carries operative 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 mutation with no output schema, it covers auth, reversibility, idempotency, concurrency, notifications, and the return shape. The only omission is the optional thread parameter, which the schema already types adequately.

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

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

Schema coverage is 80%, so baseline is 3. The description restates the comment-id keying and confirms the body semantics, but adds nothing about the optional nested `thread` object (kind/number) that the schema leaves thin on purpose.

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 ('Replace the text of a comment'), the scope ('issue or pull request'), and the lookup key ('by comment id'). This clearly separates it from creating tools like gluecron_comment_issue/gluecron_comment_pr and from gluecron_delete_comment.

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?

Names the authorization contract ('Its author or a repository writer only'), which tells the agent when the call will succeed. It does not explicitly point to alternatives such as delete_comment or re-commenting when the edit is not permitted, so it stops slightly short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds genuinely new behavioral context beyond that — 'Infra and flaky failures never suggest a code change', the cross-repo scoping ('this repo, your other repos with the same owner or org, and platform-wide counts only'), and the diff being limited to relevant files.

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 dense but well-ordered sentence: purpose first, then the returned diagnostics in sequence, then the parameter caveat. Nothing is wasted, though the long clause chain is heavy to parse and could have been broken up.

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 carries the full return-value burden and does so thoroughly — failure class taxonomy, fix-rate semantics, cross-repo visibility limits, diff scoping, and the infra/flaky exception. An agent knows what it will get and what constraints apply.

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

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

Schema description coverage is 100%, so the schema already documents run_id, owner, repo, and include_diff. The description's closing note about run_id being a full id or an 8+ hex prefix with owner+repo duplicates the schema text rather than extending it, 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 — 'Explain a failed CI run' — and immediately enumerates the concrete diagnostics produced (failure class, error signature, failing tests, prior occurrences, suggested fix), which clearly separates it from siblings like get_workflow_logs or get_workflow_run that merely fetch raw data.

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

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

The scenario is strongly implied (you use this to diagnose a run that already failed), but there is no explicit when-to-use/when-not guidance and no named alternatives such as get_workflow_logs for raw output or list_flaky_tests for flake stats. Usage must be inferred from the purpose statement.

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

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

The description adds value beyond annotations by explicitly stating 'Pure read — never triggers a new generation', which aligns with the readOnlyHint and provides specific behavioral context about caching. No contradictions.

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

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

The description is extremely concise: two short sentences that front-load the purpose and immediately add a critical behavioral constraint. Every word adds value, no redundancy.

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

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

For a simple read-only retrieval tool with two standard parameters and no output schema, the description adequately covers core behavior (returns cached Markdown), return format hint (Markdown), and safety profile (read-only). No missing information given 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 coverage is 0% and the description does not explain the 'owner' and 'repo' parameters beyond what is obvious from their names. With no additional parameter guidance, the description fails to help agents understand input format or constraints.

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

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

The description clearly states the tool returns cached AI Markdown for a repo. It uses specific verb 'Return' and resource 'cached AI explain this codebase Markdown', and distinguishes from tools that trigger new generations by explicitly saying 'never triggers a new generation'.

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

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

The description provides clear usage context: use this when you want the cached explanation without triggering a new generation. It implicitly contrasts with other tools that generate new explanations, but does not explicitly name sibling alternatives like 'repo_explain_codebase'.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description adds little beyond the safe read behavior. It mentions wrapping a library but no further behavioral traits (e.g., what happens if symbol not found, multiple definitions).

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

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

The description is a single sentence plus a note, which is appropriately concise and front-loaded. It conveys the core purpose without extraneous content.

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

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

Given the tool has 3 required parameters, no output schema, and limited schema descriptions, the description does not provide enough context for correct invocation. Missing details on return format, error handling, and parameter relationships.

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 33% (only 'name' described). The tool description does not add meaning to the parameters beyond what the schema provides. For a tool with low schema coverage, the description should compensate but 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?

The description clearly states it finds definitions of a symbol by name within a repo. The title 'Find symbol' supports this. It distinguishes from siblings by specifying a niche operation (symbol definition lookup) not covered by other tools.

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

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

No guidance on when to use this tool vs alternatives like semantic search or reading files. No when-not-to-use criteria or prerequisites mentioned.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false. The description adds transparency by specifying it mirrors POST /:owner/:repo/fork, returns {owner, repo, url}, and requires 'repo' scope. No contradiction with annotations.

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

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

The description is two sentences, each adding value: first states the action, second provides API details, return format, and scope requirement. No redundant 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 tool with two parameters and no output schema, the description covers the core action, return values, and a scope prerequisite. It does not mention error handling or rate limits, but is sufficiently complete for typical use.

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

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

Schema coverage is 100%, with both parameters (repo, owner) described by the schema. The description does not add additional meaning beyond the schema, meeting the baseline for high 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?

The description clearly states 'Fork a repository to the authenticated caller's namespace,' specifying the verb (fork), resource (repository), and destination. It distinguishes from sibling tools as there are no other fork tools, making the purpose unambiguous.

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

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

The description includes the requirement for a 'repo' scope, providing a prerequisite for use. However, it does not explicitly state when to use this tool versus alternatives, but since there are no directly competing fork tools, the guidance is adequate.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the tool's safety is clear. The description adds little beyond noting the same engine as a sibling, which is contextual but not behavioral. It doesn't disclose rate limits, auth needs, or output characteristics.

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 highly concise, using two efficient sentences that convey the purpose and key distinction without any fluff.

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

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

Given the simple nature of the tool (2 parameters, no output schema), the description is minimally adequate but lacks details on the output format or commit message conventions. It is not fully complete for an agent to understand all implications.

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 50% schema description coverage, the description does not compensate for the undocumented 'diff' parameter. The 'style' parameter has a brief description, but the tool description adds no further meaning to either parameter, leaving the agent to infer usage.

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

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

The description clearly states it generates a commit message for a diff, and explicitly distinguishes it from gluecron_generate_pr_description, ensuring the agent selects the correct tool for commit messages vs. PR descriptions.

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

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

The description provides a clear context by mentioning the sibling tool, implying when to use this (commit messages) versus the other (PR descriptions). However, it does not explicitly state when not to use it or provide alternatives, leaving room for improvement.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description adds value by disclosing the internal module ('src/lib/ai-commit-message.ts') and graceful degradation to heuristic when ANTHROPIC_API_KEY is missing. This goes beyond annotations without contradicting them.

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 highly concise with two sentences: first states the purpose, second adds implementation detail and return type. Every sentence serves a function with no redundancy.

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

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

Given no output schema, the description includes the return shape ({subject, body}). Parameter semantics are covered in the schema. The behavior (AI vs heuristic) is explained. Minor gaps (e.g., diff size limits) are not critical for a simple 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% with both parameters ('diff' as 'Unified-diff body' and 'style' with default 'conventional' or 'plain'). The description does not add new parameter-level meaning but complements with return format and fallback behavior, resulting in a baseline score.

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

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

The description clearly states the tool generates an AI commit-message-style description for a diff, specifying the verb ('generate') and resource ('commit-message-style description for a diff'). It differentiates from siblings like 'gluecron_generate_commit_message' by focusing on PR descriptions from diffs and mentioning the internal implementation.

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

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

The description implies usage for diff-to-PR-description conversion but lacks explicit when-to-use guidance or comparisons with alternatives. It does not mention when not to use it or suggest siblings like 'gluecron_generate_commit_message' for other contexts, providing only implicit context.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that it wraps a specific function and returns Markdown and section data, providing output structure beyond annotations. No contradictions.

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

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

The description is concise with two sentences. The first sentence captures the core functionality, and the second adds output details without verbosity. Every sentence adds value.

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

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

Given the tool's moderate complexity (4 parameters, no output schema), the description covers purpose and output but lacks guidance on required parameters and usage context among many siblings. It does not explain that repo and owner are required or that from_tag is optional.

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% (only to_tag and from_tag have descriptions). The description mentions 'between two tags' but does not clarify the required owner and repo parameters or that from_tag is optional. It adds no new parameter details beyond what the schema provides.

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

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

The description clearly states the tool generates release notes between two tags and specifies the output format (rendered Markdown + section data). This sets it apart from sibling tools like gluecron_generate_commit_message or gluecron_generate_pr_description.

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

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

The description implies when to use (generating release notes between tags) but does not provide explicit guidance on when not to use it or suggest alternative tools. No usage context or exclusions are given.

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

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

Annotations already indicate the tool is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds that it wraps a function and requires 'repo' scope, but does not disclose additional behaviors such as cost, rate limits, or side effects beyond creating PRs/commits.

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

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

The description is three sentences, each serving a distinct purpose: stating the main function, explaining modes, and noting scope requirement. No unnecessary words, and the purpose 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?

Given the tool has 4 parameters and no output schema, the description covers the essential aspects (purpose, modes, scope). However, it could be more complete by explaining what the tool returns (e.g., PR URL or commit SHA) or any asynchronous behavior.

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 50% (mode and number have descriptions; repo and owner do not). The description adds context for the 'mode' parameter and mentions the required scope, but does not fully compensate for the missing schema descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the tool's verb ('Generate tests') and resource ('for a PR'). The two modes are specified, distinguishing it from sibling tools like gluecron_generate_commit_message or gluecron_generate_pr_description, which serve different purposes.

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

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

The description explains the two modes ('follow-up-pr' and 'append-commit') and their outcomes, and mentions the required 'repo' scope. However, it does not explicitly state when to use this tool over alternatives or when not to use it, though no direct competing sibling 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, indicating safe read-only behavior. The description adds no additional behavioral details beyond confirming it returns data. Since annotations cover the safety profile, a score of 3 is appropriate.

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

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

The description is a single efficient sentence that conveys the tool's purpose without extraneous words. It is well front-loaded and earns its place.

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

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

Given the tool's simplicity (one parameter, no output schema, annotations present), the description is mostly complete. It specifies what is returned (spent, cap, remaining cents) and hints at the input (agent session). Minor gaps exist (e.g., error behavior), but for a read-only tool, this is sufficient.

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 only parameter, agent_session_id, has no description in the schema (0% coverage). The description does not elaborate on its format, meaning, or constraints, providing no added value beyond the schema's type definition.

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

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

The description clearly states it returns spent, cap, and remaining cents for an agent session, which directly describes the tool's function. The name 'gluecron_get_agent_budget' matches this purpose. No sibling tool appears to duplicate this functionality.

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

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

The description provides no guidance on when to use this tool versus alternatives or any prerequisites. It merely states what the tool does, leaving the agent without contextual usage instructions.

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 this with 'Read-only.' It adds useful behavioral detail beyond the annotations by describing the return payload for both no-rule and matching-rule cases, including merge_train fields and the protected false/true distinction.

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-loaded: it names the operation, lists relevant rule fields, explains merge_train, and states the return shapes. Every clause contributes useful information, though the field list could be more structurally organized for 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?

For a three-parameter read-only tool with no output schema, the description provides the necessary return-value detail: it explains the protected false case with merge_train and the protected true case with pattern, matched_by, required_checks, and merge_train. This is sufficient for an agent to call and interpret the 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 100%, so the schema already documents repo, owner, and branch. The description adds meaning beyond the schema by clarifying that the branch parameter accepts either an exact branch name or the glob that covers it, which is useful semantic guidance for selecting the right value.

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: read the branch-protection rule that applies to a branch. It specifies the scope (exact name or covering glob), enumerates the rule fields returned, and clearly distinguishes this read operation from the sibling set_branch_protection mutation.

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 'Read the branch-protection rule' and the read-only note, but the description does not explicitly say when to use this versus alternatives such as set_branch_protection or when not to use it. The context is clear enough for basic selection, but there are no explicit routing instructions.

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?

Even with readOnlyHint=true and destructiveHint=false already declared, the description adds meaningful behavioral context: it details the response composition, states that patch bodies are deliberately omitted, and mirrors a specific REST endpoint. This goes beyond the annotations and helps the agent set correct expectations.

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 only two sentences, front-loads the core action, and packs in the endpoint reference, return-value summary, and a clear caveat with an alternative. Every sentence earns its place with no redundancy.

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

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

For a read-only, single-commit fetch with no output schema, the description covers what the response contains, what it omits, and how to get the omitted content. It is sufficient for an agent to call the tool 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 description coverage is 50%: sha and include_files are described in the schema, while owner and repo are not. The tool description indirectly clarifies owner/repo via the endpoint pattern and clarifies the meaning of the file list, but it does not compensate fully for the undocumented 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?

The description starts with a specific verb and resource: 'Fetch a single commit by SHA' and lists exactly what is returned (metadata plus file changes with path, status, additions, deletions). It also explicitly contrasts with gluecron_get_diff by stating patch bodies are not included, so an agent can distinguish the two tools 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 gives an explicit when-not-to-use instruction: 'Patch bodies are NOT included — use gluecron_get_diff for those.' This directly names the alternative and the condition that selects it, which is exactly what a usage guideline should provide.

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 adds meaningful behavioral detail: it documents the return object shape, the `truncated` flag, and that patch text is byte-capped. This is valuable context beyond the structured fields and is consistent with the read-only annotation.

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 focused sentences with zero fluff: purpose, invocation modes, return shape, and truncation caveat are all front-loaded and each sentence earns its place.

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

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

With no output schema, the description wisely includes the return shape and truncation semantics. It covers both call modes and the summary-only switch. A minor gap is that it doesn't explicitly state `sha` and `base`+`head` are mutually exclusive, though `or` implies 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 coverage is 71%, already covering most parameters, and the description adds the key relational semantics between `sha` vs `base`+`head`, plus the effect of `include_patch=false`. It doesn't detail `max_patch_bytes`, but that is already defined in the schema.

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

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

The description opens with a specific verb and resource: 'Read the actual changes in a commit or a branch range.' It clearly differentiates the tool from siblings like gluecron_get_commit or gluecron_get_pr by focusing on diff content and explicitly naming two diff modes.

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 usage conditions: pass `sha` for one commit against its first parent, or `base`+`head` for the PR-style branch range. It doesn't name explicit alternatives or exclusions, but the context is clear enough for an agent to decide when to invoke it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it is an authenticated call, and it explains mergeable semantics (true/false/null unknown), mergeState values, unresolved files, settled files, and conflictsUrl.

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

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

The description is front-loaded with the core action and avoids wasted filler. It is dense but somewhat long as a single sentence with nested parentheticals, though every clause provides useful return-value 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?

There is no output schema, so the description carries the burden of explaining returns; it does so thoroughly by listing standard PR fields, mergeability, merge state values, unresolved files, settled files, and conflictsUrl. The authentication requirement is also disclosed.

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 schema already documents owner, repo, and number. The description adds no additional meaning about these parameters, so the baseline 3 applies.

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

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

The description uses a specific verb ('Fetch') and resource ('full detail record of a pull request'), and it enumerates the returned fields. It distinguishes itself from listing/search tools implicitly via 'full detail record' and the merge-probe details, but it does not explicitly name alternative sibling tools.

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

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

Usage is implied by the focus on full PR detail and merge conflict probe information, but the description never states when to use this instead of sibling tools like list_prs, search_prs, pr_status_summary, or list_pr_conflicts. The authentication note is an access constraint rather than usage 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 carry readOnlyHint, and the description restates 'Read-only' (mild redundancy) but goes well beyond: it discloses the withheld-log case and the required 'repo' scope for private repositories, the fact that a timed_out run still blocks merge, and the exact shape of the `failure` payload. That auth and blocking-behaviour context is real value the annotations cannot supply.

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 core purpose, which is good, but the remainder is a single ~180-word sentence stitched together with em-dashes and nested clauses that is hard to parse on a quick read. The detail is largely justified given there is no output schema, but the structure could have been broken into scannable clauses.

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 fully: it enumerates the returned fields (head_sha, total_count, check_runs, required, ci), the per-check state vocabulary, and the nested failure shape including the withheld variant. An agent can correctly interpret the response without any 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% and all three parameters (owner, repo, number) are documented in the schema, so the description does not need to explain them. It adds nothing parameter-specific beyond the phrase 'at a PR's current head', which merely reinforces what `number` means. 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?

Opens with a specific verb and resource ('List every check at a PR's current head') and enumerates the covered sources (workflow runs, gates, commit statuses), so the agent knows exactly what is returned. It does not name the neighbouring tools (pr_status_summary, list_workflow_runs, get_workflow_run) that could be mistaken for it, so sibling 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?

There is no explicit when-to-use or when-not statement and no named alternative, despite siblings like pr_status_summary and list_ready_to_merge covering overlapping ground. The merge-readiness framing hints at intent, but the agent must infer it from the return-shape description rather than from any stated 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?

The annotations already indicate readOnlyHint=true and destructiveHint=false, establishing a safe read operation. The description adds value by disclosing that the tool wraps an internal function and returns a specific error shape when the host is misconfigured. The success return format is only partially described ('URL + status'), but the added context goes beyond the annotations.

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

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

The description consists of two concise sentences. The first states the primary action and inputs, and the second adds a critical error condition. Every sentence serves a purpose with no padding, making it highly efficient and 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?

Given three required parameters and no output schema, the description covers the error case but omits details about the success response shape. It also fails to explain the 'owner' parameter. While the tool is simple, the missing parameter guidance and incomplete output description leave moderate 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?

The schema description coverage is 0%, so the description must compensate for parameter meaning. However, the description mentions only 'repo' and 'branch', omitting the 'owner' parameter. It does not explain what each parameter represents or provide any insights beyond their names, leaving the agent with incomplete 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?

The description clearly states that the tool returns a branch-preview URL and status for a given repository and branch pair. It specifies the verb 'return' and the resource 'branch-preview URL + status', and the mention of wrapping an internal function adds precision. Among siblings, no other tool serves this purpose, making it well-differentiated.

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

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

The description implies the tool should be used to retrieve a preview URL for a branch, and it provides a specific condition (host without PREVIEW_DOMAIN) that leads to an error response. While it doesn't explicitly state when not to use it or name alternatives, the unique functionality makes the usage context clear enough.

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 readOnlyHint=true already covering safety, the description adds genuinely useful behavior: the return includes the full audit trail (create, edits with before/after diff, rotations, revocation) and explicitly never exposes the secret. The 'same scopes as gluecron_list_tokens' note gives auth context.

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

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

A dense single passage that front-loads the core purpose and return contents; nearly every clause earns its place. Minor redundancy in restating the type prefixes that the schema already carries.

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 carries the return-value burden and does so by enumerating what the audit trail contains and what is withheld. Adequate for a two-parameter read tool, though it does not mention pagination or audit-trail size limits.

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, and the description largely repeats the type vocabulary already present in the schema. The only added value is tying `id` back to gluecron_list_tokens, which is marginal beyond the schema.

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

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

States a specific verb+resource ('get one of your tokens by type and id') and immediately scopes it against the sibling list tool by noting the id comes from gluecron_list_tokens. An agent can distinguish this from gluecron_list_tokens without opening 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?

Implies the workflow: call gluecron_list_tokens first to obtain the id, then use this to fetch the single token. It also states scope ('one of your tokens'), but it never explicitly contrasts when to use this versus the list call rather than reading both.

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 readOnly, idempotent and non-destructive, so safety needs no repeating. The description adds real context beyond them: organisation variables require an admin-scoped token, and a missing name is an error rather than an empty result.

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 plus a return-shape clause, with purpose first, then scope selection, then auth and error behavior. Nothing is redundant with 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?

With no output schema, the description supplies the return shape itself ({name, value, createdAt, updatedAt}), covers the auth requirement for the org scope, and states failure behavior. For a single-resource getter this is complete enough to 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 coverage is 100% so the baseline is 3, but the description goes further by explaining how the parameters combine (owner+repo, owner+repo+environment, org) to select the variable scope, which the individual property descriptions do not state.

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 one Actions variable by name. It is clearly distinguishable from siblings like gluecron_list_variables, gluecron_set_variable and gluecron_delete_variable, and scope is front-loaded.

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 routing logic: owner+repo for a repository variable, owner+repo+environment for an environment variable, org for an organisation variable. It does not explicitly name the listing sibling as the alternative when the name is unknown, so there is no stated 'when not to use'.

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 read-only safety, and the description still adds real behavioral context beyond them: the 'repo' scope / OAuth write:repo requirement, that every token read is audited, and that a truncated step exposes `fullLog` as an artifact download. It stops short of stating pagination, size limits, or latency, which is the only remaining gap.

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

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

Purpose is front-loaded, but the middle is a single dense run of nested parentheticals describing testFailures categories and forensic fields that is difficult to parse on one read. The detail is largely justified because there is no output schema, but the packing is heavy for the payload.

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 carries the return shape itself: run metadata, per-job/per-step status, exit code, duration, failedSteps, testFailures with its classification taxonomy, and fullLog. Combined with the auth note this is close to complete, with only pagination/size expectations 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?

With 60% schema coverage, the description compensates by explaining `step` (a name exact-then-substring case-insensitive, or 1-based position within its job) and the interaction rule that full logs appear only when neither `step` nor `tail_lines` is passed. It adds meaning beyond the schema, though `owner`/`repo` are left entirely 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?

The opening sentence names a specific verb and resource ('Return a workflow run's logs plus a failure summary') and adds a scope distinction via 'JSON-friendly companion to the ZIP-download endpoint'. It never names an actual sibling tool (e.g. get_workflow_run, explain_failure), so the differentiation is by shape of output rather than by sibling routing.

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 through parameter behavior rather than stated as guidance: '`step` ... returns only that step's stdout/stderr; `tail_lines` keeps the last N lines. The full per-job logs are included only when neither is given.' There is no explicit statement of when to prefer this over explain_failure or get_workflow_run, nor any 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 establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description goes well beyond that by explaining run-relationship semantics (retryOf/retriedAs), queue-reason diagnostics, workClass slot sharing, and schedule coalescing — genuinely useful behavioral context for interpreting results.

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 in the first sentence, then dense field-level detail. Every sentence carries substantive information, though the long run-on field inventory lacks bullets and the meta phrasing "Also says how it relates to..." is slightly awkward.

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 explaining return values and does so thoroughly. Annotations cover safety; the only material gaps are error/not-found behavior and the undocumented owner/repo parameters.

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 (accepts a unique 8+ hex prefix) but owner and repo are bare strings. The description adds no meaning whatsoever for any parameter, so it fails to compensate for the low coverage as the rubric requires.

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: "Fetch a workflow run's metadata + status," and anchors it to the upstream API route. It is clearly a single-run read, distinguishable by name from gluecron_list_workflow_runs, but the description never explicitly contrasts itself with that sibling or with gluecron_get_workflow_logs.

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 statement, no exclusions, and no named alternatives among the many workflow-related siblings (list_workflow_runs, get_workflow_logs, ci_queue_status). Usage is only implied by the described fields (inspecting retries, queue reasons, coalesced schedule fires), which is the definition of implied 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 declare readOnlyHint=true and destructiveHint=false, and the trailing 'Read-only' restates that rather than adding to it. The rest is genuinely additive: explicit return sections (summary, blockers, CI per workflow, merge gate grouping, queue), plus bounds such as at most 10 plan files and a 48h default / 720h cap window.

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 selection cue and then a dense enumeration of return sections; almost every clause carries information an agent needs. It is one very long run-on sentence, which makes it harder to scan than it needs to be.

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 thoroughly by enumerating each returned field, its ordering, and its conditional presence. For a complex aggregate-read tool, an agent has enough to call it and interpret the response.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description only echoes `merged_since_hours` (default 48) and adds no semantics for `owner`/`repo` beyond 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?

States a specific verb and resource — reading the live state of a repository from git and CI — and frames itself as the orientation entry point, explicitly contrasting with a handoff doc. Among siblings like repo_health, pr_status_summary and ci_queue_status, this reads as the aggregate starting 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?

'Start here when picking up work' gives an explicit trigger condition, and the parenthetical on `plan`/`plans` tells the agent when those extra sections appear. It stops short of naming alternatives to avoid (e.g. repo_health, pr_status_summary) or stating when not to use it.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond by disclosing the admin-token requirement, the one-ref-per-import constraint, that re-importing a ref updates it to current upstream state, that the operation is audit-logged, and the skip behavior for unimported actions.

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 admin-only requirement, then purpose, then behavioral facts, with zero filler. Dense but every clause (skip semantics, idempotent re-import, audit log, return shape) carries actionable 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?

Covers the auth prerequisite, the mutation/idempotency profile matching the annotations, the operational consequence for workflows, and an inline enumeration of the response fields in the absence of an output schema. An agent has everything needed to call 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the mirror namespace is derived as gluecron-actions/<owner>--<repo>, only ONE tag/branch/full SHA may be imported per call, and it enumerates the returned fields despite no output 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 (import) and resource (a third-party GitHub Action at one ref) and names the exact target namespace (gluecron-actions/<owner>--<repo>). No sibling tool performs this function, and the description makes that unambiguous.

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

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

The 'when' is clear: needed so workflows writing `uses: owner/repo@ref` can run, because workflow runs never fetch from github.com and unimported actions are skipped. It also states the admin-scoped-token prerequisite. It does not name an alternative tool, but no close sibling 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?

Discloses that labels are auto-created if missing and specifies the return object. Annotations already indicate mutability (readOnlyHint false) and non-destructiveness, so the description adds useful context beyond annotations.

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

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

Two sentences, each adding necessary information. No fluff, front-loaded with the action.

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

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

For a simple labeling tool, it covers purpose, auto-creation, required scope, and return value. Minor omission: 'number' is not explicitly said to be the issue number, but it is clear from context.

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

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

Only 25% schema description coverage; the description does not elaborate on parameters like owner, repo, or number beyond the schema. For labels, the schema already describes 'Label names (strings)', so the description adds no extra 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 starts with a specific verb ('Attach') and resource ('labels to an issue'), clearly distinguishing it from sibling tools like gluecron_unlabel_issue or gluecron_comment_issue.

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?

States the required 'repo' scope, which is a key usage constraint. It does not explicitly list when-not-to-use, but the purpose is straightforward and well understood.

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

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

Annotations already declare readOnlyHint=true/destructiveHint=false, and the description adds genuinely useful behavior beyond that: output is counts only with no log text or repository data, the returned shape is {health, patterns, register}, and the interpretation rule ("N failures, 0 lessons" reads RED). This is solid additive context for a read 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?

The auth gating and core purpose are front-loaded, and the detail is dense but mostly earns its place. It reads somewhat as a run-on sentence, but it is appropriately sized for the number of facets it lists.

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