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

With no annotations, the description carries the full behavioral burden. It implies a state mutation and hints at optimistic concurrency ('exact version'), but never says the call fails on a version mismatch, whether transitions are reversible, what permissions are required, or which target states are terminal.

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

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

A single front-loaded sentence with no filler; the verb and scope come first. It is efficient, though the brevity comes at the cost of the semantics noted elsewhere.

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

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

For a three-parameter mutation tool with no annotations, no output schema, and 0% parameter documentation, the description is too thin. An agent cannot tell from this text whether the call is safe to retry, what happens on version conflict, or how the terminal states behave.

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

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

Schema description coverage is 0%, so the description must compensate yet only partially does: 'exact version' loosely maps to expectedVersion, and the stage words loosely map to some target values, but repoTaskId is unexplained and the enum members BLOCKED and CANCELLED are never mentioned.

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 ('Advance') and resource ('repo task') and names the lifecycle stages it moves through (planning, pull request, merge), which maps to the target enum. It does not, however, distinguish itself from the closely named sibling workflow_ticket_advance, so an agent must infer the repo-task vs ticket distinction.

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 versus workflow_ticket_advance, workflow_complete_task, or workflow_task_skip. The phrase 'with an exact version' hints at a precondition but never states when the call is appropriate or what to do if the version has moved on.

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating operation, so the description adds little there. It says nothing about what the analysis produces, whether the manifest is validated, or how errors in the manifest are surfaced.

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?

One short, front-loaded sentence with no filler or redundancy. It is efficient, though its brevity is partly a symptom of under-specification rather than disciplined editing.

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 a complex nested input, no output schema, and no annotations beyond read-only, the description leaves the agent without knowledge of the return shape or the analysis semantics. It is too thin for the complexity involved.

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% for a single, deeply nested manifest object with 8 required sub-fields and several size constraints. The description only echoes 'journey manifest' and adds no meaning about the manifest's structure or the significance of httpEdges, so it fails to compensate for the coverage gap.

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

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

The description names a specific verb ('Analyze'), a specific resource ('cross-service HTTP dependencies'), and the input source ('a journey manifest'). It is clear and unambiguous, but it does not distinguish itself from near-neighbors such as workflow_analyze_journey or workflow_get_journey_graph.

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

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

There is no guidance on when to use this tool versus the many sibling analysis/graph tools, no preconditions, and no statement of what the agent should do with the result. An agent must infer usage from the name 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?

Annotations declare readOnlyHint=true, so safety profile is covered. The description adds 'deterministic' (results are reproducible) and 'evidence-gap analysis' (this is analysis output, not mutation), which is useful added context. But nothing about what it consumes from the manifest, whether it requires prior onboarding, or what it returns. With annotations carrying the safety burden, a 3 is appropriate.

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

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

One compact sentence with no filler, front-loaded with the verb. It's efficient, but borderline under-specified rather than genuinely concise — it says a lot of words ('deterministic cross-repository Journey contract and evidence-gap analysis') without resolving what the agent actually needs.

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

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

For a tool that takes a complex nested manifest and produces some analysis (no output schema), the description is far too thin. It doesn't cover the manifest requirement, processing semantics, what 'evidence-gap' means, or expected output. Given the complexity and density of siblings, this is inadequate.

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%, but there's only one top-level parameter ('manifest') and the schema documents its entire nested structure with required fields, types, and constraints. The description says nothing about the manifest or how it relates to cross-repository analysis. Baseline for a single richly-typed parameter is around 3; the description neither compensates for nor worsens the coverage gap.

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

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

The description states a specific action verb and resource: 'Run deterministic cross-repository Journey contract and evidence-gap analysis.' It says what it does at a high level, but it's jargon-heavy and doesn't tell the agent exactly what gets produced or how it differs from siblings like workflow_get_journey_graph or workflow_analyze_http_dependencies. It's distinct enough from the names alone, but the purpose remains somewhat opaque.

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

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

No when-to-use guidance, no prerequisites or conditions, no mention of alternatives. With a dozen analysis/graph siblings (workflow_get_journey_graph, workflow_analyze_http_dependencies, workflow_scan_repository_context), the description does zero routing. Implied usage is running analysis, but nothing tells the agent when to pick this over the others.

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 of behavioral disclosure. 'Assign a task' implies a mutation, but the description does not state permission requirements, whether assignment is reversible, how it interacts with bound identities, or what happens on failure. No annotations means the description must compensate more than it does.

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 efficient sentence that front-loads the verb and resource. No wasted words, though the compactness trades away the detail the tool needs.

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

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

For a 3-parameter mutation tool with no annotations, no output schema, and 0% schema description coverage, the description is too thin. It doesn't explain actorRole (the least self-evident parameter), doesn't cover permissions or side effects, and doesn't provide any output or error context. Significant gaps remain.

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 adds no meaning beyond the schema. taskId and assigneeId are self-evident from their names, but actorRole is abstract and completely unexplained — the description repeats 'declared actor role' without defining what an actor role is or its valid values. Three required parameters with no documentation in either place.

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 (assign a task) with additional scope (bound identity, declared actor role). However, it does not distinguish itself from siblings like workflow_claim_task, workflow_complete_task, or workflow_report_blocker, leaving the agent to infer when assignment differs from claiming. Vague enough to be considered minimum viable.

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 sibling list contains workflow_claim_task, which is a closely related concept (taking a task), but the description gives no condition that selects assignment over claiming. Context is implied at best.

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 the full burden. It does disclose genuine behavior: the claim is a lease and that lease is bounded, and it signals ordering relative to reasoning. It omits what happens on lease expiry, conflict handling, or the optimistic-concurrency meaning implied by expectedVersion, leaving notable gaps.

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 tight sentence with the action front-loaded and zero filler. Nothing here wastes the agent's attention.

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?

A mutating coordination tool with no annotations, no output schema, and 0% parameter coverage needs considerably more than one sentence. Key facts an agent must know, lease semantics, expiry, and expectedVersion handling, are absent.

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

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

Schema description coverage is 0%, so the description must compensate and does not. "bounded lease" loosely gestures at leaseMinutes but never names it or its default/limits, and expectedVersion (clearly an optimistic-locking token) is never explained. taskId is self-evident at best.

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 ("Claim") and resource ("task") plus a distinguishing scope ("with a bounded lease"). It separates itself reasonably from siblings like workflow_complete_task or workflow_get_task_context, though it never explicitly names an alternative.

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

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

