Gluecron

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

Annotations already indicate the tool is not read-only (mutating) and not destructive. The description adds the behavioral detail that the tool returns null when another agent holds an active lease. However, it does not disclose whether acquiring a new lease releases a previous one, what happens on error, or the effects of the duration_ms parameter beyond schema info.

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 wasted words. It is front-loaded with the action, then return value. While concise, it could include more useful context 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?

With 4 parameters and no output schema, the description lacks essential context. It does not explain key parameters, mention the sibling release tool, or provide guidance on lease lifecycle (timeout, release, re-acquisition) beyond the schema's duration_ms description.

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% (duration_ms and target_type have descriptions). The tool description adds no parameter information, leaving agent_session_id and target_id unexplained. This fails to compensate for the schema gaps.

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 the verb 'grab' (synonymous with acquire) and specifies the resource as an exclusive lease on a target like PR or branch for an agent session. It also describes the return behavior when the lease is held by another. This clearly distinguishes from sibling tools like gluecron_release_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?

The description implies usage for agent sessions requiring exclusive access, but does not explicitly state when to use this tool versus alternatives (e.g., when not to acquire, or that a release tool exists). No exclusion scenarios or prerequisites are 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 already declare readOnlyHint=true, so the description adds value by specifying the nature of the rollups (AI spend) and scoping. No contradictions; it complements 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?

Two sentences with no waste. The first sentence states the core function, the second details scoping. Essential 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?

The description is adequate for a simple read-only cost summary tool. No output schema exists, but the purpose and scoping are clear. It does not explain response format or rate limits, but these are not critical for selection.

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%), but the description adds significant meaning: it explains the relationship between repo and owner, and clarifies the scope options (user/repo/agent). It does not detail agent_session_id further, but the scoping clarity compensates.

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 AI spend rollups and specifies three scoping options (user, repo, agent_session_id) with a default. It is distinct from siblings like gluecron_get_agent_budget which focuses on budgets.

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 when to use each scope and the default behavior. It does not explicitly state when not to use or provide alternatives, but the context is clear enough for a straightforward read-only tool.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) indicate a non-destructive write. The description adds transparency by revealing that assignment is modeled as a label and requires 'repo' scope, providing 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?

The description is two sentences, front-loading the core purpose, and includes necessary context without 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?

The description covers the action, implementation nuance, and required scope. It lacks information about return values or success indicators, but given the tool's simplicity and lack of output schema, it is mostly 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 only 25% (only assignee has a description). The description does not add any new parameter details beyond the schema; it merely lists the parameter names in the action. With low 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 the action ('Assign an issue to a user') and the resource (issue). It distinguishes from sibling tools like gluecron_label_issue by noting that assignment is modeled as a label but the tool is specifically for assignment.

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 required 'repo' scope and explains the label-based implementation, indicating when the tool is appropriate. However, it lacks explicit guidance on when not to use it or how it differs from gluecron_label_issue beyond the implementation detail.

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 have readOnlyHint=false and destructiveHint=false, so the description appropriately adds that the tool creates branches, applies atomic commits, and requires 'repo' scope. It describes the internal blob/tree/commit/ref-update sequence. However, it does not disclose potential side effects like overwriting existing branches or concurrency behavior. Overall 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?

The description is two sentences, front-loading the core purpose in the first sentence and providing details in the second. No redundant or unnecessary words. 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?

Given the tool's complexity (atomic multi-file commit, branch creation), the description covers the main functionality, scope requirement, and change format. However, it does not explain return values (no output schema), error scenarios, or the base_branch parameter's role fully. It is adequate but could be more complete with a brief note on behavior when branch already exists.

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 low (33%), so the description should compensate. It partially does by explaining the changes array format (path, content, content_base64, deleted) and noting required scope, but does not explain parameters like owner, repo, branch, message, or base_branch beyond what the schema already states. The description adds marginal value over the schema for some parameters but leaves others undocumented.

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 applies a set of file writes/deletes as a single atomic commit on a branch, even creating the branch if needed. It specifies verb ('commit') and resource ('file writes/deletes on a branch'), and distinguishes from sibling tools like gluecron_write_file which do single operations.

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 calls it the 'killer agent tool' and implies it's for atomic multi-file commits, but does not explicitly state when to use it vs alternatives like gluecron_write_file or gluecron_delete_file. It mentions the required scope ('repo') but lacks explicit when-not-to-use guidance. Context signals show sibling tools for single files, so usage is clear but not fully 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 already set destructiveHint=true, indicating a destructive action. The description adds that the tool requires 'repo' scope, which is useful. However, it does not disclose behavioral traits beyond that, such as irreversibility or success/failure conditions. With annotations covering the safety profile, the description adds moderate 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 very concise: two sentences that front-load the primary action and immediately mention a prerequisite. No unnecessary words. 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?

Given that this is a destructive action with no output schema, the description is too minimal. It does not explain return values, error cases, or what happens after cancellation. For a tool of this complexity, more completeness is warranted.

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 description provides no information about the three parameters (owner, repo, run_id) despite 0% schema description coverage. It does not explain their meaning, format, or how they are used. The tool relies entirely on the schema, which is insufficient for an agent.

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 action ('Cancel') and resource ('workflow run'), and specifies the state ('queued/running'). It also mentions the required scope ('repo'). This distinguishes it from sibling tools like gluecron_trigger_workflow and gluecron_get_workflow_run.

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 cancelling a queued or running workflow run, but it does not provide explicit guidance on when not to use it or mention alternatives. The usage context is clear but lacks exclusions or comparative 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?

The description indicates a write operation (sending a message), which aligns with readOnlyHint=false. However, it does not disclose other behavioral details such as whether the chat must exist, what happens on failure, expected latency, or additional side effects like token consumption. The description adds little beyond the 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?

The description is extremely concise: two sentences that directly state the action and the output. No extraneous words or 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?

Given the simplicity of the tool (2 params, no output schema), the description is too minimal. It does not explain the prerequisite that a chat must have been started, how to create a chat_id, or what to expect in the assistant's reply. The context for proper use is incomplete.

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 input schema has 0% description coverage, so the parameter meaning relies entirely on the tool description. The description does not explain what chat_id refers to (e.g., how to obtain it) or the expected format of message. This is a significant gap for a tool with two 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?

The description clearly states the action 'send another message' and the resource 'existing repo chat', and mentions the return of the assistant's reply. However, it does not explicitly distinguish this from the sibling tool gluecron_chat_with_repo, which may start a new chat.

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, such as when to start a new chat versus continue an existing one. There is no mention of prerequisites (e.g., an existing chat_id) or when not to use this tool.

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

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

The description details the tool's behavior (creates, sends, streams, persists, returns) beyond annotations. It clarifies it is not read-only and not destructive, but could elaborate on streaming semantics or side effects.

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

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

