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

With no annotations the description carries the full burden. It usefully notes it reads 'real PR activity' and compares against a 'last saved review' (implying a prior review must exist), but it never states whether the operation is read-only, what permissions or tenant scoping is needed, or how results are produced.

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 comparison and its output list are front-loaded, followed by a compact use-case clause. It is appropriately sized with no wasted sentences, though the first sentence 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?

No output schema exists, and the description does cover the main return content, which helps. However, it omits the 'tenant' parameter entirely and doesn't clarify the dependency on an existing saved review, leaving gaps for correct invocation.

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

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

Schema coverage is 0% for the single 'tenant' parameter and the description never mentions it, offering no meaning, format, or default explanation. For a tool whose only parameter is undocumented in both schema and prose, the description fails to compensate.

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 (compare) and resources (the graph now vs. the last saved review) and enumerates the concrete outputs: safer/riskier modules, top holder change, pairing-task progress. It is clear what the tool does, though it does not explicitly distinguish itself from the adjacent succession_review 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?

Gives explicit trigger phrases ('what changed since last time', 'did the plan work') that map an intent to this tool. There are no when-not conditions or named alternatives, but the usage context is unambiguous.

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 the important part: 'Dry-run: nothing is posted anywhere' explicitly declares the operation is side-effect-free, which is the key safety fact for a tool that emits patches and issues. It also says each artifact carries graph evidence. Permissions and any limits on reruns are not covered.

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

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

Three tightly packed sentences: artifacts first, then the safety guarantee, then the parameter shortcut. No filler and every clause adds 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?

With no annotations and no output schema, the description usefully enumerates what is produced (CODEOWNERS patch per repo, issue draft per pairing, graph evidence) and confirms nothing is emitted externally. The unexplained tenant parameter is the only real gap for an agent to call this correctly.

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

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

Schema coverage is 0%, so the description must compensate. It explains decision_id well - omitting it selects the latest approved Decision - but tenant is never mentioned and its empty-string default is unexplained, leaving one of two parameters ambiguous.

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 transformation - an approved succession Decision becomes a CODEOWNERS patch per repo and an issue draft per pairing. The concrete output artifacts distinguish it from read-only siblings like succession_review and overview without needing the schema.

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

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

Usage is implied by 'approved succession Decision' and the explicit 'omit decision_id to use the latest approved one' rule, but there is no statement of when to call this versus succession_review or what prerequisites (approval state, credentials) must hold. Adequate but leaves 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the core behavior (fuzzy/semantic matching rather than exact lookup) and the intended call ordering, but says nothing about whether zero, one, or many candidates are returned, how ambiguity is resolved, or what the tenant scoping implies.

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, zero filler, with the core transformation stated first and the call-ordering rule second. Nothing can be cut without losing guidance.

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 and no annotations, so the description is the only source of behavioral detail. For a discovery tool whose results feed other tools, the missing information about return shape (single id vs candidate list) and the undocumented tenant parameter leave the agent guessing about downstream usage.

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 meaningfully explains the `query` parameter's expected content (fuzzy natural-language phrases, with examples), which is more than the bare string type conveys, but the `tenant` parameter is left entirely unexplained 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 (turn) plus resource (fuzzy phrase -> exact module ids), with two concrete examples ('execution plan', 'browser api') that remove ambiguity. It also positions itself against the module-specific siblings by declaring it runs before them, so an agent can separate it from module_risk, risk_scan, etc.

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

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

Gives an explicit trigger ('before any module-specific tool') and an explicit exclusion ('when the user did not give an exact id'), which is real routing guidance. It stops short of naming a particular sibling as the follow-on target or stating what to do if the query is already exact, so it is clear context rather than full alternative selection.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose the ranking logic (orphaned modules and sole-holder modules), which is useful beyond structured data. It stops short of describing permissions, output format, or how tenant scoping affects results.

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, front-loaded with the core ranking definition followed immediately by usage triggers. No filler or redundant 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?

The conceptual framing is complete enough to know what the tool computes, but with no output schema, no annotations, and two undocumented parameters, the agent lacks detail on result shape and parameter effects. Adequate but with clear gaps.

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

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

Schema coverage is 0% and the description is silent on both 'limit' and 'tenant'. The names plus defaults make them partly guessable, but the description does not define what tenant does or what unit limit controls, 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 the resource (people) and the ranking criterion (orphaned modules, sole-holder modules), which is a specific analytical output rather than a restatement of the name 'keystones'. It distinguishes itself conceptually from siblings like what_if_leaves or successors, though it never explicitly names 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?