The phrase "before local Copilot reasoning begins" implies sequencing/context for invocation, giving some usage guidance. However, it names no alternatives and states no explicit when-not or prerequisite conditions, so usage is only implied.

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

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

With no annotations provided, the description carries the full behavioral burden but stays silent. It does not say this is a state-mutating operation, what happens on a version mismatch (the presence of expectedVersion implies optimistic concurrency but this is never explained), whether the advance is reversible, or what permissions/approvals are needed.

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 compact sentence with no filler, so it is not verbose. However, its brevity comes at the cost of clarity — the sentence is dense with undefined internal terminology rather than being front-loaded with the actual effect.

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 mutating workflow tool with no annotations, no output schema, and two undocumented required parameters, the description is insufficient. It should at minimum state the mutation, the version-conflict behavior, and the resulting task state; none of that is present.

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 neither taskId nor expectedVersion is mentioned in the description. The phrase 'current local result' loosely gestures at a versioning concept but never explains that expectedVersion guards against stale writes, which is the single most important thing an agent must understand here.

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 abstract jargon ('confirm the current local result', 'advance it to its next persisted gate') rather than stating plainly that it marks a task complete. It never names the resource (task) or distinguishes this from close siblings like workflow_task_skip or workflow_ticket_advance. An agent would have to guess what 'persisted gate' means.

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

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

No when-to-use guidance and no exclusions. Given ~37 sibling tools including workflow_task_skip, workflow_ticket_advance, and workflow_submit_decision, the description offers nothing to help choose between them. The only implicit usage signal is the word 'complete'.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the required CREATED source state, which is useful, but says nothing about what activation changes, whether it is irreversible, permission requirements, or how expectedVersion failure is handled for this state transition.

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

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

A single front-loaded sentence with no filler; the action and its precondition are stated immediately. It is appropriately terse, though brevity here partly reflects missing detail rather than tight editing.

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 state-mutating tool with no annotations, no output schema, and no parameter documentation, the definition leaves key information missing. An agent cannot tell from the description alone what expectedVersion must be or what a successful/failed activation returns.

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 explains neither parameter. epicId is inferable from its name, but expectedVersion has non-obvious optimistic-concurrency semantics that are left entirely undocumented in both schema and description.

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

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

Specific verb+resource: 'Activate a CREATED epic', which clearly distinguishes it from sibling tools like workflow_epic_create and workflow_epic_attach_ticket. It also names the lifecycle precondition (CREATED state), though it doesn't explicitly contrast with other epic-state siblings such as workflow_epic_resume.

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?

'before attaching tickets' gives a sequencing cue: this must happen prior to attachment, implying when the tool is appropriate. However, there is no explicit when-not guidance and no named alternative for epics already active or in another state.

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 the full behavioral burden. 'Record' implies a mutation, but it doesn't say whether the operation is idempotent, whether it validates against cycles, what permissions are needed, or whether conflicting dependencies 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?

A single, well-formed sentence with the key relation type front-loaded and no wasted words. It is efficient, though its brevity is partly under-specification rather than disciplined 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?

For a mutation tool with no annotations, no output schema, and 0% parameter coverage, the definition omits too much: permission requirements, idempotency, error behavior, and the direction semantics of from/to tickets are all 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 0%, so the description must explain all three parameters. It hints at the mapping ('two tickets of one epic') and the relation direction via REQUIRES_BEFORE, but never clarifies which ticket is the prerequisite versus the dependent, nor the ID 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?

States a specific verb (Record), a precise relation type (REQUIRES_BEFORE), and the scope (two tickets of one epic). An agent can distinguish it from most siblings like workflow_epic_attach_ticket, though it does not explicitly name the closest 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?

No guidance on when to use this tool versus siblings such as workflow_epic_attach_ticket or workflow_epic_join. The use case is only implied by the word 'dependency'; prerequisites and exclusions are absent.

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 the full burden. It mentions the approval roles but omits critical behaviors: whether this requires a specific sequence (both roles required suggests two-step process), what happens if the change request isn't in an appropriate state, concurrency handling via expectedVersion, or any side effects. This is a significant gap for a mutation tool.

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

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

A single, front-loaded sentence that conveys the core action and roles without any 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 mutation tool with no annotations, no output schema, and 0% parameter documentation, the description is insufficient. It omits when to use it, parameter semantics, and behavioral details like idempotency or error conditions.

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

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

Schema description coverage is 0%, so the description must compensate. It only hints at actorRole through the roles mentioned, but doesn't explain changeRequestId or expectedVersion (e.g., optimistic concurrency). With three required parameters completely undocumented in the schema, the description falls short.

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 clear verb+resource ('Approve a change request') and the roles involved. However, it does not differentiate this tool from siblings like workflow_request_approval or workflow_submit_decision, leaving the agent to infer the distinction from the name alone.

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 by specifying the required roles, but it doesn't state when to use this tool versus alternatives like workflow_request_approval or workflow_submit_decision. No explicit when/when-not 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?

With no annotations, the description carries the full behavioral burden. It hints that only active epics accept tickets, but says nothing about idempotency, what happens if the ticket is already attached, permission requirements, or failure modes for an operation that mutates epic state.

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 wasted words. It is efficient, though the brevity is partly why contextual gaps remain.

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 3-parameter, all-required mutation tool with no annotations, no output schema, and 0% parameter documentation, the description is too thin. It covers the basic action but leaves the agent without enough context to invoke it confidently.

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%, so the description must compensate. It only clarifies the 'channel' parameter by listing enum values already present in the schema, and does not explain what epicId or ticketId must refer to, nor the relationship between the ticket and the epic.

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 ('Attach') and resource ('a channel ticket ... to an active epic'), making the operation identifiable. It does not explicitly differentiate itself from siblings like workflow_epic_add_dependency or workflow_epic_create_change_request, so it falls short of a 5.

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

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

The phrase 'to an active epic' implies a precondition (the epic must be active), which is useful. However, there is no guidance on when to use this tool versus alternatives such as workflow_ticket_advance or workflow_epic_join, and no exclusions or prerequisites are spelled out.

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 behavioral burden, and it discloses almost nothing: no idempotency, uniqueness constraints on epicId, side effects, or required permissions. The word 'fictional' hints this produces simulated/test data, which is the only behavioral signal present.

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 short sentence is front-loaded and wastes no words, but it is under-specified rather than genuinely concise. There is no structure to hang additional detail on.

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 annotations, no output schema, and three undocumented required parameters, the description leaves the agent without enough information to call this mutation tool correctly or understand its 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?

