aictrl

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds important consequences: every decision records a receipt readable by downstream nodes, rejection cancels the run, and decisions are bound to revision/digest. It does not mention rate limits or auth beyond role, but adds enough 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 concise sentences; the first front-loads the action and binding constraints, the second covers outcomes and permissions. Every clause earns its place with no redundancy.

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

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

Given 7 parameters, nested objects, and no output schema, the description covers the core decision mechanics, outcomes, and permissions. It omits return value details (no output schema) and error codes beyond schema mention, but is largely complete for invocation.

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

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

Schema coverage is 100%, so the schema fully documents all parameters including nested objects and enums. The description mentions expected_revision and approval digest but does not add syntax or format details beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific verb ('Approve or reject') and resource ('manual quality gate currently pausing a workflow run'), and adds a distinguishing scope: bound to expected code revision and optional approval digest. It is clearly distinct from siblings like cancel_workflow_run or 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?

It describes the context of use (a paused manual gate) and authority ('Only the run owner or an organization admin may decide'), and implies the need for expected_revision. However, it does not explicitly name alternatives or when to use reject vs. cancel_workflow_run.

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?

Despite destructiveHint=true, the description adds substantial context: nodes in waiting/queued are cancelled immediately, running nodes drain to a 'cancelling' state, cancellation is not an immediate interrupt, and completed effects are not rolled back. It also states the authorization rule (owner or org admin). This is exactly the kind of nuance annotations cannot carry.

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

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

Three sentences, each front-loaded with a key behavioral fact. No repetition of schema fields, no boilerplate. 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?

Covers eligibility, immediate vs deferred cancellation semantics, non-interrupt caveat, no-rollback caveat, observability path, and authorization. With no output schema, this is complete for an agent to call correctly and interpret the result.

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

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

Schema coverage is 100%, so the schema already documents all three parameters including the reason field. The description adds no parameter-level detail beyond what is in the schema, so baseline 3 is appropriate.

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

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

States a specific verb (cancel) and resource (workflow run) and enumerates the statuses from which cancellation is valid. Distinguishes clearly from sibling get_workflow_run, which is only referenced for observation.

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 which statuses are acceptable and that any other status is rejected with conflict. Also names get_workflow_run as the way to observe completion, giving the alternative for a follow-up need.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond them: the return is 'current readiness and the single best next action', and that the intent is recorded for setup-action selection. It stops short of describing permissions or any cost/latency traits, so it is not a 5.

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

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

Two sentences, zero filler. The positive usage conditions are front-loaded, the return value is stated immediately after, and the exclusion clause is last where it belongs.

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?

Output schema exists, so return values need not be enumerated in the description. With annotations covering safety and the description covering both triggers and exclusions, an agent has enough to select and invoke it. Only the effect of the four intent enum values on behavior remains unexplained, which the schema partly covers.

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

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

There is a single optional parameter with 100% schema description coverage and an enum, so the schema already carries the semantics. The description adds nothing about how 'intent' influences the result beyond the schema's own note that it is recorded for setup action selection; baseline 3 applies.

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

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

The description states a concrete function — returning account readiness plus the single best next action — and the title reinforces it as an onboarding/readiness check. It is a specific verb+resource, though it never names or contrasts a specific sibling tool by name; the not-for clause handles differentiation indirectly.

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

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

It gives three explicit trigger conditions (starting with aictrl, asking what the account can do, unknown setup prerequisites on a repository action) and two explicit exclusions (general product questions, readiness already known this turn). This is exactly the when/when-not guidance an agent needs, with nothing left to inference.

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

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

Annotations already cover read-only, idempotent and non-destructive behavior, so the bar is lower; the description goes beyond them by disclosing the privacy-minimal payload, that a PR Explanation result is durable and only available "once stored", and that Code Review returns status only. It does not state whether status partially completes, but the added behavioral context is real and non-obvious.

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

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

Three tight sentences with no filler; the core operation is front-loaded and the per-execution-type caveats follow immediately. Every clause carries information an agent needs.

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

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

An output schema exists, so return values need not be explained, and the description still supplies the key variation across execution types and the asynchrony implied by "once stored". For a 2-parameter read tool with full annotation and schema coverage, nothing material is missing.

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

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

