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

Since no annotations are provided, the description must carry the full burden. It discloses key behaviors: `block` and `unblock` set an orthogonal flag and leave the role alone, `reconcile` clears a role the provider contradicts, and `transition` resolves an abstract role to the native state. This is well-detailed for the complexity.

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 informative but somewhat dense and run-on, with parenthetical comments that could be structured more clearly. It front-loads the primary action but could benefit from breaking into bullet points for readability.

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

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

Given the complexity of four distinct operations with nuanced behaviors (orthogonal flags, role resolution), the description covers the essential semantics well. There is no output schema, but the description implies each op has a specific return (e.g., `block` sets a flag), which is adequate for agent 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 description coverage is only 25%, so the description must add meaning. It explains the `op` parameter's four valid values in detail and mentions `reason` is required for `block`. However, it does not cover parameters like `id` or `role` beyond what the schema provides (e.g., format constraints for `id`), and the empty `role` and `reason` descriptions in the schema are not supplemented.

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

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

The description clearly states that the tool moves a work item through the workflow or flags it, listing four specific ops (transition, reconcile, block, unblock) with brief explanations. It distinguishes itself from sibling tools like baron_issue_read and baron_issue_write by focusing on workflow transitions and flagging, not reading or writing issue data.

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

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

The description provides basic context for when to use each operation (e.g., `transition` for moving an item, `block` for flagging) but does not explicitly state when to use this tool versus alternatives or when not to use it. It lacks guidance on prerequisites or common pitfalls.

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?

Describes the output for get (one normalized issue), query (filtered list), and iterations (sprints with current flag). Mentions allowed special values like '@me' and '@current'. However, the 'classify' operation is absent, and no side effects, error conditions, or rate limits are 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?

The description is a single sentence with a clear front-loaded purpose ('Read work items') and structured enumeration of operations. It is concise but could be better organized (e.g., bullet list) and is missing the 'classify' 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?

Given 7 parameters, no output schema, and no annotations, the description covers the main operations well but omits the 'classify' operation entirely. It also lacks details on pagination, error handling, or authentication needed for a fully complete profile.

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

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

With only 14% schema description coverage, the description adds significant meaning: it associates parameters with operations (e.g., id for get, role/typeRole/assignee/iteration/limit for query) and explains special values. However, the 'classify' operation's parameters are not described.

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 the tool reads work items and details three operations (get, query, iterations) with their specific actions. However, the 'classify' operation from the schema is not mentioned, leaving its purpose unclear.

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

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

The description implies the tool is for reading via the phrase 'Read work items' and the sibling tools indicate write/move variants. No explicit guidance on when to use or when not to use this tool, nor alternatives are named.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently explains that 'update' is a patch operation (omitted fields left alone) and that roles and type roles are abstract (mapped by policy). However, it does not mention potential side effects like permission requirements, rate limits, or what happens on failure (e.g., partial success across multiple ops).

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

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

The description is compact (about 50 words) and front-loaded with the core purpose. Each sentence earns its place, though the last sentence about roles could be slightly more concise. The structure clearly groups operations with their parameters, making it scannable.

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 operations, 13 parameters, no output schema or annotations), the description is fairly complete for typical usage scenarios. It covers all operations and key parameter dependencies. However, it could mention return behavior (e.g., does create return the new ID?) and error handling to fully address the gap left by the missing 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?

The schema has 13 parameters but only 8% description coverage (one enum documented per schema). The description compensates significantly by explaining which parameters apply to which operation (e.g., parentId for create, assignee for assign, iteration for set_iteration) and adding semantics like '@me' and '@current' allowed values. This adds substantial meaning beyond the bare 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 is for changing a work item's content and enumerates six specific operations (create, update, comment, assign, link, set_iteration) with their required parameters. This distinguishes it from siblings like baron_issue_read (which likely reads rather than writes) and baron_issue_move (which probably relocates issues rather than altering content).

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 per-operation parameter needs (e.g., 'create' needs title, typeRole; 'update' needs id, title and/or body), which guides when to use each variant. However, it lacks explicit exclusion guidance or direct comparisons to sibling tools like baron_issue_read or baron_issue_move for scenarios where reading or moving would be more appropriate.

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

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

With no annotations provided, the description carries full burden. It only says 'durable' but omits key behavioral traits: side effects, permissions, success/error behavior, idempotency, or storage limits. This is insufficient for a mutation tool with 4 parameters and no output schema.

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

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

Two sentences front-load the core purpose and then detail operations efficiently. No extraneous words. The colon-based structure is somewhat dense but still clear. Very minor improvement possible by separating operation specs more clearly.

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

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

