Agile Today

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

Annotations already declare readOnly/idempotent/non-destructive, but the description goes well beyond them: outcome precedence (Stop > Recycle > Hold > Conditional go > Go), the state-to-outcome rules, modifier semantics, and the receipt hash return. It discloses the full decision logic an agent needs to predict behavior, and is consistent with the read-only, idempotent annotations.

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

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

The description is front-loaded with the core purpose and precedence before drilling into edge cases, and every clause carries a rule rather than filler. It is nonetheless a single dense paragraph that mixes precedence, modifiers, and special cases, which makes it harder to scan than a structured breakdown would be.

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 12-parameter tool with nested objects and no output schema, the description covers the decision model and edge cases thoroughly and notes the receipt hash return. It only lightly characterizes the returned envelope (beyond the hash), which is the one small gap remaining.

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 92%, so the baseline is 3, and the description meaningfully exceeds it by explaining cross-parameter mechanics: earlier_stage_invalid must be paired with invalid_stage/invalid_artifact, and work_started_beyond flips to a Hold specifically at G8. These pairing/context rules add value beyond the field-level descriptions.

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

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

States a specific verb and resource ('Evaluates gate g.g0 … g.g10 against your evidence') and even tells the agent what the call produces (a receipt hash), so the purpose is unambiguous. It never names or contrasts with siblings like validate_plan or check_mix, so it stops short of the explicit differentiation a 5 requires.

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

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

Gives concrete invocation guidance for edge cases ('Call without evidence to list what the gate needs', 'pass earlier_stage_invalid:true with invalid_stage:'st.discovery'', 'at G8 ... work_started_beyond:true'). It does not, however, say when to reach for this tool over validate_plan or the other siblings, so no exclusions are provided.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description still adds real behavioral value by defining the ok flag and the non-obvious rule that a severity=warning pattern does not flip ok. It does not cover rate limits or the effect of the context object on results, but the disclosed ok semantics is meaningful beyond the annotations.

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

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

Two sentences with little fat, and the ok semantics is front-loaded in the second sentence. However the first sentence is a long comma-delimited fragment ('antipatterns in the set and detected by rules, conflicts, redundant alternatives...') that is dense to parse and would read better as a structured list.

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 usefully enumerates the returned categories and defines ok, which is the main thing an agent needs. It still omits how the context object shapes the check and how this tool relates to the seven sibling tools, which matters for a tool with nested parameters and close alternatives.

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 67%, and the nested context object is heavily self-documented (ap, sc, dom, size, physical, high_stakes all have descriptions). The description only clarifies that ids is a 'set' being cross-checked; it adds no format, ordering or constraint detail beyond the schema, so baseline 3 is appropriate.

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

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

The description makes clear that the tool takes a set of practice ids and surfaces antipatterns, conflicts, redundant alternatives, avoid/not-applicable items, risks and missing inputs, so the resource and outcome are understandable. It never names or distinguishes itself from siblings like check_gate or validate_plan, so an agent must infer the boundary on its own.

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 statement of when to reach for check_mix versus check_gate, validate_plan or when_to_use. The only conditional content is about result interpretation (the ok flag), not about tool selection, so an 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, idempotentHint, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it discloses the return shape (links grouped by type) and the citation mechanism (each link carries an Lxxxx id to cite), which is the kind of context an agent cannot get from the annotations or schema.

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

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

Two dense sentences with no filler, and the return-shape information is front-loaded ahead of the filtering note. Slightly telegraphic phrasing ('One node with its description, conditions, source, level') 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 carries the return-value burden and does so by enumerating the fields and the link grouping/citation scheme. The remaining gap is the meaning of some parameters and node fields, but for a low-risk read tool this is close to sufficient.

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

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

Schema description coverage is only 20% (only lang is documented), so the description has to compensate. It names link_types, direction, and limit and frames them all as filters, which clarifies intent, but it leaves 'id' and the direction semantics (in/out/both) unexplained, so coverage remains 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?

States a specific resource and its payload: one node plus description, conditions, source, level, and links grouped by type. It is distinguishable from read-oriented siblings like search_graph or list_context, though it never names those alternatives 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 final sentence implies how to narrow results (link_types, direction, limit), which is usable context. But there is no explicit when-to-use statement, no when-not-to-use, and no pointer to a sibling such as search_graph for broader queries.

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

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

Annotations already establish the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's value-add is the disclosure that this is the mandatory first call and an enumeration of what the response contains. With no output schema, spelling out the returned vocabulary is meaningful behavioral context. It omits any note on size, caching, or whether the returned flags are defaults vs. configured values.

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

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

Two sentences, with the imperative 'Call first' front-loaded before the payload inventory. The dense enumeration is efficient rather than padded, and nothing could be cut without losing information.

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

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

For a zero-required-param discovery tool with no output schema, the description adequately covers purpose, ordering, and return contents while annotations cover safety. Minor gap: it never states that the result is static reference data the agent can reuse rather than re-fetch, which would help an agent avoid redundant calls.

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

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

Schema description coverage is 100% and the single 'lang' enum parameter is fully documented in the schema (including its 'default en' note), so the schema already carries the burden. The description says nothing about the lang parameter or its effect on the returned content, leaving it at the baseline for full schema coverage.

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

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

The description names the exact resource set returned: context dimensions, flags (with defaults and rule counts), stages, gates, evidence states and levels, gate outcome precedence, and the suggested workflow. That is far more specific than a generic 'get context' and lets an agent predict the payload. It does not, however, contrast itself against any sibling like when_to_use or explain_node.

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?