Schema description coverage is 100% and both parameters (execution_id from start_task, organization_id from list_organizations/get_started) are documented there. The description adds no format, syntax or constraint detail beyond the schema, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ("Get the current status ... of a task execution") and scopes it to executions "started through public MCP", then disambiguates the two execution kinds. It never names a sibling (e.g. get_workflow_run or list_tasks), so it stops short of explicit sibling differentiation.

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

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

The description tells the agent the prerequisite (an execution started via start_task) and routes it away from this tool for Code Review findings, which are delivered as PR review comments. It gives clear usage context but states no exclusions or alternative tool names for the status-only case.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and closed-world scope, so safety is covered. The description adds genuine behavioral context beyond that: secret trigger configuration is stripped from the returned definition, which tells the agent the output is redacted and not the full stored config.

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

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

A single front-loaded sentence with zero waste; the redaction caveat is attached directly to the resource it qualifies.

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

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

For a simple two-param read tool with full annotation coverage, complete schema descriptions and no output schema, the description supplies what is needed, including the redaction note. It just lacks explicit routing guidance relative to the run/step siblings.

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

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

Schema coverage is 100% and both required parameters are documented in the schema with provenance (IDs returned by list_workflows / list_organizations). The description adds no parameter-level meaning, so the baseline of 3 is correct.

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

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

States a specific verb (Get) and resource (one published workflow definition), and the scope word 'one' plus 'published' distinguishes it from list_workflows and get_workflow_run in the sibling set. An agent can identify the tool without opening the schema.

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

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

Usage is only implied: taking a single workflow_id suggests fetching a known definition, and the schema notes the ID comes from list_workflows, which hints at the workflow. But there is no explicit when-to-use versus get_workflow_run or list_workflows, and no stated preconditions.

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, openWorldHint=false, destructiveHint=false, yet the description adds critical non-obvious behavior: a run can be paused on a manual approval gate and repeated polling will not advance it. It also discloses which fields must be carried into the follow-up approval call (expectedRevision, approvalDigest, afterWave, gateIndex), which no structured field provides.

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 retrieval purpose before the exceptional approval branch. Although the second sentence is long, every clause is operational (paused gate, show to user, require explicit decision, which fields to pass) and none is redundant with the annotations or schema.

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

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

With no output schema, the description carries the return-value burden and does so: status, progress, node results, and the requiredAction object with its type. Combined with the approval-gate workflow instructions, an agent has everything needed to read a run and act correctly on a paused gate.

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

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

Schema description coverage is 100% for the two required parameters (run_id and organization_id), so baseline is 3 and the schema already carries the syntax. The description adds meaning by stressing that run_id must be a known run (from start_workflow or list_workflow_runs) and by naming the requiredAction fields an agent must round-trip into the approval call.

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

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

Starts with a specific verb+resource ('Get status, progress, and node results for one known workflow run ID'), which pinpoints exactly what is returned. It also distinguishes itself from the sibling list_workflow_runs by scoping to a single already-known run rather than discovery, so an agent can separate the two without opening either schema.

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

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

Explicitly names the alternative for discovery ('use list_workflow_runs to discover runs') and gives a concrete when-not condition: when requiredAction.type is 'approval', polling alone will not resolve the paused gate. It further routes the agent to approve_workflow_step and states the precondition (explicit user approve/reject decision), which is unusually complete routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds meaningful non-annotation context: results are scoped to the authenticated principal's permissions, which explains why the output can vary between callers. It does not mention ordering, size, or pagination.

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

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

A single front-loaded sentence with no redundant restatement of the name or title. Every clause earns its place by adding auth scope and a usage motive.

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 parameterless, read-only listing tool with annotations covering safety and no output schema, the description is nearly sufficient. The implied return (organization identifiers/names) is reasonably clear from 'for use with organization-scoped tools', though the exact item shape is left to inference.

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

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

The tool takes zero parameters, so the baseline is 4. There is no argument surface for the description to elaborate on, and the sentence correctly avoids inventing filter options.

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

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

The description gives a specific verb and resource ('List organizations') and adds scope ('available to the authenticated principal'). It is clearly distinguishable from the workflow/task siblings, though it does not explicitly name or contrast with any of them.

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

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

'for use with organization-scoped tools' tells the agent the context in which this call is needed — resolving organization identifiers before calling org-scoped tools. It stops short of explicit exclusions or naming an alternative 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?