Given the tool's complexity (4 params, enum, no output schema, no annotations), the description covers purpose and operation variants but lacks return value hints, error conditions, prerequisites, and parameter constraints (e.g., tag format, body length). The title-required contradiction further reduces completeness.

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 adds meaning to the 'op' enum by explaining field requirements per operation (e.g., 'learning' requires title+body, 'followup' requires title with optional body/tags). However, it contradicts the schema by implying 'title' is always required while the schema marks only 'op' as required. Other parameters (body, tags) get no additional semantics 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 this tool records data durably in Baron's own store, distinguishing it from siblings like baron_memory_query (querying) and baron_issue_write (issue tracking). It also details two specific operations ('learning' and 'followup') with field requirements, making the purpose highly specific.

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 context by specifying 'not a provider's store' and briefly defining each operation, but does not explicitly guide when to choose this tool over siblings (e.g., baron_memory_query for retrieval) or when not to use it. No exclusions or alternatives are named.

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

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

With no annotations, the description carries full burden. It confirms read-only intent via 'Read' and lists optional parameters, but omits critical behavioral traits: return format, pagination behavior, default values for omitted params, authentication requirements, and what 'learning' vs 'followup' specifically query. Minimal disclosure beyond basic operation.

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 front-loaded purpose and compact operation details using backticks and semicolons. Every word serves a purpose with no filler. Efficient and scannable.

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 5 parameters and no output schema/annotations, the description does not explain the semantics of 'learning' and 'followup' operations, expected return values, or any constraints. A query tool lacking return format or operation semantics leaves the agent with significant gaps. Incomplete for the complexity level.

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 20% (op described). The description adds meaning by grouping parameters per operation: learning (tag, text, limit) and followup (status, tag, limit). This clarifies which parameters are relevant for each op, compensating for the schema's lack of per-parameter 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 the tool reads Baron's own store, uses specific verbs 'learning' and 'followup', and distinguishes it from sibling tools like baron_memory_append (write) and other issue/SCM tools. 'Read Baron's own store' plus operation listing makes the purpose specific and unambiguous.

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

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

The description implies the tool is for querying memory store but provides no explicit guidance on when to use this versus sibling tools (e.g., baron_issue_read for issues). No alternatives or exclusions are mentioned, leaving the agent to infer context from tool names alone.

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

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

No annotations exist, so the description must disclose all behavioral traits. It states that Baron attaches base URL + auth and caps response size, and that the call is non-portable. However, it omits details on error handling, potential destructive side-effects (since METHOD can be DELETE/PATCH), or response format. More disclosure would be needed for complete transparency.

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

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

The description is compact (3 sentences) and front-loaded with the key concept 'ESCAPE HATCH'. Every sentence serves a purpose: stating what it is, when to use, and what the user provides vs what Baron handles. 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?

The tool has 5 parameters (3 required), no output schema, and nested objects. The description explains the high-level flow and constraints but does not detail what the response looks like (beyond 'size-capped'), error responses, or format of body/query parameters. For an escape hatch, some missing details may be acceptable but the response shape is left ambiguous.

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

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

Schema coverage is 80% (4 of 5 parameters have descriptions). The description adds meaning by explaining that the user supplies the provider-native method+path+query/body and that Baron only adds the base URL and auth. It reinforces the role of each parameter in the tool's execution, going beyond the schema's brief 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 explicitly states 'raw, authenticated, NON-PORTABLE provider REST call' and positions itself as an 'ESCAPE HATCH — last resort' contrasting with the normalized sibling tools (issue/scm/ci/notify). This clearly distinguishes the tool's purpose from the sibling list.

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 provides explicit when-to-use ('Last resort for when no normalized tool covers the need') and when-not-to-use ('Prefer the normalized tools — this is provider-specific and will not port'). It also mentions constraints: 'Only providers bound in the active policy are reachable.' This gives the agent clear guidance on alternatives and limitations.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool lists built-ins and project recipes with inputs, implying a read-only listing. However, it does not explicitly state that the operation is safe, non-destructive, or if any authentication is required. The behavioral detail is adequate but not rich.

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

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

Two sentences, zero wasted words. The first sentence states the primary function, the second provides usage guidance. It is front-loaded and efficient.

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

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

For a simple list tool with no parameters and no output schema, the description is complete. It specifies the scope (built-ins + project recipes), the output content (declared inputs), and the intended use case (discovery before running). No additional information is 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?