'Call first' gives an explicit ordering instruction that positions this as the bootstrap/discovery step before other tools, which is genuine when-to-use guidance. It stops short of naming alternatives or stating when this call is unnecessary, so it is clear context without exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds useful behavioral context the annotations cannot: the approximate output size (6-10k characters) and the composition of the compact envelope (ids by strength, names dictionary, gate evidence for all stages), which helps an agent budget context. It does not describe pagination or error behavior beyond the schema's did_you_mean note.

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?

It is front-loaded with the operating concept but written as one dense paragraph of internal shorthand ('presale to closure', 'ids by strength', 'gate evidence') that an outside agent must decode. No sentence is pure filler, yet the jargon raises cognitive cost disproportionate to the single paragraph's length.

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

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

For a complex, option-heavy planning tool with a nested context object, no output schema, and no required parameters, the description covers the output format and size but never explains the domain vocabulary it relies on (what a 'stage', 'gate', or 'route' actually is). The schema handles parameter detail well, but the core output contract remains underspecified.

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

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

Schema coverage is 100%, so a baseline of 3 applies, but the description genuinely extends the meaning of min_strength='core' beyond the schema's terse default note: it defines what counts as core (context rule, flag or gate-critical artifact), caps it at 8 work items per stage, and gives the producer-selection priority order. That is real added semantics for at least one parameter.

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

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

The description says it will 'Route from presale to closure for a project context', which hints at producing a staged project plan, but 'route' is jargon that never resolves into a plain statement of what the tool returns or does. It names no sibling (validate_plan, check_gate, when_to_use) to disambiguate, so an agent must infer the tool's role from the title 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?

It gives real usage guidance on format: default compact, and 'ask for one stage with stages:[...] and format:full' to get reasons and avoid texts. That is genuine when-to-use encoded at the option level. However it offers no guidance on when to call this tool rather than validate_plan, check_gate, or when_to_use, nor any prerequisites.

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

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

Annotations already declare this a safe read (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add behavioral nuance — and it does: stem-based matching and small-typo tolerance, plus return shape. It does not mention pagination, ranking, or anything about how 'best matches' are ordered.

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

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

Two tight sentences, front-loaded with what is searchable and immediately followed by the return shape. No filler or restatement of the name.

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

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

There is no output schema, so the brief 'returns total and the best matches' partially covers return values, and language behavior is addressed. Gaps remain around the type enum, the limit/pagination semantics, and routing relative to siblings, making it adequate but incomplete for a 4-param search tool.

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

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

Schema coverage is only 25%, so only lang is documented structurally, and the description does imply language handling (English and Russian). But the 14-value type enum and the limit bound are unexplained in both schema and description, leaving the two most behavior-shaping params 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 (search) and clearly scopes what is searched (names, ids, descriptions, aliases) in two languages. It does not, however, differentiate itself from potential siblings like explain_node or when_to_use, so an agent still has to infer positioning.

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, when-not-to-use, or alternative tool is mentioned. The agent gets no signal about whether to reach for search_graph versus explain_node, when_to_use, or list_context when looking up graph concepts.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds substantial detail beyond that, listing specific error and warning conditions, 'shadow start' rules, and what 'expected' means. It does not describe return formatting or performance, keeping it from a 5.

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

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

The description is dense but front-loads its purpose and uses clear 'Errors:' and 'Warnings:' groupings. It is longer than typical, with some parenthetical interruptions, but every clause contributes relevant validation 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 complex validation tool with no output schema and a rich nested context parameter, the description thoroughly covers step validation but never explains how the context object (e.g., size, physical, high_stakes) alters the rules. The schema descriptions partially compensate, but the description alone leaves an important gap.

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

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

Schema description coverage is 75%, so the baseline is 3. The description clarifies what the steps parameter should contain (stages, gates, events, etc.) and mentions the evidence concept via 'expected', but it does not explain the lang or context parameters, leaving the schema to carry most of that burden.

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

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

The description states a specific verb (Checks) and resource (an ordered list of steps), and enumerates the step types it validates. It is clearly distinguishable from siblings like check_gate or check_mix, though it does not explicitly name alternatives.

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 implied: an agent can infer this tool validates a plan. However, there is no explicit guidance on when to use it versus alternatives, no prerequisites, and no exclusions.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive, openWorldHint=false), so the bar is lower. With no output schema present, the description usefully discloses the response payload — verdict, strength and rationale, alternatives with group advice, risks, and required gates — which the agent could not otherwise infer.

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 dense sentence that front-loads the subject ('For one ... item') before listing outputs. It is long but every clause earns its place by naming a distinct part of the answer; only the item-type enumeration is slightly 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?

For a read-only tool with no output schema, the description enumerates the return contents and the possible verdicts, and the schema fully documents the nested context. Nothing critical is missing for correct invocation, though the tool's relationship to siblings like check_gate and explain_node is left to inference.

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

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

Schema description coverage is 100% with three parameters, including the deeply documented nested context object, so the schema already carries the parameter semantics. The description only echoes 'this context' without adding format, defaults, or examples beyond what the schema provides, making the baseline 3 correct.

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

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

States a specific action (evaluate whether one item fits a context) and enumerates the item types it covers (event, practice, technique, notation, tool, artifact, antipattern) plus the verdict vocabulary (fits/avoid/not_applicable/antipattern). An agent can tell it apart from validate_plan or check_gate, though the sibling differentiation is implicit rather than explicit.

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

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

The 'For one ... item' framing implies the per-item scope and 'which gates require it' hints at the relationship to check_gate, but there is no explicit statement of when to choose this over explain_node, search_graph or check_mix, and no exclusions or prerequisites are given.

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