Three required parameters exist with 0% schema description coverage, and the description adds no meaning for epicId, title, or journeyId. Format expectations (e.g., length limits, ID conventions) are entirely 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 verb 'Create' and the resource 'Epic workflow aggregate' are stated, but 'aggregate' is unexplained jargon and the description never says what an Epic aggregate contains or how it relates to siblings like workflow_epic_create_change_request. It is only barely distinguishable from other workflow_epic_* creation tools.

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

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

There is no guidance on when to use this tool versus the many sibling workflow_epic_* tools, no prerequisites, and no mention of when it should not be used. The agent must infer usage entirely from the name.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it only signals 'emergency' and says nothing about required permissions, whether creation triggers an approval workflow, side effects on the epic, or reversibility. A single clause cannot cover a mutation tool with a downstream approval sibling.

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

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

One front-loaded sentence with zero padding, and the verb and resource lead immediately. It is efficiently written, though it is terse rather than genuinely informative.

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 five-parameter, all-required mutation tool with no annotations and no output schema, a single sentence leaves the agent without prerequisites, lifecycle, or return expectations. The description is far too thin relative to 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 0% and all five parameters (epicId, reason, urgency, description, affectedTicketIds) are undocumented in both schema and description. The description adds no meaning about the urgency enum values, the 200-item cap on affectedTicketIds, or the required reason/description fields.

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 (create) and resource (emergency change request) with the target (an epic), so the operation is immediately identifiable. It does not, however, distinguish itself from the sibling 'workflow_epic_approve_change_request' or clarify how this differs from workflow_epic_create.

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 no guidance on when to use this versus its siblings: nothing about when an emergency change request is warranted, whether approval must follow, or when a plain epic change is sufficient. The existence of a paired approve_change_request tool is left entirely implicit.

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 the full burden. It implies a state change (becoming an 'active participant') but says nothing about whether joining is idempotent, whether it requires authorization or an existing roster entry, what side effects occur, or how a duplicate join is handled. Only the barest behavioral hint is present.

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

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

A single front-loaded sentence with no filler; the verb and resource come first and the qualifying scope follows. Every clause carries information.

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

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

For a two-required-parameter mutation-style tool with no annotations, no output schema, and 0% parameter documentation, one sentence is not enough. The agent lacks permission requirements, idempotency behavior, and valid role values needed to call it correctly.

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

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

Schema description coverage is 0%, so both parameters are undocumented in structured data. The description loosely maps 'epic' to epicId and 'role' to actorRole, but adds no format, allowed values, or examples for the role string, leaving the agent to guess what a valid role looks like.

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

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

Names a specific verb (join) and resource (epic) and adds the scope 'as an active participant with a declared role', so the agent knows this is a membership action rather than a lifecycle action like workflow_epic_create or workflow_epic_activate. It stops short of explicitly contrasting itself with those siblings, so it is clear but not fully differentiated.

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

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

There is no statement of when to use this versus the many workflow_epic_* siblings, no prerequisites (e.g. must the epic exist or be active?), and no exclusions. 'Active participant' hints at context but the agent is left to infer the trigger conditions entirely.

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, covering the safety profile. The description adds useful behavioral context by enumerating what is read back (epic state, open tasks, next actions, audit trail), but doesn't address persistence, pagination, or error behavior. With annotations covering the safe-read profile, a 3 reflects marginal added 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?

A single front-loaded sentence with no wasted words, listing the four returned resources efficiently. Appropriate size for a read-only tool with one parameter.

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

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

For a simple read tool with a required epicId and readOnlyHint annotation, the description covers what is returned and the trigger scenario. However, it leaves the epicId undocumented and doesn't explain how to obtain it, which is a notable completeness gap given 0% schema coverage and 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%, so the description should compensate. It doesn't mention the epicId parameter or its format/source. The schema does enforce minLength and required, but the description adds no parameter meaning. Baseline is 3 given the single-parameter simplicity, but the lack of any param guidance is a 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 states a specific verb (read) and four concrete resources (persisted epic state, open tasks, next actions, audit trail) scoped to a shutdown recovery scenario. This distinguishes it reasonably from siblings like workflow_get_task_audit or workflow_list_my_tasks, though it doesn't explicitly name an alternative. Clear purpose overall.

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 post-shutdown condition ('after a shutdown') provides clear context for when this tool applies, which is a meaningful usage trigger. However, it doesn't state when NOT to use it or name explicit alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only the scope of what is read and no other behavioral traits, such as what 'freshness' is expressed as, whether results are per-repository or per-journey, or what happens when no journeyId is supplied.

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

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

A single front-loaded sentence with no filler; the core concept (read freshness/staleness) leads. It is perhaps overly terse for a tool whose key term needs definition, but nothing 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 must explain what is returned, yet it never says whether freshness is a timestamp, an age, or a stale/current flag. For a read tool with an optional filter and no return-value documentation, an agent cannot predict the result shape.

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 single optional journeyId parameter is never referenced in the description. 'journey and repository context' hints that a journey may be scoped, but optionality and the behavior when the parameter is omitted are 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?

States a specific verb ('Read') and resource ('freshness (staleness) of journey and repository context'), with a clarifying parenthetical that resolves the ambiguous term 'freshness'. It does not differentiate itself from the closely related sibling workflow_mark_context_stale, leaving the agent to infer the read/write distinction.

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

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

There is no statement of when to call this tool, when not to, or which sibling to prefer. The obvious pairing with workflow_mark_context_stale (which presumably invalidates the same freshness state) is never mentioned, so the agent gets no 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, so the agent knows this is a safe read. The description adds the useful context that GitHub membership isn't required for certain roles, but it doesn't explain what the tool returns, whether identity is always bound, or what happens if no identity 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?

Two short sentences, but the second sentence feels somewhat tangential to the core action and could be considered noise for an agent deciding whether to invoke. The core action is front-loaded, which is good, but the second sentence lacks clear connection to invocation criteria.

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 zero params, readOnly annotation, and no output schema, the description covers the basic purpose. However, it leaves gaps: no indication of what 'bound enterprise identity' means in practice, no error conditions, and no guidance on when a caller should use this vs other workflow_get_* 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?