Goes well beyond the readOnly annotations: documents the exact return fields (id, githubCommentId join semantics including null cases, claim, lifecycle, latest verdict/verification), the append-only judgment chains, and three non-obvious filtering rules (own-run exclusion, obsolete exclusion, history toggling). This is rich operational behavior an agent needs.

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

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

Front-loaded with purpose then return semantics and filtering rules; every sentence carries information. It is dense and somewhat long, but no sentence is wasted.

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

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

With no output schema, the description fully compensates by enumerating returned fields and their join semantics, plus the behavioral filters. An agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 60% and the schema already carries detailed descriptions for include_history and include_obsolete; the description largely restates those rather than adding new param-level meaning. organization_id/repository/pr params get no added explanation in the description, so baseline 3 applies.

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

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

Specific verb+resource ('Read all recorded findings for a PR') with the scope ('any lifecycle status') and the downstream purpose ('so verdicts can be recorded by exact id'). It implicitly contrasts with the write-side sibling record_finding_verdict by emphasizing this read returns ids for judging.

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

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

Gives clear context: use it to obtain exact ids before recording verdicts, and states two exclusion conditions (own-run judgments, obsolescence-swept findings). It does not explicitly name when to prefer this over other listing tools, but the routing intent is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low; the description adds genuinely useful behavioral context beyond them — result scope (first-party only), the meaning of an empty result, and the guarantee that listing has no side effects. It doesn't state pagination or ordering, but the safety profile is covered by annotations.

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

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

Three tight sentences, front-loaded with what it lists and immediately qualifying scope and exclusions. Each sentence carries distinct information: scope, exclusion, empty-result semantics, and side-effect safety.

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?

An output schema exists, so return values need no prose. The description covers what an agent needs — scope, exclusions, empty-result interpretation, and no-side-effect guarantee — leaving nothing material unstated for a two-parameter read tool.

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

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

Schema description coverage is 100%, so both parameters are already documented with format and constraints. The description reinforces that repository_full_name must be live-authorized but adds no syntax or value semantics beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (List) and resource (first-party aictrl tasks) with an explicit scope constraint ('can run for one live-authorized repository'). It also carves itself out from siblings like start_task and from org-authored templates, so an agent can distinguish it without opening a schema.

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

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

Gives a clear usage context (one live-authorized repository) and an explicit exclusion (never templates authored inside the organization), plus 'Listing never starts work,' which implies the run-it alternative. It stops short of naming start_task or get_task_execution outright, so the routing is inferred rather than stated.

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

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

Annotations already cover read-only/non-destructive/non-open-world, and the description adds real context beyond them: the returned envelope {data, nextCursor, hasMore}, the cursor-continuation contract, the null behavior for unavailable issues, and the projection shared with get_workflow_run. It stops short of describing ordering or rate limits, so it is strong but not exhaustive.

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

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

Four tight sentences, front-loaded with scope and filters, then pagination contract, then the read-only disclaimer. Dense but each sentence carries distinct information; no filler or restatement of the name.

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

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

No output schema exists, yet the description supplies the return envelope and pagination protocol, which is what an agent most needs for a list tool with 11 parameters. Combined with 100% schema coverage, an agent has enough to call it correctly; only minor gaps like default ordering remain unstated.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters including needs_attention, cursor, and the status enum. The description reinforces the filter set and the needs_attention semantics but adds little syntax or format detail beyond the schema, which is the expected baseline when 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?

States a specific verb (page through) and resource (org-scoped workflow runs) plus the filter dimensions, and explicitly references the sibling get_workflow_run for the projection. An agent can distinguish this list tool from get_workflow_run, start_workflow, and cancel_workflow_run without opening any schema.

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

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

Gives concrete usage conditions: filter by issue/epic/status/starter/date, use needs_attention for failed or approval runs you started or own native issues, and the exact pagination loop (pass nextCursor as cursor with the same organization_id and filters). It also rules out the mutation path ('never starts or changes a run'). No explicit naming of a competing list alternative, but the routing is clear.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, not open-world), and the description adds genuinely new behavior: ordering by most recent update with deterministic tie-breaks (organization ID, then workflow ID), a hard cap at limit, and the fact that there is no cursor-based pagination. Return shape ({workflows}, each with owning organization) is also disclosed.

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

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