It supplies concrete use-case triggers ('who can we not afford to lose', 'single points of failure'), which tells the agent when this tool fits. However it gives no exclusions or contrast with the very similar what_if_leaves sibling, so the agent must infer the boundary.

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 usefully discloses the underlying algorithms (label propagation for clusters, betweenness for brokers), which adds genuine context about how results are derived. It does not, however, state cost, permissions, or that it is a read-only analysis, leaving key traits unstated.

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 the primary resource definition front-loaded followed by usage examples. The parentheticals are compact and the structure is easy to parse, though the phrasing is noun-heavy rather than an explicit verb.

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 no output schema, the description adequately describes the returned artifacts (territories, holders, brokers), which the agent would otherwise lack. It is incomplete on the tenant parameter and on behavioral/permission aspects, but the core analysis is sufficiently explained.

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 'tenant' parameter has 0% schema description coverage and is never mentioned in the description, so nothing is added beyond the bare name. Although 'tenant' is a somewhat self-explanatory scoping concept, its default (empty) and required-status are not explained 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?

The description names the concrete resource it produces: territories (module clusters found by label propagation), who holds each, and brokers (via betweenness). An agent can form a clear mental model of the output. It stops short of naming which sibling it replaces (e.g., find_modules or who_knows), relying on the example phrases for 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?

Explicit example intents are given: 'how is knowledge organised', 'silos', 'who bridges teams', which map directly to user questions. However, there is no when-not guidance and no mention of alternatives such as who_knows or path_between, so the agent must infer the boundaries.

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

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

With no annotations, the description carries the full burden. It discloses the analytical methodology (authored vs reviewed share, contributor activity, PageRank) which is genuinely useful, but says nothing about permissions, cost, rate limits, or that it is a read-only operation. The behavioral profile is partially but not fully covered.

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 packs purpose, component signals, and usage cues without filler. Slightly dense with parentheticals, but every clause earns its place.

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

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

No output schema or annotations exist, so the description must do more legwork. It conveys what signals are analyzed but not how results are shaped or what the tenant scoping does. Adequate for the core intent, incomplete on scoping and return behavior.

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 implies 'module' identifies a single target, but the 'tenant' parameter is never mentioned and its meaning/default is left entirely to inference. Half the parameters remain 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 analysis verb (bus factor and risk tier) on a specific resource (ONE module), and enumerates the constituent signals: authorship/review share, contributor activity, and PageRank load-bearing. The emphatic 'ONE' implicitly contrasts with multi-module siblings like risk_scan and keystones.

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

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

Provides concrete usage triggers via quoted user phrasings ('how risky is X', 'bus factor of X'), which maps intent to tool cleanly. It stops short of naming alternatives or exclusions (e.g., when to prefer risk_scan or who_knows), so it is clear context without explicit 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?

With no annotations, the description carries the full burden. It usefully discloses that this is a persistent memory write, that links require exact ids, and that content must be graph-grounded, but it says nothing about permissions, whether writes are append-only or deduplicated, or how tenant scoping affects visibility.

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, zero waste, with the core action and its linking requirement front-loaded and the content-fidelity constraint placed last as a qualifier. Nothing is 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 mutation tool with no annotations, no output schema, and 0% parameter coverage, the description is too thin. It omits the role of tenant, the shape of any returned identifier, and safety/visibility context an agent needs before writing to shared memory.

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 is the only source of meaning. It partially compensates by clarifying 'text' (a short finding) and 'about' (people/module ids, exact), but the 'tenant' parameter is entirely unmentioned in both schema and description, leaving a required-capable 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 and resource: save a finding to memory, with the linking target named (people/modules by exact id). It is clear what the tool does and how it differs in kind from the read-only analysis siblings, but it never names or contrasts with its natural counterpart, recall, so an agent must infer the write/read pairing.

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?

Implies the usage context (record findings produced by graph analysis) and constrains content with 'Only write what the graph showed,' but gives no explicit when-to-use, no prerequisites, and no routing to or from recall. Guidance is 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.

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 usefully discloses the return payload (counts plus an as-of freshness date), but never states that this is a read-only, side-effect-free operation, nor anything about tenant scoping or cost. For a read-only summary tool the risk is low, but the disclosure is incomplete.

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: the content list first, then the routing rule. Zero filler and the most decision-relevant information (what you get) is front-loaded.

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

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

With no output schema, the description does a decent job enumerating returned fields, and with no annotations the read-only nature is at least implied by 'size and freshness.' However, the sole parameter goes unexplained and there is no statement of side-effect profile, leaving a meaningful gap for a tool the agent is told to call first.

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

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