Zero parameters, so the baseline is 4. The description doesn't need to explain parameter semantics, and it correctly avoids doing so.

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 ('Read') and resource ('the bound enterprise identity'), which is clear and specific. It doesn't explicitly distinguish itself from siblings like workflow_get_related_artifacts or workflow_get_task_context, but the resource is unique enough that an agent can tell it apart.

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 second sentence ('GitHub membership is not required for non-coding Scrum Masters') hints at a use case but doesn't state when to call this tool vs alternatives. There is no conditional guidance, no prerequisites, and no named 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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read. The description adds useful behavioral context that annotations do not cover: results are 'evidence-labelled' and carry an 'observation time', which hints at provenance and freshness semantics. It stops short of explaining what 'evidence-labelled' means or how stale results can be.

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

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

A single front-loaded sentence that states the action, the scope, and the two distinguishing output traits with no filler. Nothing is redundant or padded.

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 and zero parameters, the description is the only source of return-value information, and it only gestures at it via 'evidence-labelled' and 'observation time'. It is enough to call the tool correctly, but the agent gets no sense of diagnostic shape, severity fields, or failures.

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 per the rubric the baseline is 4; there is nothing for the description to disambiguate. No parameter detail is added or needed.

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 names a specific verb (read) and resource (integration diagnostics) and enumerates the covered systems (Jira, Confluence, GHES, Jenkins, Splunk), so the agent knows exactly what surface this covers. It does not explicitly contrast itself with sibling read tools like workflow_get_freshness or workflow_get_task_audit, which keeps it short of a 5.

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

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

There is no statement of when to call this versus alternatives such as workflow_get_freshness or workflow_get_related_artifacts, nor any prerequisite or exclusion. The implied usage (fetching integration health diagnostics) is inferable from the purpose but never spelled out.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is low. The description adds that the graph is deterministic and derived from a manifest, which is useful context about the nature of the result, but says nothing about output shape, size, or failure modes when the manifest is missing/invalid.

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 tight sentence with the key resource and its contents front-loaded and no filler. Clean, though the parenthetical enumeration is dense and the sentence could carry one more clause of guidance at no real cost.

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 and 0% parameter coverage, the description partially compensates by naming the graph's components (repositories, screens, http edges), but it omits how journeyId relates to the manifest and gives no sense of the returned structure beyond a noun list.

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% for the single required parameter journeyId. The description refers to a 'manifest' as the input source, which does not correspond to the declared journeyId parameter, so it adds no clarifying meaning and arguably muddies what the parameter should be.

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 (Build) and resource (journey graph) and enumerates the graph's contents (repositories, screens, http edges) plus its source (a manifest). This distinguishes it reasonably well from siblings like workflow_get_repository_graph and workflow_analyze_journey, though it never explicitly contrasts 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as workflow_get_repository_graph or workflow_analyze_journey. The agent must infer usage entirely from the name and the tool 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?

The 'never claims simulated evidence is real' clause adds a behavioral guarantee beyond the readOnlyHint annotation, which is genuinely useful context. However, it is cryptic and doesn't explain what the returned action looks like, whether it mutates state, or how validation progresses.

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 compact sentence with no waste. Structure is fine, though the trailing honesty clause is oddly placed rather than 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?

No output schema and no parameters, so the description must carry the full burden of explaining what the tool returns and how it fits the validation workflow. The opaque honesty clause and absent return-value description leave significant gaps for an agent trying to use it.

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

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

Zero parameters, so baseline is 4. No param info is needed and none is missing.

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 verb (Read) and resource (next company-network validation action), so purpose is discernible but the domain jargon 'internal validation' / 'company-network validation action' is vague. It does not clearly distinguish from siblings like workflow_validate_pod_roster or workflow_submit_decision.

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 indication of when to call this versus alternatives, no prerequisites, no sequencing context in a workflow that clearly has validation stages. The agent must infer usage entirely.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds useful context that traversal is over a persisted graph and bounded by depth, but does not describe what artifacts look like, whether results are paginated, or how depth affects the result set.

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

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

A single front-loaded sentence that carries the operation, mechanism, and constraint with 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 read-only tool whose safety profile is already covered by annotations and which has no output schema, the description is adequate but thin. It leaves the nature of 'artifacts', the return shape, and the practical meaning of depth bounds unspecified.

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

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

Schema description coverage is 0%, so the schema itself documents neither parameter. The description compensates partially by explaining that maxDepth bounds the traversal, and taskId is self-evident from its name, but it adds no format, range, or default 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?

States a specific verb (Read), resource (artifacts related to a task), and mechanism (persisted artifact graph bounded by depth). This is clear enough for an agent to understand the operation, though it does not explicitly distinguish itself from adjacent read tools like workflow_get_task_context or workflow_get_repository_graph.

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

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

The phrase 'related to a task' implies a context but there is no explicit when-to-use, when-not-to-use, or named alternative among the many sibling read tools. An agent must infer the routing decision on its own.

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?

readOnlyHint=true already tells the agent this is a non-mutating operation, so the safety profile is covered. The description adds a useful behavioral trait ('deterministic') and identifies the derivation source (journey manifest), but says nothing about cost, latency, caching, or whether the graph is persisted or recomputed.

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 efficient sentence with the action front-loaded and no filler. It is appropriately sized, though there is room to spend a few more words on usage and return semantics given how sparse the rest of the definition is.

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

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

There is no output schema, so the description carries the burden of explaining what the graph returns (nodes, edges, format), and it does not. Combined with an undocumented parameter and no usage guidance, the definition is thinner than the tool's complexity warrants.

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 single parameter has only length constraints (minLength 3, maxLength 80). The phrase 'journey manifest' weakly implies journeyId identifies such a manifest, but the description never explains the ID format or where to obtain it, leaving the parameter under-specified.

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 pairs a specific verb ('Build') with a specific resource ('repository dependency graph') and names the input source ('journey manifest'). However, it offers no differentiation from close siblings such as workflow_get_journey_graph, workflow_scan_repository_context, or workflow_analyze_http_dependencies, which an agent could easily confuse it with.

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

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

There is no statement of when to use this tool versus alternatives, no prerequisites, and no exclusions. The agent must infer the workflow context (post-onboarding, pre-analysis) entirely from the tool name.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes beyond that by disclosing filtering semantics: compensated and invalidated events are excluded by Workflow Service. This tells the agent the returned stream is pre-filtered, which is meaningful behavioral context not present in structured fields.

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

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