Three sentences, all load-bearing: scope first, then return/ordering/pagination constraints, then the next-tool handoff. No filler or repetition of the title.

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

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

For a zero-required-parameter read tool with no output schema, the description supplies everything missing elsewhere: return shape, ordering, cap, absence of pagination, and the follow-up tool. Nothing an agent needs to call this correctly is omitted.

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

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

Schema coverage is 100%, so baseline is 3; the description goes further by explaining that organization_id scopes results to a single org and that limit both caps the result set and is the only way to page beyond it. It stops short of restating format constraints, but adds real semantic value over the schema.

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

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

States a specific verb and resource ('List published workflows') plus scope ('across organizations available to the authenticated principal, or in one organization when organization_id is given'). This cleanly separates it from siblings like list_workflow_runs and get_workflow, which deal with runs and single-workflow detail.

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

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

Explicitly routes the agent forward: 'Use get_workflow to inspect a selected workflow's parameters, side effects and gates before start_workflow.' It also gives the escalation path when results are truncated ('filter by organization_id or raise limit to see more'), which is exactly the when-to-use guidance an agent needs.

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/openWorldHint/destructiveHint=false, but the description adds real context beyond them: most actions read stored indexed context while exactly two (issues/read, code/read) reach GitHub live, and issues/read requires authentication with repoFullName + issueNumber. It doesn't cover rate limits or pagination/response shape, but the live-vs-stored distinction is genuinely informative.

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

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

Front-loaded with the six domains, then live-vs-stored caveats, then exclusions and alternatives - a sensible order. It is dense but not padded; the main cost is that the long action enumeration partially duplicates the schema's action description, which is redundant but still aids action selection.

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 broad multi-domain read tool with an output schema and annotations already present, the description supplies what structured fields cannot: the live-vs-stored split, the ordering requirement before update_backlog, and explicit handoffs to the workflow/task-execution siblings. Nothing an agent needs to select the right domain/action is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further: it disambiguates which domain+action combinations exist, clarifies that issues/context, list and overlap use stored issue context while issues/read is live, and states that query accepts an ID, path, symbol, or skill name depending on domain. That is semantic guidance the schema's flat action enum does not convey.

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

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

The description states a concrete verb+resource ('Read project context') and immediately enumerates the six exact domains (code, system, issues, backlog, skills, stack), so an agent knows precisely the scope. It also names what it is not (workflow runs, task executions), separating it from 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?

It gives explicit routing rules: 'use backlog list/get actions to find existing epic and task IDs before calling update_backlog', and 'Not for workflow runs or task executions: use list_workflow_runs... get_workflow_run... get_task_execution...'. This is when-to-use, when-not-to-use, and named alternatives in one place.

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 a destructive write, and the description goes well beyond them: idempotent overwrite semantics, judgment-history append behavior, the SHA validation rule and its rejection mode, the auto-dismiss side effect on FALSE/MINOR findings vs. confirmed suggestions on MAJOR/BLOCKER, and that dismissals are not reopened. This is unusually rich behavioral disclosure.

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

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

Front-loaded with the core action and dense with useful detail, but it runs long (~300+ words) as a single block, with several clauses packed per sentence. Every sentence carries information, but the volume slightly hurts scannability.

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

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

With no output schema, the description compensates by naming the returned fields (`autoDismissed`, `autoDismissReason`) and covering required inputs, validation failures, and side effects. For a 10-parameter nested-object tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is already 80%, so the baseline is 3, but the description adds real meaning: it clarifies that finding_id is the only supported selector, that judged_at_sha must be the SHA actually read (not the branch tip), and warns that `reason` is not a substitute for `reasoning`. Most remaining detail is duplicated from the schema, keeping it short of a 5.

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

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

States a specific verb and resource ('Apply a post-hoc triage verdict to a finding') and scopes the operation precisely. It names its companion tools (record_finding for creation, list_pr_findings for lookup) so an agent can distinguish it from siblings without opening any schema.

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

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

Explicitly says when it applies (the /reply-to-code-review flow), the prerequisite that only findings recorded into the data layer can receive a verdict, and the recovery path on not_found ('call list_pr_findings to refresh stale IDs and do not treat the write as successful'). It also states when a verdict does not reopen a dismissal.

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

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

