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?

With annotations covering only readOnlyHint/destructiveHint, the description carries the load and delivers: git apply --cached against branch head, compare-and-swap via expected_head_sha (all-zeros = branch must not exist), same branch-protection/ruleset/secret-scan path as a push, CI/webhook firing, a 2 MiB limit, and the 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?

Single dense paragraph, front-loaded with purpose before mechanics; nearly every clause carries new information (formats, CAS, protections, limits). It is long and packs many distinct facts, 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?

No output schema exists, yet the description enumerates the return shape ({branch, commit_sha, parent_sha, files_changed, files, commits, created}) and covers auth scope, size limit, and branch-creation behavior — everything an agent needs to invoke 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?

Adds real meaning beyond the 71%-covered schema, especially for `patch` (a/ b/ prefixed git diff vs format-patch mbox, where each patch becomes its own commit with its own message/author) and the interaction with `message`. It largely mirrors the schema on base_branch/expected_head_sha rather than extending them.

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 (commit a patch to a branch) and immediately scopes it against the whole-file alternative ('without sending whole files'), which distinguishes it from write_file and atomic_multi_file_commit 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?

Gives clear when-to-use context: it is 'the way to change a few lines of a large file', and it distinguishes the two input modes (unified diff where message is required vs mbox where message is ignored). It does not explicitly name a sibling tool as the fallback for whole-file commits, so it stops short of full when/when-not/alternatives 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 set readOnlyHint=false and destructiveHint=false. The description adds that assignment is modeled as a label (behavioral detail) and requires 'repo' scope (authentication context), which goes 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?

Three concise sentences with clear purpose, implementation detail, and a requirement. No redundant information; each 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?

Adequate for a simple assignment tool, but missing details like whether it overwrites existing assignees, supports multiple assignees, or what the return behavior is. No output schema so description should provide more behavioral 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?

Schema description coverage is only 25% (only assignee has a description). The tool description does not elaborate on any parameter semantics (e.g., what 'number' refers to), so it adds minimal value 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 clearly states 'Assign an issue to a user' with a specific verb and resource. It explains the label-based implementation, differentiating it from standard assign but does not explicitly contrast with sibling tools like gluecron_label_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?

No guidance on when to use this tool versus alternatives such as gluecron_label_issue. The only usage hint is 'Requires repo scope', a prerequisite, but no when-to-use or when-not-to-use advice.

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

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

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 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 already declare readOnlyHint=true and destructiveHint=false, so the closing "Read-only." earns little. The description does add genuine context beyond annotations: the response is "the same `ciQueue` block the write tools return," which tells the agent the shape is consistent across tools, and it discloses that owner+repo is what unlocks the per-repo view.

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 answer (how full the queue is) and then the optional per-repo extension, which is the right ordering. It is a dense em-dash sentence, but each clause carries distinct content — level, counts, slots, ETA, per-repo fields, recommendation — so little is wasted.

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

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

With no output schema, the description correctly carries the return-value burden and enumerates the fields an agent will get back. Combined with the pre-push usage trigger and the owner+repo semantics, an agent has enough to invoke and interpret it; only the absence of explicit alternatives keeps it from a 5.

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 meaning: owner+repo must be supplied together, and supplying them yields that repo's queued/running runs, its share of CI work, slots it may hold while others wait, and a recommendation. That is more than the schema's terse "Optional, with owner."

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 and scope: the shared CI queue's fill level plus per-repo breakdown. It enumerates the exact outputs (level ok/busy/saturated, runs queued/running, runner slots, ETA), which lets an agent distinguish it from generic run-listing siblings like gluecron_list_workflow_runs.

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 an explicit trigger: "Ask before a burst of pushes." That is real when-to-use guidance rather than a restatement of purpose. It stops short of naming an alternative tool or a when-not-to-use condition, so it falls one step below the top.

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?

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?

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 declare readOnlyHint=false and destructiveHint=false, consistent with a token-creation tool. The description adds meaningful behavior beyond that: the token is single-use, expires in an hour, and yields a long-lived credential on the runner, plus the exact return shape. Not contradicted, but it does not cover permission requirements or failure modes.

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

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

Three sentences, front-loaded with the action and scope, then the lifecycle behavior, then the return shape. No filler or 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?