Two short sentences with zero filler, and the primary action ('Read the valid task audit stream') is front-loaded. The filtering caveat follows efficiently. Appropriately sized for a one-parameter read tool.

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 single-parameter read with readOnlyHint and no output schema, the definition covers the essential behavior including the exclusion rule. It stops short of describing the shape or ordering of the returned audit stream, which an agent might want given the absence of an 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% for the single required taskId parameter, so the burden falls on the description, which never mentions the parameter. While taskId is fairly self-evident by name, the description adds no semantics such as accepted ID format or scope, leaving the parameter 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?

States a specific verb (read) and resource (task audit stream), which distinguishes it from mutation siblings like workflow_complete_task or workflow_submit_artifact. However, it does not explicitly contrast itself with the similarly named workflow_get_task_context. Clear purpose, but no 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 offers no when-to-use guidance, no prerequisites, and does not name any alternative such as workflow_get_task_context or workflow_get_related_artifacts. An agent must infer when an audit stream is the right resource to request.

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 safety profile is covered. The description adds only that the state is 'persisted' (i.e. durable, not in-memory), with no mention of failure modes, auth needs, or what 'task state' comprises. Some added context, but thin.

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

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

A single front-loaded sentence with no filler. It is efficient, though it is arguably clipped to the point of under-specification rather than tightness.

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?

Low-complexity, read-only tool with one parameter and no output schema, so the description should at least sketch what state is returned. It names the resource but not its contents or the identifier's origin, leaving the agent only partly equipped to call it.

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

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

The sole parameter taskId has 0% schema description coverage, and the description says nothing about it — no format, source, or how to obtain it. With the schema carrying no meaning and the description not compensating, the agent must guess where the identifier comes from.

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

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

States a specific verb+resource ('Read the persisted task state'), which tells the agent exactly what the tool retrieves. It does not, however, differentiate itself from look-alike siblings such as workflow_get_task_audit or workflow_get_freshness, so an agent must infer the distinction from context.

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 timing cue ('before starting or resuming local Copilot work') that implies the usage window, but names no alternatives and no when-not conditions. The agent gets a rough sense of when this fits but no routing logic against the many sibling get_* 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?

With no annotations, the description carries the full burden and does disclose one meaningful trait: persistence must follow explicit human confirmation. But it is silent on the behavior implied by 'persist' beyond that — overwrite semantics, expectedRevision conflict handling, and reversibility are undisclosed.

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 filler. The action and its gating condition are both stated within one line, with no redundant 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?

For a complex mutation with 4 undocumented required params, no annotations, and no output schema, a one-line description leaves major gaps — notably how expectedRevision guards against stale writes. It is incomplete relative to the tool's surface 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 0% and all 4 parameters are required, so the description must compensate. It only loosely gestures at 'roster' (mapping to memberships) and never explains journeyId, expectedRevision, or the const-true confirmed flag. Most parameter intent remains 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?

States a specific verb+resource ('Persist a ... Pod roster') and implies a precondition ('validated'). The qualifier 'validated' hints at the sibling workflow_validate_pod_roster but never names it, so sibling differentiation is only implicit. Clear enough for an agent to grasp the 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?

'only after explicit human confirmation' is a genuine usage precondition, which is more than most definitions offer. However, it does not name the validate step as an alternative/prerequisite tool or state when this should not be called, leaving routing 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 declare readOnlyHint=true, so the safety profile is covered by structured data. The description adds two useful behavioral nuggets beyond that: tasks are 'persisted' (i.e., stored records, not ephemeral/in-memory state) and results are scoped to the current user, implying an authentication-derived filter. It does not describe ordering, pagination, or volume limits.

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

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

A single clause, front-loaded with the action verb and resource, with zero filler. Nothing in it is redundant with the tool 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?

For a zero-parameter read tool with no output schema, the agent still lacks any sense of the return shape (fields per task, ordering, whether the list can be large) and of what 'persisted' distinguishes from other task representations in this workflow family. The description is adequate to invoke the tool but thin on outcome expectations.

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 according to the rubric the baseline is 4. There are no parameter semantics for the description to add, and it correctly avoids inventing filtering options the schema does not support.

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), a specific resource (persisted workflow tasks), and a scope qualifier (visible to the current user). It is clearly distinguishable from write-oriented siblings like workflow_claim_task or workflow_complete_task, though it never names an alternative explicitly.

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

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

The description gives no when-to-use guidance, no prerequisites, and no alternatives such as workflow_get_task_context or workflow_get_task_audit which also surface task information. Usage must be inferred entirely from the name.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose a meaningful consequence ('force re-onboarding'), but omits whether the marking is reversible, what exactly becomes invalid, whether it blocks downstream task/decision tools, and any permission requirements. It is helpful but thin for a state-mutating tool.

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

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

A single, front-loaded sentence with the verb, resource, and consequence in immediate sequence. No filler or redundancy.

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

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

For a zero-parameter, no-output, no-annotation tool that mutates context state, the description is adequate but leaves the key operational questions open: what gets invalidated, with what scope, and what the caller should expect afterward. A sentence on the resulting state or required follow-up would close the gap.

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

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

The tool takes zero parameters, so the schema baseline of 4 applies. Nothing about parameter meaning is left ambiguous, though the description does not explain how 'journey' vs 'repository' scope is selected given there are no 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 states a specific verb ('Mark'), a specific resource ('journey or repository context'), and the effect ('as stale'), plus the downstream intent ('to force re-onboarding'). This clearly distinguishes it from the onboarding and freshness siblings (workflow_onboard_journey, workflow_get_freshness), though it does not name any sibling explicitly.

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

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

Usage is only implied by the purpose clause: call it when you want to force re-onboarding. There is no explicit when-to-use/when-not-to-use guidance and no statement of which alternative to prefer (e.g., re-running workflow_get_freshness vs. this) or what precondition makes context 'stale'.

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 carries the full behavioral burden, yet it says nothing about idempotency, whether an existing journey is overwritten, what happens when 'manifest' is omitted, permissions, or failure modes. For an onboarding/mutation-style tool this is a significant gap.

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

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

A single, front-loaded sentence with no filler; the verb and source are stated immediately. It is efficient, though it is arguably too terse given the complexity it must cover.

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 a deeply nested manifest schema, no annotations, and no output schema, yet the description is one sentence. It omits manifest requirements, mutation semantics, and result behavior, leaving the agent under-informed for a complex onboarding 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 0%, so the schema names parameters without documenting them. The description hints that onboarding is driven 'from its manifest', but never explains the relationship between the required journeyId and the optional manifest, nor what omitting manifest does. It does not compensate for the coverage gap.

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

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