Two sentences, front-loaded with core purpose, each sentence adds value. 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?

Given no output schema, the description adequately hints at return structure ({chat_id, reply}). It covers key behavioral aspects but could specify parameter details for owner and repo.

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% (title and message have descriptions). The overall description adds little beyond the schema; 'owner' and 'repo' lack descriptions. The tool's purpose implies they are identifiers but no further details.

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 purpose: 'Start a new chat with a repo', with specific actions (creates chat row, sends first message, streams+persists reply). It effectively distinguishes from the sibling tool 'gluecron_chat_continue' by indicating initiation.

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 authentication' and implies use for starting new chats, distinguishing from 'gluecron_chat_continue'. However, it does not explicitly state when not to use or provide alternative scenarios.

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, so the description adds value by specifying the return shape ({url, hint}). It does not contradict annotations, and the safety profile is clear. No additional behavioral traits are disclosed 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 extremely concise with only two sentences, no wasted words, and front-loaded with the core purpose. 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 simplicity, no output schema, and that the description explains the return object ({url, hint}), it is fully complete. It covers all necessary context for an agent to use 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?

Input schema has 100% description coverage for both parameters (repo and owner), so the schema already provides meaning. The description does not add new semantic information beyond what the schema offers.

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 the authenticated HTTPS clone URL and a credential helper hint. The verb 'Return' and the resource 'clone URL for a repo' are specific. No sibling tool performs this exact function, so it is well-distinguished.

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 advises using this tool instead of embedding tokens in URLs, providing clear usage context. However, it does not mention when not to use it or list alternative tools, but the context is sufficient for a simple tool.

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

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

Beyond annotations (idempotentHint, destructiveHint), the description adds authentication requirement and return value format ('Returns {state}'). No contradictions 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 concise sentences, first sentence states core action. No unnecessary words 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?

Given the tool's simplicity, annotations cover idempotency and destructiveness. Description adds auth requirement and return info (no output schema). Sufficient for accurate invocation.

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

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

Schema coverage is 100%, so baseline 3 applies. Description does not add parameter details beyond schema, but the schema descriptions are already clear.

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 'Close an open issue' with a specific verb and resource. While it distinguishes from siblings like close_pr and reopen_issue by name, it lacks explicit differentiation from related tools such as comment_issue or 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?

Specifies prerequisite: 'Requires authenticated caller with write access.' Also notes idempotency, guiding safe repeated use. Does not explicitly contrast with alternative tools, but name and context are sufficient for common scenarios.

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 destructiveHint and idempotentHint; description reinforces idempotency, adds auth requirements, and specifies return format {state}, adding behavioral 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, front-loaded with the core action, no filler. Every sentence adds value: purpose, auth, idempotency, 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?

For a simple close operation with straightforward parameters, description covers essential aspects: action, permission, idempotency, output. No gaps given the tool's complexity.

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

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

Schema description coverage is 100%; each parameter has a brief description. Description does not add extra parameter details beyond the schema, earning the baseline score of 3.

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

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

Description explicitly states 'Close an open pull request without merging,' which clearly identifies the verb (close) and resource (pull request). The phrase 'without merging' differentiates it from sibling merge_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?

Includes 'Requires authenticated caller with write access' and 'Idempotent,' providing context for when to use. Implicitly contrasts with merge_pr via 'without merging,' but no explicit when-not-to-use alternatives are listed.

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 destructiveHint=false and readOnlyHint=false. The description adds that write access is required and discloses the return value '{commentId}', providing useful context 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 two sentences, concise and front-loaded with the primary action. Every sentence provides essential information without 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 comment tool with no output schema, the description covers the action, auth requirement, and return value. It is adequate for the tool's complexity, though no further details about side effects or behavior are needed.

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 descriptive parameter names and descriptions. The tool description does not add additional meaning beyond the schema, so a baseline 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 'Add a comment to an existing issue', clearly identifying the action (add), resource (comment), and target (existing issue). This distinguishes it from siblings like gluecron_comment_pr (comment on PR) and gluecron_create_issue (create 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 mentions 'Requires authenticated caller with write access', which is a prerequisite but does not explicitly guide when to use this tool versus alternatives like gluecron_comment_pr for pull requests. Usage context is implied but not clearly differentiated.

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 important behavioral context beyond annotations: requires write access and returns {commentId}. Annotations only indicate it is not read-only and not destructive, so the description supplements well.

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 succinct sentences: first states purpose and requirement, second states return value. 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?

For a simple comment creation tool, the description covers the purpose, auth requirement, and return value. The schema fully documents all 4 parameters. No 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?

All parameters are fully described in the schema (100% coverage). The description mentions that the body is Markdown, which is already in the schema, so no additional semantic 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 the action 'Add a comment to a pull request', using a specific verb and resource. It is distinct from sibling tools like comment_issue or close_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 specifies that the caller must have write access, providing a clear prerequisite. However, it does not explicitly exclude use cases or mention alternative tools like comment_issue, though the name is self-explanatory.

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 annotations (readOnlyHint=false, destructiveHint=false), the description adds critical behavioral info: the token is returned exactly once and must be stored. It also discloses the admin scope requirement, providing valuable context.

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

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

Two concise sentences deliver purpose, key behavior, and a prerequisite. No unnecessary words; 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?

With 4 parameters and no output schema, the description covers the main return value (token) and overall behavior. It could elaborate on the effect of optional parameters but the schema covers them, making it adequately complete.

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

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

Schema description coverage is 100%, so the input schema already documents all parameters. The description does not add further parameter-level meaning beyond what the schema provides, meeting the baseline.

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

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

The description clearly states it 'Mint a new agent-multiplayer session,' using a specific verb and resource. It uniquely identifies this tool among siblings, as no other sibling creates sessions.

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 mentions the prerequisite 'Requires admin scope,' guiding on access. It does not specify when not to use or list alternatives, but the tool's purpose is distinct, so usage 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 indicate readOnlyHint=false and destructiveHint=false, and the description confirms it creates a new branch (non-destructive write). It adds behavior beyond annotations by specifying the required scope and return format.

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

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

The description is concise and front-loaded, consisting of three short sentences that each provide essential information 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 tool's simplicity (4 parameters, no output schema), the description covers the purpose, API mirror, required scope, and return format. It is adequately complete for an agent to use effectively.

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 sha and branch have descriptions). The description adds minimal value beyond schema: it clarifies sha is the target commit and branch is a new name, but does not explain owner or repo. Baseline is 3.

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

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

The description clearly states 'Create a new branch ref pointing at an existing sha', providing a specific verb and resource. It distinguishes from sibling tools by its unique git branch creation function.

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 required 'repo' scope and mirrors a specific API endpoint, offering clear context. However, it does not explicitly state when to use this tool versus alternatives, though no direct 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?