Goes beyond the annotations by disclosing the external side effects: PR Explanation 'posts nothing to GitHub' while Code Review 'posts its findings as review comments on that pull request.' It also explains idempotency semantics concretely (same key = same execution), which adds value on top of idempotentHint=true. It does not mention auth/permission requirements for the live-authorized repo, keeping it short of a 5.

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

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

Four tight sentences, front-loaded with what the tool does, then the two task behaviors, then the prerequisite, then the idempotency contract. No filler or restatement of the title.

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

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

An output schema exists, so return values need no explanation; the description instead covers the things it must: which task templates are valid, the pre-condition for calling, the differing GitHub side effects, and retry semantics. Nothing material for correct invocation is missing.

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

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

Schema description coverage is 80%, so the schema already documents task_id, idempotency_key, organization_id, pull_request fields and the audience enum. The description reinforces only the 'exact pull-request revision' constraint already captured by expected_head_sha; it adds no format or edge-case guidance for the remaining parameters. Baseline 3 applies.

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

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

States a specific verb (Start) and resource (one first-party task from list_tasks) and pins the scope to an exact pull-request revision. It also enumerates the two task kinds it can launch and what each does, so an agent can distinguish it from start_workflow without opening the schema.

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

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

Gives an explicit gating condition: 'Call only after the user explicitly asks to run that task in the current turn,' and points at list_tasks as the source of task_id. It does not, however, route the agent away from the sibling start_workflow or explain when a workflow run (rather than a task) is the right choice.

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

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

Annotations already declare destructive=true, idempotent=true, and openWorld=true, but the description adds crucial context: the run can perform only the published workflow's declared side effects within configured gates and policy, and retrying with the same idempotency key returns the same run. It also surfaces the required user-confirmation gate before any destructive action.

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

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

Four sentences, front-loaded with the core action, then the confirmation gate, then the idempotency behavior. Every sentence earns its place for what is a destructive, open-world operation.

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

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

For a destructive, open-world tool with nested inputs and no output schema, the description covers the essentials: validation source, side-effect limits, the required user-confirmation gate, and idempotent retry semantics. Nothing an agent needs to call this safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by explaining that inputs are validated against parameters returned by get_workflow and that native issue workflows require a confirmed repository_id. It stops short of adding syntax or format details beyond the schema.

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

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

The description states a specific verb and resource ('Start a published workflow') and explicitly ties input validation to the sibling tool get_workflow. An agent can distinguish this from start_task or get_workflow without opening the schema.

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

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

It gives an explicit precondition: show the user the workflow's inputs, declared side effects, and approval gates from get_workflow, and call only after explicit confirmation in the current conversation. This is a clear when-to-use rule, not just implied 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 (destructiveHint=true, readOnlyHint=false) only flag that this mutates state; the description goes much further by explaining that omitted fields are preserved, that supplied depends_on/tags/stack_layer_ids arrays REPLACE the stored list and [] clears it, that unknown stack_layer_ids are silently dropped, and which updates are rejected.

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

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

Front-loaded with purpose, then usage, then edge-case semantics in a compact paragraph with no filler sentences. It is dense and the final sentences pack several distinct rules together, but every sentence carries actionable information.

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

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

Covers the hard parts: ID discovery, partial-update semantics, array replacement, and rejection rules for a tool with nested objects and no output schema. The remaining gap is return behavior (e.g., how to obtain the new task_id), which is not addressed and matters for chained create calls.

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

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

Schema coverage is 100% and the params oneOf already lists every field, so the baseline is 3. The description adds real meaning on top: merge-vs-replace semantics for the three array parameters, the empty-array clearing behavior, and the silent dropping of unrecognized stack_layer_ids, none of which the schema states.

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

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

States a specific verb pair and resource: 'Create or update tasks within an Epic,' and adds scope ('materialise a plan into stored tasks with stack-layer assignments and dependencies'). It differentiates itself from read siblings by directing ID lookups to query_context, though it never names list_tasks as the read alternative.

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

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

Explicitly routes the agent: this is the Planner Breakdown write path, and existing epic/task IDs must come from query_context domain=backlog reads (action=list_epics, then action=list with params.type="tasks"). It also enumerates the rejection conditions (no-op update, active/claimed task, invalid status transition), which is exactly the when-and-when-not guidance an agent needs.

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