States a specific verb (onboard) plus resource (journey) and the source of truth (its manifest), and 'into the local workflow context' scopes the effect. It distinguishes itself from workflow_onboard_repository by resource, though it doesn't explicitly call out that sibling.

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

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

There is no when-to-use, when-not, or alternative guidance. The agent must infer that this is the journey analogue of workflow_onboard_repository, and nothing states prerequisites or when the manifest is required vs. omitted.

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 behavioral burden. It never states whether onboarding is idempotent, what state it creates or mutates, whether a journey must already exist, or what happens on conflicting aliases/URLs.

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 wasted words, but its brevity reflects under-specification rather than efficient density. It is concise without being informative.

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 3-parameter, mutation-style tool with no annotations, no output schema, and no parameter documentation, the description omits nearly everything an agent needs: prerequisites, side effects, and the meaning of each argument.

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 3 parameters at 0% schema description coverage, the description should explain them, but it mentions only the general 'repository' concept and says nothing about repositoryAlias being required, what journeyId binds to, or how repositoryUrl is used. No compensation for the coverage gap.

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

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

The description pairs a specific verb ('Onboard') with a resource ('repository'), but 'local workflow context' is vague and does not distinguish this tool from close siblings such as workflow_onboard_journey or workflow_scan_repository_context. An agent knows the general area but not the precise effect.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives like workflow_onboard_journey or workflow_scan_repository_context. The agent must infer the trigger condition entirely.

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 supply readOnlyHint=true, so the safety profile is largely covered. The description adds genuine context beyond that: it is a local projection built from already-persisted tickets and explicitly makes no external Jira call. It does not say where the projection is written, what it contains, or what is returned.

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, front-loaded with the action and resource, with zero filler. Nothing to trim.

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 annotation beyond readOnlyHint, yet the description omits where the projection is materialized, what an agent should do with the result, and what both parameters mean. Too thin for a tool whose semantics are non-obvious.

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% for both parameters, and the description supplies no meaning for epicId or targetBoard. With two undocumented parameters, the description fails to compensate for the schema gap.

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

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

The description names a specific verb (Prepare) and a specific artifact (local Jira projection from persisted tickets), and clarifies the source of truth. It is clear, though it does not distinguish itself from any of the numerous workflow_* 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?

There is no guidance on when to use this versus alternatives, nor any stated prerequisite or ordering relative to sibling tools like workflow_epic_attach_ticket. The 'without calling Jira' phrase hints at a use case but does not constitute usage guidance.

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

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

With no annotations, the description carries the full behavioral burden and discloses very little. It implies a write operation but does not state whether recordings are append-only or overwrite prior results, whether FAIL outcomes trigger follow-up actions, what permissions are required, or whether evidenceNotes are mandatory.

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 well-formed sentence with the action and resource front-loaded and no filler. Efficient, but it is under-specified rather than genuinely concise-with-completeness.

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?

A mutation tool with no annotations, no output schema, and 0% schema coverage on 4 parameters needs substantially more text than one sentence. An agent lacks the information needed to call it correctly, particularly which result values mean what and what evidenceNotes must contain.

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% across 4 parameters (taskId, result, wcagLevel, evidenceNotes), so the description must compensate and does not. Only the word 'WCAG' loosely gestures at wcagLevel; the PASS/FAIL/MANUAL_REVIEW_REQUIRED enum, the AA default, and the role of evidenceNotes are all left unexplained.

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 ('Record'), resource ('WCAG accessibility check result') and scope ('for a task'), and the WCAG qualifier distinguishes it from lookalike siblings such as workflow_record_manual_e2e and workflow_record_tagging_result. It is clear what the tool does, though it does not explicitly name which sibling it supersedes.

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

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

No when-to-use guidance, no prerequisites, and no mention of the closely related recording tools (workflow_record_manual_e2e, workflow_record_tagging_result) an agent must choose between. Usage must be inferred entirely from 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?

No annotations exist, so the description carries the full behavioral burden. It hints that the operation must reflect genuine manual verification (an anti-fabrication constraint), but says nothing about write/mutation semantics, permissions, reversibility, or what happens to prior records. That is a thin disclosure for a state-mutating tool.

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

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

A single front-loaded sentence with no filler; the key qualifier is placed prominently. Nothing in the sentence is redundant.

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 four required, fully undocumented parameters, no annotations, and no output schema, the description is far too sparse for an agent to call this correctly. It supplies neither the required parameter semantics nor the mutation/authorization context that the missing structured fields would otherwise provide.

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% across four required parameters (taskId, result, evidenceNotes, executedBy), and the description adds no meaning for any of them. The PASS/FAIL/BLOCKED enum and the 1-2000 character evidenceNotes constraint are left entirely 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 names a specific verb (record) and resource (manual end-to-end verification result), and the qualifier 'without fabricating automation evidence' usefully distinguishes it from automated equivalents. It does not explicitly name its closest siblings (workflow_record_accessibility_result, workflow_record_tagging_result), but the purpose is unambiguous.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The phrase 'manual' implies it should be used only for hand-run verification rather than automated runs, but no alternative tool or condition is named, leaving the agent to infer the routing.

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

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

No annotations are provided, so the description carries the full behavioral burden. It says 'bounded' but never discloses whether recording replaces or appends prior results, whether it is idempotent, what permissions are needed, or what the response contains.

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 efficient sentence with the action front-loaded and no filler. Nothing is wasted, though there is also very little 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?

A record/mutation tool with no annotations, no output schema, and 0% parameter description coverage needs substantially more than one sentence. An agent cannot tell what gets persisted, how duplicates are handled, or how this differs from other recording 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 description coverage is 0%, so the description must compensate. 'content-tagging or taxonomy classification' loosely gestures at the tags array and 'for a task' at taskId, but the source enum (MANUAL/AUTOMATED) and the tag/count limits are entirely unexplained.

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 (Record) and resource (content-tagging or taxonomy classification result) scoped to a task. It is clear what the tool does, but it never distinguishes itself from similar 'record result' siblings such as workflow_record_accessibility_result or workflow_record_manual_e2e.

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 no when-to-use context, no prerequisites, and no alternatives. 'for a task' implies the scope but not the trigger condition or how it relates to sibling recording 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?