There are zero parameters and schema coverage is 100% (vacuous). The baseline for 0 parameters is 4. The description adds meaning beyond the empty schema by explaining what the tool lists and its purpose, which is sufficient.

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 lists runnable recipes (built-ins and project recipes) with their declared inputs. It distinguishes itself from the sibling `baron_recipe_run` by explicitly mentioning what the tool discovers for that run tool.

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

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

The description explicitly tells when to use the tool: 'Call this to discover what `baron_recipe_run` accepts before running a workflow.' This provides clear context and links to the sibling tool, guiding the agent to use it as a prerequisite step.

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

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

With no annotations, the description carries full burden. It discloses deterministic execution, rule-enforced step order, automatic error on missing inputs, dual return format (JSON context + optional text block), and explains the text block's purpose ('reports what it could not verify'). 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?

Four sentences covering action, behavior, input requirements, return format, and usage preference. It is concise and front-loaded, though the dense paragraph could benefit from slight structural separation (e.g., breaking out return format). No redundant content.

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

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

Given the tool's complexity (recipe execution, deterministic workflow, two-part return) and no output schema, the description is nearly complete. It covers what it does, how to use it, what to expect, and what the text block means. It does not mention error handling for missing recipes or non-existent inputs, but that is implied by the deterministic nature.

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% (both parameters have descriptions). The description adds value beyond the schema by explaining that required inputs come from baron_recipe_list and that missing them causes errors rather than prompting. This context helps the agent prepare inputs correctly.

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 'Run a named recipe end-to-end as ONE deterministic, rule-enforced workflow' – a clear verb+resource pairing. It explicitly distinguishes from sibling tools by advising 'Prefer this over composing the individual issue/scm/ci tools yourself for a packaged workflow.'

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 when-to-use guidance ('Prefer this over composing...'), instructs to supply inputs from baron_recipe_list, warns that missing required inputs error rather than prompt, and tells the agent to read the second text block for verification messages. This fully covers selection and invocation 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?

Without annotations, the description carries the full burden. It explains the return values for each operation (normalized state, review decision, mergeability, checks rollup; most recent PR or null) and mentions null return for pr_for_branch. However, it does not disclose error handling, rate limits, or authentication requirements.

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 paragraph but is well-structured with inline code formatting for operations. It front-loads the primary purpose and efficiently packs details. Could be improved with bullet points, but remains clear and 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?

The tool has no output schema, so the description must explain return values. It does so for both operations and adds usage hints (e.g., idempotency probe). Missing details on error conditions or empty results (e.g., what happens if pullRequestId is not found), but overall sufficient for a simple 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 only 25% (only 'op' has a schema description). The tool description compensates by explaining the meaning and usage of all parameters: it describes the two op values and their associated parameters (pullRequestId, sourceBranch, state) with clear semantics, adding significant 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 begins with 'Read source-control state,' clearly stating the verb and resource. It then enumerates two distinct operations with detailed outputs, differentiating it from sibling tools like 'baron_scm_write'.

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 patterns (e.g., 'open is the idempotency probe before creating one' suggests use before baron_scm_write) but does not explicitly state when to use this tool vs alternatives or when not to use it. No direct reference to 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?

The description explains important behavioral aspects: branch_create is idempotent, pr_create's linkedIssueRelation semantics, and that a provider-declined merge surfaces as MERGE_FAILED rather than a false success. This is valuable since no annotations are provided, and it goes beyond just listing parameters.

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 given the complexity (5 operations, 15 parameters) and organizes information per operation with parentheses. It front-loads the overall purpose. A minor improvement would be breaking into a list for readability, but it remains compact.

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 tool with 15 parameters and no output schema, the description provides sufficient context for each operation's semantics and parameters. It covers idempotency, merge failure behavior, and link relations. The only gap is the response format (e.g., what is returned on success), but with no output schema, the description could include that.

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 very low (7%), so the description must compensate. It does so by grouping parameters per operation and explaining semantics for key parameters (fromBranch, linkedIssueKey, linkedIssueRelation, strategy, deleteSourceBranch). However, some parameters like body, draft, assignees, autoComplete are only mentioned in passing without full detail.

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

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

The description clearly identifies the tool's purpose as changing source-control state and lists the five distinct operations with their required and optional parameters. It distinguishes itself from siblings like baron_scm_read (which likely reads state) and other baron tools focused on issues, recipes, or memory.

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

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

The description provides clear guidance on when to use each operation and the effect of parameters (e.g., 'closes' finishes the item on merge, 'relates' only references it for linkedIssueRelation; 'idempotent' for branch_create). However, it does not explicitly contrast with baron_scm_read or other siblings for deciding when to write vs. read.

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