Adds beyond annotations by specifying write access requirement and return format {number, url}. Annotations already indicate non-destructive mutation; description provides additional context.

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

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

Two sentences, front-loaded with purpose, 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?

Provides return shape and access requirement, which complements the schema. Could mention error cases or idempotency but overall 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?

Schema description coverage is 100%. Description adds no extra meaning beyond what is in the schema for 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 description clearly states the verb 'Create' and resource 'issue on a Gluecron repository'. It is distinct from sibling tools like close_issue, comment_issue, etc.

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?

Describes prerequisite (authenticated caller with write access) which helps the agent know when to invoke. Does not explicitly exclude alternatives, but 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 indicate readOnlyHint=false and destructiveHint=false, and the description adds key behavioral context: requires write access, returns {number, url}, and defaults base_branch to repo default. This goes beyond annotations to inform the agent about side effects and outputs.

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 sentences that front-load the purpose and follow with essential details. Every sentence earns its place without 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 the tool's complexity (6 params, 4 required, no output schema), the description covers the core purpose, authentication, return format, and default behavior. Missing details like error cases or idempotency, but sufficient for a typical create operation.

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

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

The input schema has 100% description coverage for all 6 parameters. The description adds value by clarifying that head_branch is required and base_branch defaults to the repo default branch, but the schema already provides adequate descriptions. Thus, baseline 3 with slight improvement.

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 'Open a new pull request' with specific verb and resource. It distinguishes from sibling tools like merge, close, and draft PR by focusing on creation. The details on required head_branch and default base_branch further clarify the scope.

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

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

The description explicitly mentions when to use this tool (opening a PR) and includes prerequisites: authenticated caller with write access. However, it does not explicitly compare with alternatives like open_draft_pr or when to use which, hence a slight deduction.

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 destructiveHint=true, so the description's mention of deletion via git plumbing adds context but no significant behavioral insight beyond what annotations 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?