No annotations are provided, so the description carries the full behavioral burden. It implies a write/report operation but does not disclose side effects, required permissions, reversibility, state changes to the ticket, or error behavior. 'Typed reason and bounded description' describes inputs, not behavior.

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

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

A single, front-loaded sentence with no filler. Every phrase adds meaning about the action and its required inputs.

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

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

For a mutation-style tool with no annotations, no output schema, and 0% parameter description coverage, the description is too thin. It does not explain what reporting a blocker does to the ticket, who can do it, or what result to expect.

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

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

Schema description coverage is 0%, so the description must compensate. It semantically identifies all three required parameters: a ticket target, a typed blocker reason, and a bounded description. However, it does not explain the enum values or length limits, so the compensation is only partial.

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 clear verb ('Report') and resource ('a blocker against a ticket'), plus the key input types ('typed reason and bounded description'). It does not distinguish this tool from any of the many sibling workflow_* tools, so it falls short of full 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?

Usage is only implied by the phrase 'Report a blocker against a ticket'; there is no explicit when-to-use guidance, no when-not-to-use conditions, and no mention of alternatives among siblings like workflow_mark_context_stale or workflow_request_approval.

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 supplied, so the description carries the full burden. It reveals that this is a write operation recording an approval, but says nothing about immutability, idempotency, required permissions, or what happens when the supplied versions do not match the current state (the optimistic-lock semantics implied by expectedTaskVersion).

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 filler and the action stated first. It is tight to the point of being underspecified for a four-parameter mutation, but nothing in the 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?

For a four-required-parameter mutation with no annotations, no output schema, and no parameter descriptions, the definition is too thin. It omits the version-guard behavior, who may call it, and what recording an approval causes downstream, all of which an agent needs before invoking 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 0% across four required parameters, so all semantic burden falls on the description. It gestures at 'exact artifact and task version' but never explains the distinction between artifactVersion and expectedTaskVersion, nor that the latter acts as a concurrency guard, leaving two of four parameters effectively 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?

States a clear verb+resource ('Record a human approval') and the scoping object ('an exact artifact and task version'), so the agent knows the action writes an approval record rather than computing status. It does not, however, distinguish itself from closely related siblings like workflow_submit_decision or workflow_epic_approve_change_request, leaving the reader to infer which approval surface this applies to.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the many approval/decision siblings. The phrase 'human approval' weakly implies a human rather than agent is the approver, but no condition or exclusion is 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 declare readOnlyHint=true, so the safety profile is covered, but the description adds nothing behavioral beyond that: no indication of what gets scanned, how expensive/wide the scan is, or what a 'summary' contains. With annotations carrying the safety signal, the description fails to add the additional context that would earn a higher score.

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 compact sentence with no wasted words and the core action front-loaded. It is efficient, though brevity here comes partly from under-specification rather than precision.

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

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