There is one parameter, 'tenant', with a default of empty string and 0% schema description coverage. The description never mentions tenant, so an agent cannot tell whether omitting it means 'all tenants', 'the caller's default tenant', or something else. With a param present and undocumented, the baseline-4 zero-param case does not apply.

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 resource (the graph) and enumerates exactly what the tool reports: people, active people, tracked modules, merged PRs, and the data as-of date. It reads as a metadata/summary tool and is clearly distinct from the analytical siblings (risk_scan, path_between, who_knows), though it never states a crisp verb like 'summarize'.

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

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

It gives an explicit routing rule: 'Call first when unsure what is in the graph.' That is real when-to-use guidance and positions it as the entry-point tool. It does not name any alternative or a when-not-to-use condition, 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?

No annotations are supplied, so the description carries the full behavioral burden. It names an internal algorithm ('algo.SPpaths') but doesn't disclose return shape, what 'weighted' means, whether the search needs a tenant context, or performance/limit behavior. Only the implicit read-only nature of 'path between' is conveyed.

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 the core purpose front-loaded and zero filler. The parenthetical algorithm reference is the only slightly expendable token.

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 pathfinding query with no annotations, no output schema, and 0% parameter coverage, the description should explain at least the return concept and the tenant parameter. It leaves the agent without enough to call the tool confidently on anything but the simplest two-arg case.

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

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

Schema description coverage is 0%, so the description should compensate. It clarifies that the two endpoints (a, b) are people or modules, which adds real meaning, but the third parameter 'tenant' is never mentioned and no input format or typing guidance is given for any 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?

States a specific computed resource ('weighted shortest chain of shared knowledge') and its domain (two people, or a person and a module), which is more than a tautology. It doesn't explicitly contrast with path/knowledge siblings such as who_knows, knowledge_map, or successors, so an agent must infer the 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?

The phrase "Use for 'how is X connected to Y'" gives an implied usage context, which is better than nothing. However there are no when-not conditions, no prerequisite guidance, and no routing versus the many connectivity-oriented siblings.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the content returned (findings, decisions, open tasks, notes about module holders) but omits whether this is read-only, any permission requirements, or result-size/limit behavior. Adequate but leaves real behavioral gaps for an annotation-free 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?

Two sentences, front-loaded with the core purpose and content types, then the timing advice. Dense but no wasted filler; the parenthetical content list earns its space.

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-param tool with no annotations and no output schema, the description explains what comes back but not the parameters or result format. It covers the 'why/when' well but leaves the 'what arguments/returns' side under-specified.

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 all three parameters (limit, tenant, subject). The description implicitly maps 'subject' to a person or module but never defines limit or tenant, nor explains syntax. With zero schema help the description should compensate far more than it does.

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

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

The description states a concrete retrieval purpose — surfacing findings, decisions, and open tasks from earlier sessions about a person or module — which is a specific verb+resource. It is reasonably distinguishable from write siblings like note_finding, though it never names a sibling tool to sharpen the boundary. The abstract name 'recall' is rescued by the parenthetical content list.

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

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

It gives explicit timing guidance ('Call BEFORE planning') and states the rationale (avoid repeating or contradicting earlier work), which is strong context. However, it provides no when-not guidance and does not name alternatives (e.g., knowledge_map, who_knows) that an agent might confuse it with.

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

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

With no annotations, the description carries full behavioral burden. It discloses the output shape (a ranking plus tier counts), which is useful, but says nothing about cost, scan scope, pagination, or permissions.

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: the ranking/counting behavior is front-loaded, followed by trigger examples. No filler.

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

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

Covers purpose and output semantics adequately for a small two-param tool, but with no output schema, no annotations, and 0% param coverage, the meaning of limit and tenant is left entirely 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 0% and both parameters (limit, tenant) are undocumented in the schema. The description does not explain whether 'limit' caps the ranked list or the scan scope, nor what 'tenant' filters.

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 (rank), resource (every tracked module), and the risk scale (critical/high/medium/low) plus tier counting. The scope word 'every' distinguishes it from the per-module sibling module_risk, but no sibling is named 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?

Provides three concrete natural-language trigger phrasings ('what is most at risk', 'where are we fragile', 'orphaned code') that map intent to the tool. No explicit exclusions or contrast with siblings like module_risk or keystones.

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 substantial work: it discloses the three-role architecture, that roles coordinate through graph state and forks, and crucially that the tool Writes memory and produces a Decision and Tasks. It omits cost/latency/reversibility and whether the memory write is idempotent, but the mutation behavior is clearly 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?

Front-loads the purpose, then the architecture, then the usage trigger. The parenthetical breakdown of the three roles is dense but each clause adds distinguishing information. Only mild bloat from the architecturally detailed middle section.

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

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