With no output schema present, the description compensates by enumerating the return fields {owner, token, expiresAt, gluecronUrl}. Combined with the single-use and expiry semantics and the owner scoping rules, 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 description coverage is 100%, so the baseline is 3, but the description adds real meaning to the owner parameter by enumerating valid value classes (username, owned/admin'd org, or 'platform' as a site admin) beyond the schema's terse 'Username, org slug, or platform'. Labels is left to the schema, which documents it adequately.

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') with explicit scope for the owner argument, clearly distinguishing it from siblings like gluecron_list_runners and gluecron_revoke_runner. An agent can identify what this produces 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?

Explains the context of use: a runner started with RUNNER_REGISTRATION_TOKEN registers once and the owner's CI then runs on it. It clarifies which owner values are acceptable, including the site-admin-only 'platform'. It stops short of explicitly naming alternative tools or when-not-to-use conditions, so it falls just under 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 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 already mark destructiveHint=true, but the description adds valuable context: it specifies what is deleted (repository row) and what is preserved (git data on disk). It also discloses the return value and permission requirements. 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 two sentences, front-loaded with the main action. It packs in the key caveat (disk untouched), permission requirements, and return value without any fluff. Every sentence earns its place.

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

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

For a simple destructive operation with two parameters and no output schema, the description covers all essential aspects: action, effects, prerequisites, and return format. An agent has everything needed 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 description coverage is 100%, with both 'owner' and 'repo' documented in the schema. The description does not add extra parameter details, but the baseline of 3 is appropriate because the schema fully covers parameter semantics.

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: 'Permanently delete a repository row.' It specifies the resource (repository row) and distinguishes from siblings like gluecron_update_repo by emphasizing deletion. The note that git data on disk is left untouched further clarifies scope, 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?

It states the primary use case (deleting a repo) and explicitly lists required permissions (admin access and token scope). It doesn't mention when not to use it, but as the only deletion tool, no alternative exists. The disk caveat also guides usage by clarifying what is not affected.

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?

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 the list of returned fields and an authentication note, which is useful context. However, the auth note is somewhat ambiguous ('Authenticated callers only (the read tool surface still works anonymously)') and could confuse. It does not disclose error behavior, rate limits, or any side effects, but for a read tool with annotations, the additional field list provides reasonable value.

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

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

The description is a single sentence with no wasted words, and the action verb is front-loaded. The parenthetical about authentication adds a necessary caveat but is slightly awkward. It is efficient and readable, though the ambiguous auth phrasing slightly detracts from clarity.

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

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

With no output schema, the description compensates by listing the exact fields returned (title, body, state, branches, draft, author, timestamps), which is essential for an agent to know what it gets. For a simple read operation with annotations covering safety, this is largely complete. The auth note, while confusing, does alert the agent to a requirement. Missing details like error handling are minor for a read tool of this simplicity.

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

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

Schema description coverage is 100% – each parameter (owner, repo, number) has a clear description. The tool description adds nothing about parameter semantics beyond what the schema provides. It lists the fields returned but not any parameter-specific details. Baseline 3 is appropriate when the schema fully documents 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 clearly states the verb 'Fetch' and the resource 'full detail record of a pull request', and enumerates the fields returned (title, body, state, branches, draft, author, timestamps). This distinguishes it from sibling tools like gluecron_list_prs, gluecron_search_prs, and gluecron_get_diff, which serve different purposes. The specificity leaves no ambiguity about what the tool does.

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 like list_prs or search_prs. The only usage note is the authentication requirement, which is about caller eligibility rather than tool selection. An agent would have to infer that this is for a single PR by number based on the schema, but the description does not explicitly state selection criteria.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful return-shape context ('concatenated per-job logs... plus per-job metadata'), but says nothing about size limits, truncation, or whether partial/in-progress runs yield incomplete logs.

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

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

A single front-loaded sentence with no filler; the return contents are stated first. Slightly terse given the tool's complexity, but efficient.

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 parameterized read tool with no output schema, the description conveys return content adequately and annotations cover safety, but the absence of any owner/repo semantics or log-size/truncation notes leaves gaps an agent must guess at.

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

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

Schema coverage is only 33% (only run_id documented, with its leading-part abbreviation rule). The description adds no semantics for owner or repo, so it does not compensate for the coverage gap despite three required parameters.

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

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

Specific verb ('Return') and resource ('concatenated per-job logs for a workflow run, plus per-job metadata'). It is clearly a log-fetching tool, distinct from gluecron_get_workflow_run, though it never names that sibling explicitly.

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

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

The phrase 'JSON-friendly companion to the ZIP-download endpoint' implies an alternative and the condition for choosing this tool (machine-readable output vs archive download), but no when-to-use / when-not guidance is stated directly.

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 safe-read profile is covered and the description is consistent with it. The description adds only the fact that it mirrors a REST endpoint; it says nothing about what metadata fields come back, whether the run must still exist, or error behavior when a prefix matches multiple runs.

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

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

Two short sentences with zero filler, and the core purpose is front-loaded before the implementation note. Nothing could be removed without losing information.

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

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

With no output schema, the description carries the burden of describing the return value and does so only vaguely ('metadata + status'). For a simple three-parameter read tool with annotations covering safety, that is adequate but leaves the agent guessing about the response shape and the multi-match prefix case.

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

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

Schema description coverage is only 33%: run_id is well documented (prefix matching, 8+ hex chars) but owner and repo carry no description. The description text adds no parameter meaning at all, so it fails to compensate for the two undocumented parameters, even though their semantics are conventional.

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 pins it to the underlying REST endpoint, which makes it distinguishable from get_workflow_logs and cancel_workflow_run. It stops short of naming those siblings explicitly, so it is clear but not fully 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?

There is no statement of when to use this tool versus alternatives such as get_workflow_logs or cancel_workflow_run, and no prerequisites or follow-up guidance. The agent must infer usage purely from the tool name.

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

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

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 and destructiveHint=false, so no safety contradiction exists. The description adds useful behavioral context beyond the annotations: authentication is required, the result set is capped at 50 summary rows, and filtering by state is supported. This is meaningful operational information without being redundant.

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

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

Three short sentences with no filler. The main purpose and scope are front-loaded, and each sentence adds necessary information: what is listed, how it is filtered, who can call it, and what is returned.

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 list operation with rich parameter schemas, the description is largely complete: it covers the action, scope, authentication, state filter, and result size. Pagination is implicit through offset and nextOffset in the schema, and there is no output schema, so the 'summary rows' hint gives some shape. Missing only explicit guidance on paging behavior and sorting, which is a minor 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 already documents all five parameters and their meanings. The description adds a general mention of state filtering and a 50-row cap, but does not add anything beyond what the parameter descriptions already provide. 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 a specific action ('List pull requests on a repo') and the resource scope, with an explicit state filter. It is not a tautology and is readily distinguishable from get_pr and repo_list_issues, though it does not explicitly name the sibling search_prs as an alternative.

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

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

The only usage guidance is 'Authenticated callers only,' which is a prerequisite rather than a when-to-use instruction. It does not explain when to prefer this tool over gluecron_search_prs, gluecron_get_pr, or repo_list_issues, nor does it provide any exclusion guidance.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses substantial behavior: both modes honor path, recursive toggles one-level vs whole-subtree, return shape is always the same, recursive vs non-recursive entry naming differs, and a nonexistent ref is an error. This is rich, non-obvious context that helps the agent predict outcomes.

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 compact and front-loaded, with the core action in the first sentence and every subsequent sentence adding distinct information about modes, return shape, or error behavior. No filler or redundant restatement.

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 present, the description wisely defines the exact return shape. It covers path behavior, recursive behavior, entry naming, and ref errors. Minor gaps remain, such as what truncated means or how pagination works, but these are not essential for a basic 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 only 40%, but the description compensates by explaining the two most behaviorally important parameters: path scoping and recursive semantics. It also adds meaning for ref by stating that a missing ref is an error. Only owner and repo are left to the schema, but those are standard repository identifiers and require little additional explanation.

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: 'List directory contents at a ref.' This clearly distinguishes it from sibling tools like gluecron_read_file and gluecron_find_symbol, which serve different purposes. The focus on directory listing is unambiguous.

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

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

The description gives clear context for when to use the tool and how its modes behave: path scopes to a subtree, recursive walks the whole subtree. It does not explicitly name alternatives or state when not to use it, but the directory-listing purpose is enough for an agent to select it correctly in most cases.

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, so safety is covered; the description adds the ordering guarantee ('newest first') and the REST-equivalent behavior ('Mirrors GET /api/v2/repos/.../actions/runs'). It stops short of describing paging behavior or what a run record contains, which keeps it at a strong 4 rather than 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?

Front-loaded with purpose and scope in the first sentence, and the routing hint follows immediately. The closing parenthetical citing issue #10493 is motivational rather than operational and is the one sentence that does not fully earn its place.

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

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

For a 7-parameter read tool with no output schema, the definition covers purpose, ordering, filters and downstream use well; the main omission is any indication of the returned shape or paging semantics (offset/limit interplay) that an agent would need to iterate results.

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%, so most parameters are self-documenting; the description only re-lists branch/status/event as 'optional filters', which the schema already spells out (including branch ref syntax and status values). It adds no format or interaction detail beyond the schema, so the baseline 3 holds.

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 ('List a repository's workflow runs'), plus ordering and filter scope, and explicitly differentiates from the siblings it feeds (get_workflow_run / cancel_workflow_run). An agent can place it precisely in the workflow-run tool family 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?

States when to use it directly: 'this is how an agent finds the run ids to inspect or cancel', naming the two downstream tools it enables. The issue note reinforces the trigger condition (discovering stale queued runs), leaving nothing 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?

The description adds substantial behavioral detail beyond the annotations: it enumerates enforced checks, reveals the M3 soft-block behavior tied to the pre-merge risk score, explains how confirm_high_risk overrides it, and specifies the return shape. The destructiveHint is consistent with the merge action, and no contradiction exists.

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 with zero filler. It front-loads the core purpose ('Merge an open PR'), then packs behavioral caveats and return information in a logically ordered, scannable way.

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?

Even though there is no output schema, the description explicitly includes the return shape {merged, sha?, reason?, riskScore?}. It also covers prerequisites, gate checks, and the risk-override condition, giving an agent enough context to invoke the tool correctly and interpret results.

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% for all four parameters, so the baseline is 3. The description adds meaningful semantics for confirm_high_risk by explaining the M3 risk-score soft-block and the bypass behavior, going beyond the schema's simple 'bypass the M3 risk-score soft-block' phrasing. The other parameters are self-explanatory and require no extra description.

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

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

The description opens with a specific verb and resource: 'Merge an open PR.' It clearly distinguishes this tool from siblings such as gluecron_close_pr, gluecron_create_pr, and gluecron_open_draft_pr by focusing on merging an existing, open PR and the checks involved.

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 on when to use the tool: for merging an open PR that must satisfy the same checks as the HTTP merge flow. It does not explicitly name alternative tools or state when not to use it, but the context is specific enough for an agent to select it appropriately among siblings.

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

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

Annotations provide `readOnlyHint: false` and `destructiveHint: false`, indicating mutability but no destruction. The description adds the key behavior that it forces `is_draft=true`, which is beyond what annotations convey. 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?

Two sentences, no filler, delivers core message efficiently. Every sentence adds value: first defines purpose, second gives usage 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?

Given the tool is a specialized variant, the description adequately explains its unique feature (draft status) and use case. However, it assumes knowledge of the sibling tool's payload, and lacks any parameter documentation, which could hinder standalone usability for an agent unfamiliar with `gluecron_create_pr`.

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

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

Schema has 6 parameters with 0% description coverage. The description does not explain any parameters or their semantics. It only states 'Same payload as gluecron_create_pr', which is insufficient for an agent to know required fields or formats without consulting another tool's 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 the tool opens a draft pull request and distinguishes it from sibling `gluecron_create_pr` by noting the forced draft status. The verb 'open' and resource 'draft pull request' are explicit.

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 states when to use this tool: 'Useful for AI-in-progress PRs that shouldn't run mergeability checks yet.' This clearly implies when not to use it, and references the alternative `gluecron_create_pr` indirectly.

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 supply readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds genuinely new context: the required 'repo' scope and write access, plus the no-op behavior when the run is not queued, which explains why the idempotent hint holds. It does not describe the return payload for the 'reported, not changed' case.

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

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

Two tight sentences, front-loaded with the action and its effect. The parenthetical issue reference is the only near-disposable element, and everything else 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 carries return-behavior burden and does address the failure path ('reported, not changed') plus auth requirements. It is slightly thin on how to confirm the priority was applied or check queue ordering, but nothing essential for a correct call 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 only 33% — only run_id is documented (and the description's queued-state constraint restates run semantics rather than adding parameter detail). Neither 'owner' nor 'repo' is explained in the schema or the description, so two of three parameters remain undocumented. The brief mention of 'repo' scope does not compensate.

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

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

States a specific verb and resource ('Move a QUEUED workflow run into the priority lane') and immediately explains the mechanism ('the runner claims it ahead of the fair-share order across repositories'). This is easily distinguished from siblings like gluecron_cancel_workflow_run or gluecron_list_workflow_runs.

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 an explicit precondition and exclusion: 'Only queued runs; a running or finished run is reported, not changed.' The when-not case is spelled out clearly. It stops short of naming an alternative tool (e.g., how to inspect queue state), so it is strong but not exhaustive.

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) are generic. The description adds key behaviors: it rewrites prose, opens a PR, and requires 'repo' scope. This effectively communicates the mutation and permission needs 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?

The description is concise, front-loading the core purpose ('Manual trigger for the AI doc-update flow') in a single sentence. While effective, it could be slightly more structured to separate purpose from requirements.

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

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

For a tool with 2 common parameters and no output schema, the description adequately covers the main behavior and side effects (opens PR). It does not explain return values, but that is acceptable given the 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 has 2 parameters (owner, repo) with 0% description coverage. The description provides no explanation of these parameters, leaving the agent to infer their meaning. Given the low coverage, this is a significant 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?

The description clearly states the tool triggers an AI doc-update flow: scans tracked sections, rewrites stale prose, and opens a PR. The verb 'scans' and resource 'tracked sections' make the purpose specific and distinct from sibling tools like gluecron_propose_migration.

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 indicates manual triggering and requires 'repo' scope, but does not explain when to use vs alternatives (e.g., gluecron_propose_migration) or when not to use. It provides partial guidance but lacks 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 not read-only and not destructive. The description adds the scope requirement and internal function name, providing some context beyond annotations. However, it does not describe side effects, output, or implications of proposing a migration.

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 long, front-loading the core purpose. It is concise and avoids fluff, though it could integrate parameter guidance without becoming verbose.

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 7 parameters, no output schema, and low schema description coverage, the description is incomplete. It does not explain the migration process, expected output, side effects, or prerequisites beyond 'repo' scope. Context for a complex operation is lacking.

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 29% schema description coverage, the description adds no information about the 7 parameters. It fails to explain what owner, repo, dependency, from_version, to_version are, or how they are used. The description should compensate for low schema coverage 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 the tool proposes a dependency-upgrade PR, which is a specific verb+resource combination. It distinguishes from sibling tools like create_pr or propose_doc_update by focusing on dependency upgrades. Internal reference adds specificity.

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 mentions 'Requires repo scope', indicating a prerequisite, but does not explain when to use this tool versus alternatives like create_pr or open_draft_pr. No explicit when-not or alternative suggestions are provided.

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 value by disclosing the internal wrapper (pr-sandbox.provisionSandbox), an auth requirement ('repo' scope), and a specific error return when the host lacks a provisioner. This contextualizes behavior 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?

The description is three sentences (45 words) and front-loaded with the primary purpose. The second sentence adds implementation context, and the third covers a key error case. No filler or redundant information. Every sentence contributes meaningfully.

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 the tool is simple with three clear parameters and no output schema, the description does not specify the success return value or side effects. It only documents the failure case. Annotations cover destructive intent, but the description omits whether provisioning creates resources or has any rate limits. Adequate but not fully thorough for a mutation 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 0%, so the description carries the burden of explaining parameters. The parameter names (repo, owner, number) are standard and self-explanatory for a PR sandbox tool, but the description does not explicitly define them, their formats, or constraints. For example, it does not confirm that 'number' is the PR number or clarify that 'repo' and 'owner' are GitHub identifiers.

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 provisions or re-provisions a sandbox for a PR. The verb 'provision' and resource 'sandbox for a PR' are specific and distinct from sibling tools like create_pr, merge_pr, or get_pr. The mention of wrapping an internal function adds clarity without ambiguity.

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 mentions a prerequisite ('Requires repo scope') but provides no explicit guidance on when to use this tool versus alternatives. While no other tool provisions sandboxes, the description could clarify scenarios (e.g., after PR creation) or when re-provisioning is appropriate. The 'or re-provision' hint is mild 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 mark this as readOnly and non-destructive, and the description reinforces that while adding useful nuance: the risk score is qualified as to whether it describes the current head, CI state is 'as the merge gate sees it,' and AI-review verdicts are a 'trio.' This goes beyond the annotation bar, though it does not discuss staleness, caching, or failure 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?

A single front-loaded sentence that immediately states the core purpose and then enumerates the computed outputs. There is no filler, repeated metadata, or unnecessary explanation.

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

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

This tool aggregates a fairly complex status view and has no output schema, but the description lists every major result category, including a subtle head-match qualifier for the risk score. It does not give exact return shapes, but it provides enough context for an agent to select and invoke 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?

The schema has zero description coverage for all three parameters; owner, repo, and number are bare name/type declarations. The description does not add field-level semantics—it only indicates that the tool operates on a PR. Even though these are conventional GitHub identifiers, the description fails to compensate for the schema 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?

The description opens with a concrete verb and resource: 'Compute a one-shot status summary for a PR,' then enumerates the specific components included. This makes it easy to distinguish from siblings like get_pr or get_workflow_run because it is clearly an aggregation of state, risk, CI, review, and gate signals rather than a single-resource fetch.

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 'one-shot' phrasing implies that this tool consolidates data that might otherwise require multiple calls, but it never explicitly states when to prefer this tool over alternatives such as get_pr, get_workflow_run, or list_prs. Usage context is implied rather than clearly stated with exclusions or 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 already indicate read-only and non-destructive behavior. The description adds the return format {path, size, content, encoding} and the API mirror, but no additional behavioral traits such as error handling or limitations.

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 with two sentences, front-loading the purpose and providing essential return format information without any filler.

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

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

For a simple read file tool, the description covers the core purpose, return format, and API reference. It lacks notes on handling large files or encoding caveats, but these are not critical for basic use. Overall, it is reasonably complete 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 description coverage is only 40%, and the tool description does not add any parameter-level details beyond what the schema provides. Required parameters like owner, repo, path have no descriptions even in schema, and the description does not explain them.

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 'Read a file from a repo at a given ref' with a specific verb and resource, and mirrors a known API endpoint. However, it does not differentiate from the sibling tool 'gluecron_repo_read_file', which could cause confusion.

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 like gluecron_repo_read_file or other read-related tools. An AI agent would have to infer based on name alone, which is insufficient.

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 list destructiveHint=false, but the description says it 'executes' a refactor, which may modify repos. The description does not disclose the actual side effects of execution (e.g., file modifications, commits), leaving ambiguity about behavioral traits. No additional context is provided 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?

The description is relatively concise with four short sentences. It front-loads the core purpose and adds details like dry_run and scope requirement. Could be slightly more streamlined, but no waste.

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. The description describes inputs and the dry_run behavior but does not explain what the execution returns (e.g., success message, diff). For a tool with this complexity, more completeness about return values would help.

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%. The description adds minimal value; it restates the dry_run behavior and mentions the implementation file (multi-repo-refactor.ts), but the schema already adequately describes each parameter.

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 plans and executes a refactor spanning multiple repos owned by the caller. It distinguishes itself from single-repo sibling tools like gluecron_write_file or gluecron_create_branch, which operate on a single repo.

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 mentions the dry_run option returns a plan only and requires 'repo' scope. It implies when to use (multi-repo refactor) but does not explicitly state when not to use it or suggest alternatives for single-repo refactors.

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 provide readOnlyHint=false and idempotentHint=true. The description adds that it is idempotent and returns {released}, which is consistent but adds minimal new behavioral context 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 is very concise (three short sentences) and to the point. It wastes no words but could be slightly more informative without becoming verbose.

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 release operation with one parameter and no output schema, the description is fairly complete. However, it lacks explanation of what a lease is, which may be needed for full clarity.

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

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

Schema description coverage is 0%. The description mentions 'by id' but does not explain the lease_id parameter or provide context about what a lease is. For a single parameter with no schema description, the description should elaborate more.

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 releases a lease by ID and notes it is idempotent. The verb 'Release' and resource 'lease' are specific, and it distinguishes from the sibling tool 'gluecron_acquire_lease'.

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 versus alternatives. The description only states what it does, not when it is appropriate 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 value beyond annotations: it discloses the auth requirement (not in annotations) and the return shape '{state}' (useful since no output schema exists). It restates idempotence, which is already in annotations, but the added auth and return context justify a 4. 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 sentences, zero filler. The core action leads, then prerequisites, then behavior and return shape. Every sentence earns its place.

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

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

Complete for a simple 3-parameter mutation with no nested objects or output schema: purpose, auth requirement, idempotence, and return value are all covered. The only minor gap is the unspecified behavior if the issue is already open, but 'previously closed' scopes the intended 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% — all three parameters (owner, repo, number) are already documented. The description adds no parameter-level detail, so the schema carries the full 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?

'Reopen a previously closed issue' states a specific verb and resource with a clear state transition. It differentiates itself from sibling gluecron_close_issue (inverse), gluecron_create_issue (new vs existing), and comment_issue without ambiguity.

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 a clear prerequisite — 'Requires authenticated caller with write access' — which tells an agent when it can even attempt the call. It does not explicitly name alternatives or exclusions (e.g., 'use close_issue for the inverse'), but the 'previously closed' scoping implies the appropriate condition.

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 mark it read-only/non-destructive, and the description adds meaningful behavior: data is cached, only public repos are supported, freshness is tied to the most recent commit, and null is returned on cache miss. No annotation 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?

A single, front-loaded sentence carries the core operation and both important qualifications (cached, public, most recent commit, null behavior) 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?

For a simple read-only lookup with two fully documented parameters, the description covers input, scope, and return behavior (Markdown or null) despite no output schema. It could be slightly more complete by pointing to the generation sibling on cache miss.

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 owner and repo, so baseline is 3. The description does not add parameter-level syntax or format details, but none are needed beyond the schema's owner/repo definitions.

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

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

Description states a specific verb ('Return'), a precise resource (cached AI explain-codebase Markdown for a public repo), and a scope qualifier ('most recent commit'). The 'cached' and null-return behavior clearly differentiate it from the uncached gluecron_explain_repo sibling.

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 use case—fetch a cached explanation when one exists—and signals cache miss with null, but it never explicitly names an alternative such as gluecron_explain_repo or states when to prefer it. Usage context is present but exclusion/alternative guidance is left to inference.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond that by specifying the output composition, the 0-100 score range, the categories covered, and that the report reflects current state. Minor gaps like error behavior remain, but they are not critical for a read-only computation 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 description is a single, front-loaded sentence that communicates purpose and output shape efficiently. The implementation note 'Backed by computeHealthScore in src/lib/intelligence.ts' is slightly extra but not harmful; it does not prevent the description from being concise.

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

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

For a simple two-parameter, read-only tool with no output schema, the description is largely complete: it lists all key output dimensions an agent needs to judge the result. It omits exact handling of missing repos or private repos, but those are edge cases and the overall context is sufficient 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 100% and both parameters (owner, repo) already have descriptive names and explanations. The description adds only the 'public repo' framing and does not materially clarify parameter value formats or constraints 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 uses a specific verb and resource ('Compute the current health report for a public repo') and enumerates the concrete deliverable: score, grade, category breakdown, and insights. This clearly distinguishes the tool from sibling analysis tools like security_scan or explain_repo.

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 clear context: this tool is for computing a current health report on a public repo. It does not explicitly name alternatives or list when-not-to-use cases, but no direct sibling tool competes with this exact responsibility, so 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it only lists open issues (not all issues), returns up to 50, and orders by most-recent. It doesn't mention that closed issues are excluded or that the repo must be public, but the description explicitly says 'public repository' and 'open issues', which are meaningful constraints beyond the schema.

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

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

Two sentences with zero waste. The core action and scope are front-loaded, and the pagination/ordering behavior is stated compactly. Every sentence earns its place.

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

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

For a read-only list tool with 100% schema coverage and no output schema, the description is nearly complete. It covers scope, ordering, and pagination limits. It doesn't describe the response shape, but no output schema exists and the tool is simple enough that an agent can infer the return format from the parameters and the 'nextOffset' hint in the schema.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds the 'open issues' filter and 'ordered by most-recent' behavior, which gives context for the limit/offset parameters, but doesn't add per-parameter meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb ('List'), a resource ('open issues'), a scope ('for a public repository'), and a concrete behavior ('Returns up to 50 ordered by most-recent'). This clearly distinguishes it from sibling tools like gluecron_search_issues (search) and gluecron_list_prs (pull requests).

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 it: when you need open issues for a public repo, with pagination and ordering. It doesn't explicitly state when not to use it or name alternatives like search_issues, but the context is clear enough for an agent to select it correctly.

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 details beyond those: private-repo access behavior and rejection of binary files. It does not mention error cases or size limits, but it provides enough extra context to justify a score above baseline.

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 compact and front-loaded: the core purpose appears in the first sentence, followed by two useful behavioral clarifications. Every sentence earns its place without 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?

For a simple read tool, the description covers the essential return behavior (text content, rejects binary), access considerations, and ref semantics. It does not describe output details like encoding or non-binary error cases, but these are not strict gaps for an agent invoking the tool.

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

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

Schema description coverage is 100%, so the parameters are already fully documented. The description adds no new parameter semantics beyond the schema's existing statements about path, owner, repo, and ref. A baseline of 3 is appropriate because the schema carries the explanatory burden.

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 and resource: 'Read a single file from a repository at a given ref (branch / tag / commit).' It is clearly distinct from write/delete/list tools and explicitly limits scope to a single file. However, it does not differentiate itself from the very similarly named sibling gluecron_read_file, which leaves some selection ambiguity.

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 use case is implied: fetch file content at a known ref. It also gives useful context that private repos require authenticated access and that binary files are rejected. But it contains no explicit when/when-not guidance or mention of alternatives such as gluecron_read_file or gluecron_list_tree.

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 readOnly and non-destructive annotations, the description discloses case-insensitive matching, searchable fields, authentication ownership scope, and the full pagination contract (default/max per page, total count, nextOffset). This gives the agent a clear behavioral model with 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?

Two dense sentences front-load the core action and then provide essential pagination detail. There is no filler, repetition, or unnecessary elaboration.

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

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

With no output schema, the description still explains what is returned, ownership visibility, and how pagination works. It would be fully complete if it named the fields of each returned repository item and explicitly addressed the sibling search_repos ambiguity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining how offset relates to nextOffset and that total is the full match count, giving operational meaning to the pagination parameters beyond their 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?

The description clearly identifies the action: searching Gluecron repositories by keyword in name and description, with case-insensitive matching. It is specific about scope and distinguishes the tool's behavior, but it does not explicitly differentiate itself from the similarly named sibling gluecron_search_repos.

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

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

No when-to-use or alternative guidance is provided, especially relative to the near-duplicate sibling gluecron_search_repos. The scope detail about public/private repos is contextual, but it does not tell an agent when to choose this tool over other search 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?

Annotations indicate readOnlyHint=false and destructiveHint=false. The description adds context about the AI tag and gate-checker recognition, but does not fully describe side effects (e.g., creating a review, triggering notifications). Some behavioral context is provided beyond annotations, but not comprehensively.

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

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

The description is a single, front-loaded sentence with no extraneous information. Every word adds value: purpose, special tag, scope requirement.

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

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

The description adequately explains the tool's core function but does not cover return values or interaction with sibling tools like how it differs from 'gluecron_comment_pr'. Given 4 params and no output schema, more detail on param roles or outcomes would be beneficial.

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 low (25%) with only 'body' described. The description does not explain the meaning of 'owner', 'repo', 'number', or 'body' beyond what the schema provides. For a tool with 4 required params, this is insufficient compensation.

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

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

The description clearly states the tool posts a 'changes requested' AI-review comment on a PR, with a specific tag and scope requirement. It distinguishes itself from generic PR comment tools by the special role and vs sibling like 'gluecron_comment_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 mentions required 'repo' scope and implies use for AI-review changes requests. It does not explicitly state when to use vs alternatives, but the name and context differentiate it from generic comments. Sibling tools include 'gluecron_comment_pr', making the distinction 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?

Annotations flag destructiveHint=true, and the description goes further by spelling out the actual effects: no further dispatch, refused heartbeats, stops accepting jobs, and irreversibility. This is exactly the mutation impact an agent needs before calling.

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: purpose, effects and irreversibility, then return shape. Zero filler and the most important constraint (cannot be undone) 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?

With a single required param, no output schema, and destructive annotations already present, the description covers behavior, irreversibility, alternative action, and the return shape {id, revoked}. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and already documents that id is the runner id from gluecron_list_runners; the description reinforces 'by id'. There is little room to add syntax beyond the single string identifier, so this is appropriately 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 and resource ('Revoke a CI runner by id') and the schema even points at gluecron_list_runners as the source of the id. Clearly distinguishable from siblings like gluecron_list_runners and gluecron_create_runner_registration_token.

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

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

Explains the consequence and the correct alternative ('Cannot be undone — register a new runner instead'), which routes the agent to re-registration rather than retrying a revoke. No explicit when-not guidance beyond irreversibility, but the operative context 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds genuinely new behavior by disclosing the exact return payload including the `truncated` flag and the default-branch fallback when `ref` is omitted. It does not mention rate limits or error behavior, but the return-shape disclosure is valuable given no output schema exists.

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 compact sentences, front-loaded with what the tool is, then why it is dependable, then the return contract and the `ref` default. Every sentence carries information an agent needs and 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?

With five parameters, no output schema, and moderate schema coverage, the description correctly compensates by documenting the return object and the default-branch behavior. The remaining gap is that pagination/limit interplay (default 50, max 200) is left entirely to the schema and no error or empty-result behavior is described.

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

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

Schema coverage is 60%, so the schema documents `ref`, `limit`, and `query` while `owner`/`repo` are self-evident. The description's only parameter-relevant claim, 'Omit `ref` for the default branch,' restates what the schema already says, so it adds little meaning beyond the structured fields.

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