For a read-only, single-parameter tool with no output schema, the description is roughly the minimum viable: safety is covered by annotations and no return values need explaining. It still leaves the required journeyId undocumented and the scan scope and sibling boundaries unclear, so it is adequate but noticeably thin.

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 required parameter journeyId has 0% schema description coverage and is never mentioned in the description, so its meaning (which journey's repository context is scanned, and why it is required) is left entirely unexplained. The description does not compensate for the coverage gap.

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

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

States a verb ("Scan and summarize") and a resource ("repository context"), so the action is identifiable. However, "repository context" is vague and the description never differentiates this tool from close siblings such as workflow_onboard_repository or workflow_get_repository_graph, which sound like they could do the same thing.

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

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

The phrase "for onboarding or graph building" implies when the tool is relevant, giving implied usage context. It names no alternative tools and gives no exclusion criteria, so an agent cannot tell from the description alone when to prefer this over the sibling onboarding/graph 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?

No annotations are provided, so the description must carry the full behavioral burden. It implies a write/side-effecting operation but says nothing about idempotency, whether artifactId must be unique, what happens on conflicting contentHash, permissions required, or whether the artifact becomes visible to other tasks. The 0% schema coverage and lack of annotations leave significant behavioral gaps.

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 wasted words. It is appropriately sized, though the brevity contributes to the specifications gaps noted elsewhere.

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

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

For a 5-parameter, 4-required mutation tool with no output schema and no annotations, the definition is incomplete. An agent cannot determine required permissions, idempotency behavior, how sections map to storage, or what a successful submission returns or enables. In a toolset of ~40 workflow siblings, this tool needs more context to be callable 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 0% and the description adds no parameter detail. Required fields (taskId, artifactId, type, sections) are only inferable from the schema's structure; the enum's six report types and the semantics of contentHash are not explained. The description does not compensate for the complete lack of schema-level parameter documentation.

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 verb ('Persist') and a resource ('structured, human-readable workflow artifact produced by local Copilot'). It is somewhat clearer than the name alone, but 'Persist' is ambiguous here—unclear whether it means submit to a server, save to disk, or register with a workflow—and it does not distinguish this tool from siblings like workflow_sync_onboarding_artifact or workflow_get_related_artifacts.

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

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

There is no guidance on when to use this tool versus the many related workflow tools (e.g., workflow_submit_decision, workflow_sync_onboarding_artifact, workflow_record_* variants). The phrase 'produced by local Copilot' hints at context but does not tell an agent when submission is required or how it relates to task or artifact retrieval.

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 the full disclosure burden and does not meet it. 'Persist' implies a write, but there is no mention of permission requirements, whether decisionId acts as an upsert key, whether submissions are immutable, or how the default ACCEPTED status behaves.

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 tightly worded sentence with the key scoping phrase ('for a journey') front-loaded and no filler. It is efficient, though the brevity here reflects under-specification rather than disciplined economy.

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?

A mutation tool with 7 required fields, no annotations, and no output schema cannot be called confidently from one sentence. Nothing tells the agent the expected lifecycle of a decision record or what a successful submit returns.

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?

Eight parameters with 0% schema description coverage and the description explains none of them. The distinction between decisionId and journeyId, the meaning of the options/chosen pair, and the semantics of the status enum are entirely 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?

States a specific verb ('Persist') and a clearly bounded resource ('architectural or product decision (ADR-style) for a journey'). An agent can grasp what this records, though it never contrasts itself with adjacent tools like workflow_submit_artifact or workflow_report_blocker.

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

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

There is no statement of when to use this tool versus siblings, no prerequisites (e.g., must the journey exist first), and no exclusions. The agent must infer placement in the workflow entirely from the name.

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

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

No annotations are provided, so the description carries full burden. It says 'sync' but doesn't explain whether it overwrites, merges, creates, or updates, whether it requires an active journey, or what happens on conflict. For a write operation with zero annotation coverage, this is a significant gap.

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

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

A single efficient sentence with no waste, front-loading the verb and resource. However, it is arguably under-specified rather than concise.

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

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

For a 4-parameter mutation tool with no annotations, no output schema, and 0% schema description coverage, the description is inadequate. It omits behavioral, parameter, and usage context needed to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the schema only provides types, lengths, enums, and required flags. The description mentions no parameters at all – it doesn't clarify artifactType values, journeyId vs repositoryAlias usage, or content constraints. With low coverage the description must compensate, and it 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?

Clear verb 'sync' and resource 'onboarding artifact' with a concrete example (CONTEXT.md). It distinguishes from siblings like workflow_submit_artifact or workflow_get_related_artifacts, though 'sync' could be ambiguous (push? pull? bidirectional?).

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 versus workflow_submit_artifact, workflow_onboard_repository, or workflow_onboard_journey. The agent must infer context from the name 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 are provided, so the description carries the full burden. It does disclose a meaningful trait: the skip is recorded as a persisted attestation requiring a reason, a conversation partner, and an actor role, implying an auditable mutation. It does not say whether the skip is reversible, what permissions are required, or what happens to the stage afterward.

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 compact sentence, front-loaded with the action and scoped by its key behavioral trait. It is efficient, though arguably over-terse given the tool's complexity.

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

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

For a 5-parameter mutation tool with no annotations, no output schema, and 0% schema description coverage, this is materially incomplete. The agent learns the attestation fields but not what skipping does to the workflow, whether it is reversible, or how the version guard works.

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% across 5 parameters, so the description must compensate. It names three of them (reason, discussedWith, actorRole) in parenthetical form, but leaves taskId and, more importantly, expectedVersion completely unexplained. The optimistic-concurrency semantics of expectedVersion are the highest-risk gap 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?

States a specific verb ("Skip") and resource ("a stage"), and adds that the skip carries a persisted attestation. However, the tool is named workflow_task_skip while the description talks about a "stage", and nothing distinguishes it from siblings such as workflow_ticket_advance or workflow_complete_task, so an agent must infer the difference.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. With 40+ sibling workflow tools, the agent gets no signal about when skipping is appropriate versus completing, advancing, or reporting a blocker.

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 supplied, so the description carries the full behavioral burden. 'Create' implies a mutation, but it says nothing about required permissions, what happens if the ticket or repository is unknown, whether the operation is idempotent, or what is returned.

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 well-formed sentence with the action front-loaded and no filler. It is efficient, though the brevity is arguably a symptom of under-specification rather than disciplined concision.

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 3-required-parameter mutation tool with no annotations, no output schema, and no parameter documentation, the description is far too thin. It omits prerequisites, side effects, and parameter meaning that the structured fields do not supply.

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 three required parameters (ticketId, repositoryAlias, baseCommit) have 0% schema description coverage, and the description adds no meaning beyond the names. baseCommit in particular is ambiguous — a SHA? a branch? — and the description does nothing to resolve it.

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

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

States a specific verb ('Create'), resource ('repo-level implementation task'), and scope ('under a ticket'). It is distinguishable from most siblings, but it never names or contrasts with close alternatives such as advance_repo_task or workflow_epic_create, so sibling differentiation is left to inference.

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

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

There is no guidance on when to use this versus alternatives like advance_repo_task or workflow_epic_create, nor any preconditions such as whether the ticket must already exist or be in a particular state. Usage is only implied by the tool name.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'With an exact version' hints at optimistic concurrency control, but it does not state what happens on a version mismatch, which transitions are legal, whether the call is idempotent, permission requirements, 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?

A single front-loaded sentence with no filler. It is efficient, though given the mutation semantics and 12-state enum it is arguably under-specified rather than optimally concise.

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

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

For a state-mutating tool with no annotations, no output schema, three undocumented parameters, and a 12-state enum, the description omits critical context: valid transitions, concurrency failure behavior, and return semantics. It is not complete enough for reliable 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 0%, so the description must compensate. It conveys some meaning for expectedVersion ('exact version' implies optimistic locking) and gestures at target ('delivery status machine'), but ticketId is unexplained and the 12-value enum has no transition semantics documented anywhere.

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 ('Advance') and resource ('ticket') plus the delivery status machine concept, so the operation is identifiable. It does not explicitly distinguish itself from the similarly named sibling advance_repo_task or from workflow_complete_task, so sibling differentiation is left to inference.

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

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

There is no guidance on when to use this tool versus alternatives like advance_repo_task or workflow_complete_task, nor any stated preconditions. The only hint is the implied need for an exact version, which is a constraint rather than usage guidance.

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

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

readOnlyHint=true is already declared in annotations, and the description's 'without persisting it' largely restates that same guarantee rather than extending it. It says nothing about what the validation actually checks (bounds, role validity, revision conflict), whether failures return errors or a result payload, or whether validation is deterministic. Adds minimal value 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?

A single efficient sentence with no filler and the non-persistence qualifier front-loaded. But brevity here shades into under-specification: the sentence is short because so much is left unsaid, not because it is dense.

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 a rich nested schema, three required params, no param descriptions, and no output schema, the description should explain validation semantics and especially what expectedRevision implies (optimistic concurrency). It does neither, leaving the agent unable to interpret validation outcomes or revision failures.

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% across three required parameters, including a nested memberships array with eight required subfields each. The description supplies no meaning for journeyId, expectedRevision, or memberships, so it fails to compensate for the coverage gap; only the word 'roster' loosely gestures at memberships.

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 ('Validate') and resource ('Pod roster') and adds the key qualifier 'without persisting it,' which separates it from a save/import action. It does not name the obvious sibling workflow_import_pod_roster, so the agent must infer the pairing, but the purpose itself is unambiguous. The word 'bounded' is undefined and does little work.

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

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

The phrase 'without persisting it' implies a pre-flight/check usage context, from which an agent can infer 'validate before committing'. However, no explicit when-to-use trigger, no prerequisites, and no alternative (workflow_import_pod_roster) is named, so the guidance stays implied rather than stated.

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