For a complex, multi-role, memory-writing orchestrator with no annotations and no output schema, the description covers purpose, process, and side effects well, but leaves the tenant parameter undocumented and says nothing about expected outputs, duration, or failure modes. Adequate but with clear gaps.

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

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

Schema coverage is 0%, so the description must compensate for both parameters. It clarifies that 'person' is a single person, but the 'tenant' parameter is never mentioned at all, and no format, default behavior, or scoping semantics are given for either. Half the parameters remain semantically undefined.

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 ('Full succession review for one person') and immediately differentiates itself from siblings by describing itself as an orchestrated multi-role workflow rather than a single primitive like successors or what_if_leaves. An agent can distinguish it from the individual analysis tools without opening a schema.

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

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

Provides explicit trigger phrases ('make a plan for X', 'succession plan') that map intent to this tool. It does not, however, name when NOT to use it or explicitly route the agent to siblings (successors, what_if_leaves, draft_actions) for smaller-scope requests, so the alternative-selection guidance is left 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?

No annotations are provided, so the description carries the full burden. It usefully discloses how results are derived – multi-hop over PR reviews and modules that change together – which helps the agent interpret output confidence. But it says nothing about read-only semantics, tenant scoping effects on results, or performance characteristics.

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

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

Front-loads the core question before the mechanism, then usage examples. Three compact sentences with no filler, though the parenthetical '(or one module)' is slightly awkward.

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 annotations, so the description is the only source of guidance. It covers the use case well but is thin on parameter meaning and result semantics, leaving an agent to guess at tenant scoping and result cardinality.

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 4 parameters at 0% schema description coverage, the description must compensate. It hints at 'person' and 'module' via 'a person's modules (or one module)', but leaves 'limit' and 'tenant' completely unexplained, which is significant given multi-tenancy appears to be a real concern.

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 analytical question – identifying successors who could take over a person's modules – and clarifies the mechanism (PR reviewers, co-changing adjacent modules). It implicitly distinguishes itself from siblings like who_knows and keystones via the 'multi-hop' framing, though it never names them outright.

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 trigger phrases: 'who can step in for X' and 'who should we pair with X', which map cleanly to agent intents. It stops short of naming when NOT to use it or which sibling to prefer when the question is simpler (e.g. who_knows for pure knowledge lookup).

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, and it discharges it well: it discloses the execution mechanism (GRAPH.COPY fork, before/after diff) and the safety guarantee that the live graph is untouched. That is exactly the kind of side-effect and isolation information an agent needs before invoking an analysis tool, beyond what any structured field provides.

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

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

Two sentences, zero filler, with the question the tool answers front-loaded ahead of the implementation detail and the usage trigger. 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?

For a two-parameter analysis tool with no output schema, the description covers purpose, mechanism, safety, and usage trigger well. It stops short of indicating the shape of the result (ranked list of modules? fragility scores?) and leaves the tenant parameter unexplained, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 0% and there are two parameters. The description only alludes to the required 'person' parameter ('if this person left') without stating accepted format (name, ID, email), and the 'tenant' parameter is never mentioned at all. With no schema-level documentation or enums to lean on, this is a real 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 operation (counterfactual removal simulation) and a concrete output (which modules become orphaned or fragile), which is distinct from siblings like module_risk or keystones that measure current-state risk rather than a hypothetical departure. An agent can differentiate this from the rest of the toolset without opening any schema.

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

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

It gives an explicit trigger: 'Use for "what if X leaves/quits/goes on leave"', which is a clear usage cue. However, it never names an alternative tool (e.g. module_risk or keystones) or states when a static risk tool would be preferable to this simulation, so the routing is helpful but not 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?

With no annotations the description carries the full burden, and it does disclose useful behavior: the return contents (authored/reviewed counts, recency) and the empty-case sentinel "not_in_graph". It does not address permissions, cost, or whether the underlying graph may be stale.

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

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

Three tight sentences with no filler: purpose first, then usage triggers, then the empty-result caveat. Every sentence earns its place.

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

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

No output schema and no annotations, but the description covers purpose, usage, return fields, and the no-match case, which is enough for an agent to call it. The notable gap is the undocumented limit/tenant parameters.

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 indirectly clarifies "topic" (module or area) but says nothing about "limit" (default 6) or "tenant", leaving two of three parameters undocumented 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+resource: it identifies who holds knowledge for a module/area and enumerates the returned fields (authored/reviewed counts, recency). This is concrete, though it does not explicitly differentiate itself from near-siblings like knowledge_map or keystones.

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?

"Use for 'who knows about X', 'who owns X'" gives clear trigger phrasings, so an agent can recognize the intent quickly. It offers no when-not guidance or named alternatives among the many sibling graph tools.

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