Two sentences, front-loaded with key information, no fluff. Ideal conciseness.

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 6 required parameters and no output schema, the description lacks details on return value, error handling, or behavior (e.g., what if file doesn't exist?). Incomplete for a destructive operation.

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

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

Schema coverage is only 17% (only sha has a description). The description adds meaning to sha (existing blob) but provides no detail on owner, repo, path, branch, or message, leaving most parameters opaque.

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

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

The description clearly states the tool deletes a file from a branch via git plumbing, a specific verb+resource combination. It distinguishes from siblings like write_file or read_file.

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

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

The description mentions requirements (existing blob sha, 'repo' scope), implying when it can be used, but does not explicitly contrast with alternatives like delete_repo or provide when-not-to-use 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 annotations (destructiveHint=true, readOnlyHint=false), the description specifies the precise scope of deletion (only the database row, not disk data) and the return value. This adds useful behavioral context.

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

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

Two sentences with zero wasted words. The action is front-loaded ('Permanently delete...'), followed by key constraints 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 tool's simplicity (2 required params, no output schema, no nested objects), the description covers purpose, side effects, permissions, and return value comprehensively.

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 basic descriptions for both parameters. The description adds no further semantic detail about the parameters themselves. The 'Owner-only' note marginally relates to the owner parameter but does not enhance its meaning beyond the schema.

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

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

States 'permanently delete a repository row' which is a specific action on a specific resource. The distinction that git data on disk is left untouched clearly differentiates this from other delete operations like delete_file.

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

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

Explicitly states 'Owner-only. Requires admin scope.' This provides clear permission requirements for using the tool, guiding appropriate invocation. No explicit when-not-to-use or alternative tools are 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 already mark readOnlyHint=true. Description adds that it never triggers new generation and is pure read, which reinforces and adds value beyond annotations. Could mention output format more explicitly.

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 concise sentences with no wasted words. Clearly 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?

Sufficient for a simple read tool with annotations, but fails to describe parameters, which is a gap. Lacks output schema info.

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 description should compensate, but it only mentions 'repo' indirectly without explaining either parameter (owner, repo). No additional meaning provided.

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?

Clearly states it returns cached AI explain Markdown for a repo. Distinguishes from generation tools but does not explicitly differentiate from the similarly named sibling gluecron_repo_explain_codebase.

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 clear context (cached read) and when not to use (use web UI for new generation). Does not mention alternative siblings like gluecron_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 provide readOnlyHint and destructiveHint, so the safety profile is clear. The description adds that it wraps a specific internal function, but does not elaborate on other behaviors like error handling or output format.

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

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

Two sentences with no extraneous information. The first sentence conveys the core purpose; the second provides implementation context efficiently.

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 and three parameters, the description should explain the return format or behavior. It does not mention what 'definitions' means or the structure of results, leaving the agent underinformed.

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 one of three parameters (name) has a brief description in the schema. The description does not explain owner or repo, and the overall parameter semantics are not improved 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 the action ('find definitions'), the resource ('a symbol by name within a repo'), and uses a specific verb. It distinguishes itself from siblings like gluecron_semantic_search by focusing on definitions.

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 like gluecron_semantic_search or other search tools. No context about prerequisites or exclusion 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?

Annotations already indicate the tool is not read-only and not destructive. The description adds the scope requirement and return format, providing useful 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 extremely concise, using three short sentences to convey purpose, HTTP mapping, return value, 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 adequately covers the return structure and a key requirement. It is informative but could benefit from mentioning potential delays or failure 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?

Schema coverage is 100% with clear parameter descriptions. The description does not add further semantic detail beyond the schema, so 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 clearly states the action (fork), the resource (repository), and the destination (authenticated caller's namespace). It distinguishes from sibling tools like clone_url and create_repo by specifying the unique outcome.

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 is provided on when to use this tool versus alternatives such as clone_url or create_repo. The only contextual hint is the required 'repo' scope, but no when-not-to-use or explicit comparison.

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's safety profile is clear. The description does not add behavioral details beyond stating it uses the same engine as another tool, but 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?

The description is a single, efficient sentence that communicates the core purpose and differentiation. No extraneous words or 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 generation tool with no output schema, the description is adequate. It explains the tool's purpose and distinguishes it from a sibling. It does not describe the return value, but the tool is straightforward and the agent can infer it likely returns a commit message string.

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 with 50% description coverage. The description adds the context that the first parameter represents a 'diff', but does not elaborate beyond the parameter's type. The second parameter 'style' is fully described in the schema. This provides marginal additional value.

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

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

Description clearly states the action ('Generate a commit message') and the resource ('for a diff'). It explicitly differentiates from the sibling tool gluecron_generate_pr_description, specifying that this is for commit messages specifically.

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 explicit guidance on when to use this tool vs the alternative: 'Same engine as gluecron_generate_pr_description but explicit for the commit-message use case.' This tells the agent to use this for commit messages and the other for PR descriptions.

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 annotation, the description adds valuable behavioral context: it internally uses src/lib/ai-commit-message.ts and gracefully degrades to a heuristic when ANTHROPIC_API_KEY is missing. This informs the agent about potential failure modes and fallback behavior.

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

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

The description is extremely concise: two sentences that front-load the purpose, then add implementation details and output format. Every sentence adds unique value 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 the tool's simplicity (2 parameters, no output schema, annotations present), the description covers the core functionality, internal implementation, and output format. It is missing details about the 'style' parameter options (conventional vs plain) and prerequisites for the diff input, but overall it is sufficiently complete.

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

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

The schema covers both parameters with descriptions (100% coverage). The tool description does not add extra meaning to the parameters—it merely restates the purpose. However, it does mention the return format ({subject, body}), which indirectly helps parameter understanding by clarifying the output.

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 an AI commit-message-style description for a diff. It specifies the resource (diff) and action (generate description), but does not explicitly differentiate from sibling tools like gluecron_generate_commit_message or gluecron_generate_release_notes, which may lead to 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. It does not mention scenarios where this tool is preferred or excluded, nor does it reference sibling 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 already indicate readOnlyHint=true and destructiveHint=false. The description adds return format details (rendered Markdown + section data) and the internal function wrapped, providing moderate transparency 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 with no wasted words. The purpose and return are front-loaded, making it easy to parse quickly.

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 4 parameters and no output schema, the description covers purpose and return type adequately. However, it omits details like whether tags must exist or the nature of 'section data', leaving minor 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 50% (owner and repo lack descriptions). The tool description does not add any parameter-level details to compensate for the missing 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 states it generates release notes between two tags, specifying the verb and resource. It distinguishes from siblings like commit message generation by mentioning tags and the return of Markdown and section data.

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

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

No guidance on when to use this tool vs alternatives like gluecron_generate_commit_message or gluecron_generate_pr_description. Missing explicit conditions or caveats for use.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) already indicate modification but not destruction. The description adds mode details but does not disclose full behavioral traits like creating PRs or committing, beyond what annotations hint.

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: two sentences with front-loaded purpose, 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?

The tool is moderately complex with 4 params and no output schema. The description fails to explain return value or side effects (e.g., PR creation, commit details), leaving significant gaps despite annotations.

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

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

Schema coverage is 50% (mode and number have descriptions). The description explains the two mode options, but does not clarify owner and repo beyond requiring 'repo' scope, leaving some ambiguity.

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

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

The description clearly states the tool generates tests for a PR via Claude, naming the internal wrapper function and specifying two modes. This distinguishes it from siblings like create_pr or close_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 the two modes and the required 'repo' scope, providing clear context for use. However, it lacks explicit when-not-to-use or alternatives 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 already indicate readOnlyHint=true and destructiveHint=false. The description adds value by specifying the exact output fields (spent, cap, remaining), confirming it is a non-destructive read operation. 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 a single sentence with only 10 words, front-loading the key output values (spent, cap, remaining). Every word serves a purpose; no fluff 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?

For a simple one-parameter read-only tool without an output schema, the description adequately lists the return values (spent, cap, remaining cents). However, it lacks details on the unit interpretation and session ID context, making it minimally 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 single parameter agent_session_id has 0% schema description coverage. The description only implies its necessity by saying 'for an agent session' but does not explain its format, constraints, or how to obtain it, leaving the agent without sufficient 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 the tool returns spent, cap, and remaining cents for an agent session. It uses a specific verb ('Return') and resource (agent session budget), and distinguishes it from siblings which are focused on other actions like creating sessions or generating data.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, exclusions, or contexts where this tool is preferable, leaving the agent to infer usage from the name and sibling list.

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 reinforces read-only behavior without adding new disclosures (e.g., rate limits, response format). 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?

Two concise sentences that front-load the core purpose. No fluff; every word 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 fetch tool, but lacks details on return format (no output schema) and what 'metadata' includes. Could be more helpful with a brief list of fields.

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

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

Schema coverage is only 33% (only 'sha' has a description). The description adds 'by SHA' but does not explain 'owner' or 'repo' parameters. It fails to compensate for the low 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?

Description clearly states 'Fetch a single commit's metadata by SHA', providing a specific verb and resource. It distinguishes from sibling tools (e.g., gluecron_get_pr) by focusing on commits.

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 explicit guidance on when to use this tool versus alternatives (e.g., listing commits or other commit operations). Usage is only implied by the name and description.

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. Description adds the nuance that authenticated callers are required while anonymous read surface still works, adding value 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: first captures purpose and output, second adds authentication context. No filler, front-loaded, 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?

Fully specifies returned fields (no output schema), states authentication requirements, and all parameters are documented. Complete for a simple fetch 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 covers all three parameters with descriptions, so baseline is 3. Description does not add extra 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?

Description specifies verb 'Fetch' and resource 'pull request detail record', listing the specific fields returned. It clearly distinguishes this from sibling tools like list_prs (list) or close_pr (mutate) by emphasizing it retrieves a full single record.

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 authentication requirement and notes anonymous read surface works, providing clear context. Does not explicitly mention when not to use or alternatives, but the purpose is well-defined.

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, so the description's value is limited to specifying the return (URL+status). It adds modest context but does not disclose error handling or authentication needs.

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

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

Two sentences, no filler. The first sentence states the core purpose, the second provides implementation context. Every word 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 and presence of readOnlyHint annotation, the description is mostly adequate but lacks detail on the return structure (URL format, status values) and error cases. No output schema to compensate.

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 0% description coverage, and the description only mentions repo and branch, omitting owner. It does not explain any parameter's format, constraints, or how they map to the preview API.

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 clearly states the tool returns the branch-preview URL and status for a repo-branch pair, with a specific verb and resource. No sibling tool overlaps with 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 implies use when needing a preview URL, but does not explicitly state when to use or avoid this tool compared to alternatives. No guidance on prerequisites or when not to use.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the description's mention of 'Return... logs' is consistent. It adds context about the output format (concatenated, JSON-friendly) and metadata inclusion, but does not disclose potential edge cases like log size limits. With annotations covering safety, the description adds some but not rich behavioral detail.

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, well-structured sentence of about 20 words. It immediately states the main action and distinguishes from an alternative, with no wasted words. Ideal for quick parsing.

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 relative simplicity (3 standard parameters, no output schema), the description adequately conveys the return value (logs + metadata) and format (JSON-friendly). It provides enough context for an agent to understand what to expect, though it omits details like pagination or size limits, which are minor for this use 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 0%, and the description does not explain any of the three required parameters (owner, repo, run_id). While the tool name and context may imply run_id is a workflow run, the description fails to clarify parameter semantics, leaving a significant gap for agent understanding.

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 explicitly states the tool returns 'concatenated per-job logs for a workflow run, plus per-job metadata', which clearly identifies the action and resource. It distinguishes itself from the 'ZIP-download endpoint', a likely alternative, 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 hints at an alternative ('JSON-friendly companion to the ZIP-download endpoint') but does not name a specific tool or provide explicit when-to-use vs when-not-to-use guidance. No other usage cues are given, leaving the agent to infer context from the tool name and siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that it returns metadata+status and mirrors GET, but no additional behavioral details like error handling or authorization.

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 sentence with clear verb and API reference, no wasted words. Front-loads the purpose.

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 read-only tool with clear parameters. Lacks details on output format or error cases, but output schema is absent. Could mention that run_id is required.

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 0% description coverage, and the description does not elaborate on any of the 3 required parameters (owner, repo, run_id). Parameter names are self-explanatory but no added value.

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

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

Clearly states verb 'Fetch' and resource 'workflow run's metadata + status'. Distinguishes from siblings like get_workflow_logs and cancel_workflow_run by specifying it mirrors a GET endpoint.

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 context that it is a read operation mirroring an HTTP GET, but does not explicitly state when to use versus alternatives or mention any prerequisites.

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

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

Beyond the annotations (readOnlyHint false, destructiveHint false), the description adds important behavioral context: labels are created if they don't exist on the repo. It also mentions the return value structure ({labels}). This provides useful transparency about side effects and output, exceeding what annotations alone convey.

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

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

The description is extremely concise—two sentences—and front-loads the primary action. Every sentence adds value: the first states the main function, the second adds scope and return type. No unnecessary words 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?

Given the tool's relative simplicity and the absence of an output schema, the description covers the key aspects: what it does, side effects (auto-create labels), auth requirement, and return value. It lacks details on error handling, label name validation, or rate limits, but for a straightforward labeling tool, it provides sufficient 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%, with only the 'labels' parameter described ('Label names (strings)'). The description adds context that labels are 'one or more' and mentions auto-creation, but does not explain the meaning of 'owner', 'repo', or 'number' parameters beyond what is implicit. It partially compensates for the low schema coverage but lacks detail on parameter constraints or formats.

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 'Attach one or more labels to an issue', identifies the resource ('labels' and 'issue'), and distinguishes itself from the sibling tool 'gluecron_unlabel_issue' by implying the opposite operation. The mention of auto-creating labels further clarifies the tool's specific behavior.

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 usage requirement ('Requires 'repo' scope'), which is important for authorization. However, it does not explicitly state when to use this tool versus alternatives like 'gluecron_unlabel_issue' or other issue-related tools. The guidance is present but not comprehensive.

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. Description adds that it requires authentication and returns up to 50 summary rows, providing useful behavioral 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, front-loaded with purpose and constraints. Every sentence adds value without 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?

For a list tool with fully documented parameters and annotations, the description is adequate. However, it lacks details about the return format (what 'summary rows' contain) and pagination beyond the 50-row limit, leaving gaps for an agent.

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 each parameter fully described. The description repeats the state filter options which are already in schema, adding no new semantic information for 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?

Description clearly states the verb 'List' and resource 'pull requests on a repo' with a filtering by state. It distinguishes from siblings like search_prs (which would use search queries) and get_pr (single PR retrieval).

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 explicit when-to-use or when-not-to-use guidance. The description implies it's for simple listing by state, but doesn't contrast with alternatives like search_prs for complex queries. 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 declare read-only and non-destructive behavior. Description adds value by specifying the recursive option and API mirroring, providing additional 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, front-loaded with purpose, no extraneous text. Efficient and clear.

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, but description implies a list of files. Adequate for typical tree listing; could mention pagination or limits but not critical.

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 40% of parameters are described in schema. Description adds meaning for 'recursive' but does not explain 'path', 'owner', 'repo', or 'ref' beyond what schema provides. Partial compensation.

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

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

Description clearly states it lists directory contents at a ref, providing a specific verb and resource. Distinguishes from sibling tools by focusing on tree listing, not search or file reads.

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?

Description indicates when to use recursion via optional parameter, but does not explicitly mention when not to use or list alternatives. Context is adequate for a simple listing tool.

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

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

Annotations already set destructiveHint=true, but the description adds value by detailing the enforced checks (draft status, SHA, gates) and the M3 soft-block mechanism, including the confirm_high_risk bypass. It also specifies the return format.

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

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

The description is two sentences with no fluff. It front-loads the purpose and packs essential behavioral details efficiently.

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 provides the return fields {merged, sha?, reason?, riskScore?} which is helpful. It covers the merge behavior and conditions. It could mention error scenarios, but overall it is complete for a merge operation.

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

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

Schema description coverage is 100%, so the schema already documents parameters adequately. The description adds minimal extra meaning by explaining the context of confirm_high_risk in relation to the M3 soft-block, but this is not a significant addition 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 starts with 'Merge an open PR,' a clear verb+resource pair. It distinguishes itself from sibling tools like 'close_pr' and 'create_pr' by detailing the merge-specific checks and return format.

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 clearly states when to use the tool (to merge an open PR) and outlines conditions like not being a draft and passing gates. However, it does not explicitly mention when not to use it or alternatives, but the context is sufficiently 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?

Discloses the key behavioral trait of forcing draft status and references the sibling tool's behavior. Annotations show readOnlyHint=false and destructiveHint=false, which align. Does not detail error handling or side effects, but the core mutation behavior is clear.

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 concise sentences, front-loaded with the essential action. Every sentence adds value without 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?

Provides the core purpose and usage context, but with 6 undocumented parameters and no output schema, it lacks completeness. The sibling reference partially helps but requires additional look-up.

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% and the tool description does not describe any parameters. It only says 'Same payload as gluecron_create_pr', which assumes prior knowledge and does not compensate for the lack of 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?

Clearly states it opens a draft pull request and distinguishes from gluecron_create_pr by highlighting the forced is_draft=true behavior.

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

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

Explicitly says 'Useful for AI-in-progress PRs that shouldn't run mergeability checks yet', providing a clear use case. However, does not explicitly mention when not to use or alternatives beyond referencing the sibling.

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. The description adds context: it scans tracked sections, rewrites stale prose, and opens a PR. This explains the non-destructive mutation behavior beyond annotations, though it omits details like rate limits or authentication specifics.

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 concise sentences with no redundant information. It front-loads the purpose and includes a key requirement (repo scope), earning its place efficiently.

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 2 params and no output schema, the description covers the action and the outcome (opens a PR). However, it does not describe the return value (e.g., PR URL) or clarify what 'tracked sections' means, leaving some gaps given no output schema.

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

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

Schema description coverage is 0% and the description does not provide any meaning for the 'owner' and 'repo' parameters. With 0% coverage, the description must compensate but fails to do so, leaving the agent to infer from convention.

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's a manual trigger for AI doc-update flow, specifying it scans tracked sections and opens a PR rewriting stale prose. This is a specific verb+resource with clear distinction from sibling tools like create_pr or open_draft_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 it's a manual trigger and requires 'repo' scope, but does not explicitly state when to use this tool vs alternatives like create_pr or open_draft_pr. Usage context is implied but not differentiated, limiting 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 indicate readOnlyHint=false and destructiveHint=false. The description adds that it wraps an internal function but does not explain side effects, permission needs beyond scope, rate limits, or what happens during PR creation. Minimal behavioral 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?

The description is extremely concise with two sentences, no redundant information, and front-loaded purpose. Every word serves a function.

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 complexity (7 parameters, internal function call, no output schema), the description is too sparse. It lacks details about PR creation process, branch handling, return values, and error conditions. The wrapper function name provides some internal context but does not make the tool complete for an agent.

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?

Parameter schema coverage is only 29% (2 of 7 parameters described). The description does not elaborate on any parameter meanings, formats, or constraints. Parameter names are somewhat self-explanatory, but this is insufficient for an agent to use the tool correctly without additional context.

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, with a specific verb and resource. However, it does not explicitly distinguish from similar sibling tools like gluecron_create_pr or gluecron_propose_doc_update, which slightly reduces clarity.

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

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

The description only mentions a scope requirement ('Requires repo scope') but provides no guidance on when to use this tool vs alternatives like generic PR creation tools. No when-not-to-use or exclusion criteria 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 it is not read-only and not destructive. The description adds that it can re-provision (implying idempotency) and requires 'repo' scope, both useful. However, it does not describe side effects, async behavior, or return values, so transparency is adequate but basic.

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

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

The description is short and front-loaded with the main action. It wastes no words, though it could improve by briefly describing parameters. The structure is efficient for its length.

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 complexity (provisioning likely creates resources), the lack of an output schema, and missing parameter explanations, the description is insufficient. It does not explain what the sandbox is, how to access it, or what the agent can expect after provisioning.

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% (no descriptions in the schema) and the description adds no explanations for the three required parameters (owner, repo, number). The description mentions 'for a PR' but fails to explicitly map parameters to their roles, which is a critical 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 it provisions or re-provisions a sandbox for a PR, using a specific verb and resource. The name and description are well-aligned, and no sibling tool directly competes. However, it could be clearer what a 'sandbox' refers to, leaving some 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 guidance on when to use this tool versus alternatives or when not to use it. There is no mention of related tools or context for decision-making, leaving the agent without sufficient usage boundaries.

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 little beyond repeating 'Read-only' and listing outputs. It does not disclose rate limits, pagination, or other behavioral details.

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 sentence front-loaded with key information. No redundancy or unnecessary 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?

Adequate for a read-only summary tool with annotations covering safety. However, lacks parameter details and output format info (no output schema, no description of return structure).

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 3 parameters with 0% description coverage. The description does not explain or document any parameters (owner, repo, number) beyond their existence 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?

Description clearly defines the tool's purpose: 'Compute a one-shot status summary for a PR' and lists specific outputs (state, risk score, AI-review verdicts, gate signals). Distinguishes from siblings like get_pr or list_prs by emphasizing it's a summary.

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 explicit guidance on when to use versus alternatives such as get_pr or search_prs. The description only states 'Read-only' but does not provide context for tool selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds some value by stating the return format and API mirror. But no additional behavioral details (e.g., file size limits, encoding handling) beyond what annotations 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?

Two sentences, no redundancy. First sentence states purpose, second gives return format. 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 5 parameters, no output schema, and many siblings, the description provides return format and API reference, which is helpful. However, it lacks usage context, error handling, or differentiation from very similar sibling gluecron_repo_read_file. Still, adequately covers the core functionality.

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 40%, with only ref and encoding having descriptions. The tool description does not elaborate on owner, repo, or path parameters, leaving their meaning somewhat implicit. Schema covers the semantics partially, but description adds little 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?

Description clearly states 'Read a file from a repo at a given ref' with specific verb and resource. Distinguishes from siblings like gluecron_repo_read_file by specifying the API endpoint and return format.

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?

Description implies when to use (to read a file) but provides no comparison to siblings or conditions when not to use. No alternative tool mentioned, leaving selection to agent 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 provide readOnlyHint=false and destructiveHint=false, indicating a mutation that is not considered destructive. The description adds the dry_run behavior and scope requirement, but it does not clarify the actual impact of execution (e.g., what changes are made, whether changes are reversible). While no direct contradiction with annotations exists, the description could be more transparent about the tool's effects.

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 sentences plus one line about scope. The purpose is front-loaded, and every sentence provides necessary information without fluff. 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?

For a complex multi-repo refactor tool, the description is adequate but leaves some gaps. It does not explain what the plan contains, what happens during execution, error handling, or return value format. Given the presence of detailed schema descriptions and annotations, the description meets minimum viability but is not comprehensive.

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 each parameter having a clear description. The tool description adds a redundant note about dry_run behavior and mentions 'repo' scope (not a parameter). Since the schema already fully documents parameters, the description adds minimal value beyond the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Plan + execute a refactor that spans multiple repos owned by the caller.' It identifies the specific verb (plan+execute), resource (multi-repo refactor), and scope (repos owned by the caller). This distinguishes it from sibling tools like propose_migration or atomic_multi_file_commit.

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 key usage pattern ('dry_run: true returns the plan only') and a prerequisite ('Requires repo scope'), but it does not explicitly compare this tool to alternatives or specify when not to use it. The implementation detail ('Wraps src/lib/multi-repo-refactor.ts') is not helpful. Overall, usage guidance is implied but lacks exclusions or context for sibling differentiation.

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 return value '{released}' and confirms idempotency, which aligns with the idempotentHint in annotations. However, no additional behavioral traits (e.g., authorization, rate limits, side effects) are disclosed beyond what annotations already 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?

The description is extremely concise with two short sentences that convey the core action, idempotency, and return value. Every word is functional, and there is no unnecessary 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?

Given the low complexity (one parameter, simple action) and annotations covering idempotent and destructive hints, the description is nearly complete. However, the lack of parameter description and usage context (e.g., when to release) leaves minor gaps that could confuse an agent.

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 input schema has one parameter 'lease_id' with no description, and the tool description does not explain what the lease ID represents or its format. With 0% schema description coverage, the description fails to compensate, leaving the agent without guidance on how to fill the 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 verb 'Release' and the resource 'lease by id', making the tool's action specific and unambiguous. It also uses 'Idempotent' to indicate safety. The sibling tool 'gluecron_acquire_lease' contrasts the opposite action, so the purpose is well-distinguished.

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 does not provide explicit guidance on when to use this tool versus alternatives like 'gluecron_acquire_lease'. It simply states the action, leaving the agent to infer usage from the name and context. No when-not-to-use or prerequisites are 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?

Adds value beyond annotations: specifies authorization requirement and return shape ({state}). IdempotentHint already indicates idempotency. 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 concise, front-loaded sentences. Every sentence adds essential information: purpose, access requirement, idempotency, return value. No 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 no output schema, description mentions return shape. Covers purpose, access, idempotency. Missing error handling or rate limits, but complexity is low and annotations cover safety.

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 parameters are standard (owner, repo, number). Description does not add additional meaning 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?

Description clearly states 'Reopen a previously closed issue' which is a specific verb+resource. This distinguishes it from sibling tools like close_issue and create_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?

Explicitly states prerequisite ('Requires authenticated caller with write access') and idempotent behavior. Does not explicitly mention alternatives or when not to use, but purpose is clear from 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 read-only and non-destructive. The description adds valuable context: it is for public repos only, returns Markdown for the latest commit, and returns null if no cached explanation exists. 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?

Single sentence that is clear, front-loaded, and contains no extraneous information. Every word 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?

The description adequately explains the return value (Markdown string or null) and constraints (public repo, most recent commit). No output schema is needed, and the behavioral details are sufficient for a simple read-only 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% with both 'owner' and 'repo' having descriptions. The tool description does not add additional meaning beyond stating they are required; 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 cached AI explanation Markdown for a public repo's most recent commit. It distinguishes itself by specifying 'cached' and the null return when no cache exists, but does not explicitly differentiate from sibling tool gluecron_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?

No guidance on when to use this tool versus alternatives like gluecron_explain_repo. The description mentions it's cached, but does not advise when to prefer it or when a fresh explanation might be needed.

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 description's job is to add non-obvious behavior. It adds the implementation detail (computeHealthScore) and the report contents, but lacks information on data freshness, error conditions, or authentication needs.

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

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

The description is concise with two sentences, front-loading the main action and output details. No filler, but could be slightly more structured with a bullet list for 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?

The description explains the return format comprehensively for a tool with no output schema: score range, letter grade, categories, and insights. Lacks mention of the response envelope or exact structures, but 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?

With 100% schema description coverage, the baseline is 3. The description adds no further parameter semantics beyond the schema's brief descriptions. It does imply the repo must be public, but this is not explicitly linked to 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 tool computes a health report for a public repo, listing specific output components (score, grade, breakdown, insights). This distinguishes it from sibling tools like gluecron_explain_repo, which have 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 mentions 'public repo' but provides no explicit guidance on when to use this tool vs alternatives. No when-to-use or when-not-to-use advice is given, leaving the agent to infer usage from 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 further discloses that the tool only works for public repositories, returns up to 50 issues, and orders by most-recent. This adds valuable 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?

Two short sentences that are direct and free of extraneous information. Every word serves a purpose.

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 simplicity of the tool (list operation, no output schema), the description covers the essential context: purpose, scope, limit, and ordering. It is adequate for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100% with each parameter described. The description does not add additional meaning to the parameters beyond what the schema already provides, so 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 action ('List'), the resource ('open issues'), and the scope ('public repository'). It distinguishes from sibling tools like search_issues and comment_issue by specifying it returns all open issues ordered by most-recent.

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?

While the description states when to use the tool (listing open issues for a public repository), it does not provide explicit guidance on when not to use it or alternatives like search_issues for complex queries. The context is clear but lacking exclusion 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying that binary files are rejected and that the tool returns text content. This goes beyond the 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?

A single sentence that front-loads key information (read, public, ref) and concisely states behavior (returns text, rejects binary). 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?

For a simple read-only tool, the description covers the core behavior: what it reads (file), from where (public repo, specific ref), and what it returns (text content, binary rejection). No output schema exists, so the description appropriately explains return values. Could note error handling for missing files, but not essential.

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 descriptions for all parameters. The tool description only reiterates the 'ref' parameter concept without adding new meaning to 'owner', 'repo', or 'path'. Baseline 3 is appropriate as the schema does the heavy lifting.

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 reads a single file from a public repository at a given ref, and distinguishes from sibling 'gluecron_read_file' which presumably handles private repos. The verb 'read' and resource 'file from a public repository' are 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 explicitly limits usage to public repositories, providing clear context. While it does not mention alternatives like 'gluecron_read_file', the naming convention implies differentiation. Lacks explicit when-not or exclusion details.

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 context about matching on name+description and a result cap of 20. While helpful, it does not provide additional behavioral traits beyond what annotations cover.

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

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

The description is extremely concise with two sentences, front-loading the purpose and key details. Every sentence contributes meaningful information without 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 the simplicity of the tool and good schema/annotation coverage, the description is complete. It specifies the search scope (public), match fields (name+description), and result limit, which suffices for effective agent 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%, so the description adds moderate value by relating 'keyword' to the query parameter and mentioning the default limit of 20. However, it does not explain the format or constraints 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 the tool searches public Gluecron repositories by keyword, matching against name and description, and returning up to 20 results. It specifies the scope (public) and resource (repositories), distinguishing it from other search tools among siblings.

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

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

The description implies usage for keyword-based repository search but does not explicitly mention when to use this tool versus alternatives like 'gluecron_search_repos' or 'gluecron_semantic_search'. No when-not-to-use guidance is 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?

Description adds behavioral details beyond annotations: the comment is tagged with isAiReview=true for gate-checker recognition and requires 'repo' scope. Annotations already indicate readOnlyHint=false, so the write action is consistent.

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 no redundancy. First sentence states the core action, second adds important details. Highly 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?

The description covers the primary purpose but lacks details on return value, error conditions, or consequences. For a tool with 4 parameters and no output schema, more context would improve agent understanding.

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% (body described). Description does not explain the owner, repo, or number parameters, nor does it provide additional context for body beyond the schema. Given low 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?

Description clearly states the action: 'Post a changes requested AI-review comment on a PR.' It specifies the comment type and distinguishes from siblings like gluecron_comment_pr by mentioning AI review and the isAiReview=true tag.

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?

Description mentions the required 'repo' scope as a prerequisite but does not provide guidance on when to use this tool versus alternatives like gluecron_comment_pr or other PR comment 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 already declare readOnlyHint=true and destructiveHint=false, so the description adds no new behavioral context. It is consistent but does not disclose additional traits like rate limits or return format details.

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, clear sentence that front-loads the core purpose. It is appropriately sized with no unnecessary 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?

With no output schema, the description should explain return structure; 'returns ranked rows' is vague. Missing details on pagination, error handling, and result fields make it incomplete for a 5-parameter 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 40% (only query and state have descriptions). The description adds that keyword searches title/body and that state filters results, partially compensating for undocumented parameters, but does not explain limit, owner, or repo beyond 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 the tool searches issues by keyword in a single repo, filtered by state, and returns ranked rows. It uses a specific verb and resource, distinguishing it from siblings like search_prs or list_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 implies usage for searching issues, but provides no explicit guidance on when to use this tool versus alternatives like gluecron_semantic_search or gluecron_repo_list_issues. No exclusions or when-not scenarios are 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 already indicate readOnlyHint=true, so the description adds that it searches by title/body keyword. It does not disclose further behavioral traits like pagination or rate limits, but does not contradict annotations.

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

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

A single sentence of 9 words that front-loads the verb and resource. Every word is necessary, with no wasted text.

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

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

Despite having 5 parameters and no output schema, the description is very brief. It omits details on parameter usage, return format, and pagination, making it incomplete for a complex search 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 low (20%). The tool description clarifies the 'query' parameter's purpose, but provides no information on 'repo', 'owner', or 'limit'. It partially compensates but leaves gaps.

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 'Search' and the resource 'pull requests', specifying search by title/body keyword on a repo. It effectively distinguishes from siblings like gluecron_search_issues and gluecron_list_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 implies usage for keyword-based PR search but lacks explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, though the purpose is clear enough for an agent to infer.

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 description adds 'Returns ranked rows' and notes it mirrors API. This provides some behavioral context beyond annotations, but not extensive.

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 unnecessary words, front-loaded with purpose. 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 is simple with 3 parameters and no output schema, the description adequately states purpose and output ('ranked rows'), but could be more complete about the return format or pagination.

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 all parameters described. The description adds context that query searches by name/description, but no additional parameter details beyond what 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 clearly states the verb 'search' and the resource 'public repositories by name/description', and references the specific API endpoint. It distinguishes from siblings like gluecron_semantic_search by specifying it's full-text search on repo metadata, but lacks explicit comparison.

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 like gluecron_repo_search or gluecron_semantic_search. The description only provides technical reference to an API endpoint, not usage 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 declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds that it uses Voyage embeddings or a hash fallback, providing some behavioral context but not covering auth, rate limits, or side effects.

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 no wasted words. The purpose is stated upfront, and the internal reference is brief. Could add more value without increasing length, but as is, it is 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?

No output schema and no description of return values or result format. The tool is a search function but lacks details on pagination, result structure, or error cases. Some completeness is lost given the many sibling tools.

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 0% description coverage, and the description does not explain any parameter (repo, limit, owner, query). The agent must infer meaning from names alone, which is insufficient for correct invocation.

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 queries a per-repo vector index for semantic search, specifying the use of Voyage embeddings or hash fallback. This distinguishes it from other search tools like gluecron_repo_search, which likely handles text or keyword search.

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_repo_search or other search tools. The description implies semantic search via vector index but does not explicitly state use cases or exclusions.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds behavioral details like writing to .gluecron/specs/ with status: ready, but does not disclose potential side effects like overwriting or what happens if the file already 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 concise (two sentences) and front-loaded with the core action. Every sentence adds value: the first states the action and context, the second adds implementation detail and 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?

For a tool with 4 required parameters and no output schema, the description provides adequate high-level context but lacks parameter explanations and post-action details. It covers the main action and scope but misses nuances that would help an agent use 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 low (25%), and the description does not compensate. The description only implicitly references 'body' as the spec content and 'repo' via scope, but does not explain the meaning of 'owner' or 'title', leaving agents without sufficient guidance for these 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?

The description clearly states the tool's purpose: dropping a spec file in a specific directory with a specific status for autopilot to pick up. It also differentiates from siblings by mentioning it wraps voice-to-pr.shipAsSpec and handles both voice and manual specs, which sets it apart from gluecron_voice_to_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 gives context for when to use the tool (dropping a spec for autopilot) and a prerequisite (requires 'repo' scope). However, it does not explicitly state when not to use it or provide alternatives, leaving the agent to infer from 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=false and destructiveHint=false. The description adds the scope requirement but does not disclose other behavioral traits like async execution, resource consumption, 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?

Two sentences with no wasted words. The key action is front-loaded, and the technical reference is 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?

Given 5 parameters, 3 required, and a nested object, the description lacks return value information, error handling, or prerequisites beyond scope. It does not fully contextualize the tool's operation.

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

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

Schema description coverage is 60%, but the description adds no parameter-specific details beyond what the schema provides. It does not explain allowed values, format, or usage for parameters like ref or inputs.

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 dispatches a workflow_dispatch run and references the specific API endpoint. It distinguishes from sibling tools like cancel_workflow_run or get_workflow_run by focusing on triggering an action.

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 says 'Requires repo scope', which is a prerequisite, but does not explain context 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 by stating the return format '{removed: boolean}' and confirming idempotency, which aligns with the idempotentHint. No contradictions 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 very concise with three sentences, each adding essential information. It is front-loaded with the primary 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?

While the description covers purpose, idempotency, scope, and return value, it lacks parameter descriptions and does not fully compensate for the low schema coverage. For a simple tool, it is adequate but has 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 0%, and the description provides no explanation for any of the 4 parameters (owner, repo, number, label). The description adds no semantic value for using 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 description uses a specific verb 'Detach a label from an issue', clearly identifying the resource and action. It is distinct from the sibling tool gluecron_label_issue, which adds labels.

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 idempotency and required scope ('repo'), providing some context. However, it does not explicitly state when to use this tool versus alternatives or provide 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 set readOnlyHint=false and destructiveHint=true, consistent with the update operation. The description adds behavioral details such as 'Owner-only' and 'Requires repo scope', which go beyond annotations. 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 a single concise sentence that efficiently conveys the tool's purpose, constraints, and return value. No unnecessary 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?

Given the tool has 5 parameters, no output schema, and moderate complexity, the description adequately covers purpose, constraints, and return value. It could mention the context (GitHub), but that is implied by the tool namespace.

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 descriptions in the schema already explain each parameter's meaning. The description does not add new information about parameters beyond what is in the schema, but the baseline 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 verb 'Update' and the resource 'repository description / visibility / default_branch'. It specifies exactly which attributes can be modified, and it distinguishes this tool from siblings like create_repo or delete_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 provides useful context: 'Owner-only' and 'Requires repo scope'. It does not explicitly state when not to use it or list alternatives, but the given constraints are sufficient for an agent to decide when to invoke this tool.

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