kin

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the response is one row per dependent with id, name, kind, file and referenced lines, and it is deliberately one-hop rather than transitive. It does not discuss ordering, pagination, or the case of zero dependents, which keeps it below a 5.

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

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

Two sentences plus a routing clause, all front-loaded: the capability comes first, the scope constraint and alternative follow. No filler sentences and each clause carries information the agent needs.

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

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

There is no output schema, so the description carries the return-shape burden and does so by naming the per-row fields. Combined with the one-hop scope statement and the sibling routing, an agent has everything needed to call this correctly against a deep sibling 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 100%, so all four parameters (query, entity_id, max_chars, relation_kinds) are already documented in structured form. The description's mention of callers/importers/references loosely maps to relation_kinds but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

Names a specific verb and resource (find who depends on one entity) and enumerates the exact scope: direct callers, importers, references, one row per dependent. It also distinguishes itself from trace_data_flow by declaring one-hop semantics, so an agent can tell it apart from siblings 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?

Explicitly states the selection condition ('Call it for one hop') and names the alternative ('For a whole chain, use trace_data_flow'), giving an unambiguous when-to-use vs when-to-use-something-else rule.

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/closed-world, so the safety profile is covered. The description adds substantive behavior beyond that: the output is a token-bounded bundle containing focal bodies, dependency signatures, and connecting routes, which tells the agent this is a lossy, budget-constrained aggregation rather than an exhaustive dump.

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, and the primary capability is front-loaded ahead of the routing advice. Every clause carries information about what is produced or when to call it.

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 covers return composition and truncation behavior ('token-bounded'), and it explains the alternative it supersedes. Minor gaps remain around how the budget interacts with the two overlapping budget parameters, though that detail lives in the 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 100%, including the anyOf branching requirement and per-field docs for depth, entities, question, entity_id, max_chars, and token_budget. The description restates the three input modes in prose but adds no format, default, or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ('Assemble') and a specific artifact ('token-bounded bundle'), and enumerates the three input modes (one entity, several entities, a plain-language question). It also names the sibling it replaces (get_entity_source plus traversal reads), so an agent can route without opening the schema.

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

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

Explicitly says 'Call it instead of several get_entity_source and traversal reads', giving both a trigger (multiple related reads) and named alternatives. It lacks an explicit exclusion (e.g. when a single direct read is preferable), so it stops short of the full when/when-not bar.

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, closed-world behavior, so the safety profile is covered. The description adds genuine value beyond that by clarifying the return payload is the full owned body rather than a truncated snippet. It omits behavior for a missing/invalid id and any size or rate 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?

Two short sentences, both earning their place: the first states the action and return scope, the second states the usage condition and contrast. Nothing is padded or 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 no output schema, the description carries the burden of describing the return value and does so ('exact graph-owned body', 'real source text'). One parameter plus full annotation coverage keeps this nearly complete; only error behavior for absent entities is unaddressed.

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 a single entity_id parameter, so the schema already documents the input. The description's 'by id' adds no syntax, format, or lookup semantics beyond the schema's 'Entity UUID.' Baseline 3 applies.

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

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

Specific verb (return) plus a precisely scoped resource: one entity's exact graph-owned body addressed by id. It also implicitly distinguishes itself from the snippet-returning search siblings (semantic_search, semantic_locate) by emphasizing 'exact' and 'real source text, not a snippet.'

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

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

Gives a clear triggering condition — 'when you hold an id' — and a contrast case ('need the real source text, not a snippet'), which routes the agent away from search tools. It stops short of naming a specific sibling alternative or stating when not to use it.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description usefully spends its words on the return shape: "summaries with ids" with a chosen depth. This adds real value since there is no output schema. It stops short of describing truncation behavior, but the schema's max_chars/elisions entry covers that.

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 the core purpose front-loaded and routing to siblings at the end. Every clause earns its place; nothing 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?

For a read-only orientation tool with full schema coverage and annotations covering safety, the description supplies the purpose, return character, and sibling disambiguation. Nothing critical is missing, though it leaves pagination/truncation handling entirely to schema fields rather than noting 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?

Schema description coverage is 100%, so depth, limit, direction, entity_id, and max_chars are already documented. The description reinforces depth ("to a depth you choose") and the summarized output but adds no syntax or format beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (get) and resource (an entity's dependencies and dependents), with scope modifiers: traversal depth and summarized-with-ids output. It explicitly distinguishes itself from find_references and trace_data_flow, so an agent can select it without opening the schema.

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

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

"Call it to orient in unfamiliar code" gives the when, and the next sentence names two alternatives with the conditions that select them (callers only vs. an ordered path). Both usage and exclusion are explicit.

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 destructiveHint=false, so the safety profile is covered. The description adds a scope statement ('across the whole repository') and the transitive nature of the walk, but says nothing about result size handling, the elisions mechanism, or performance characteristics. With annotations doing the heavy lifting, this is adequate 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?

Two tightly packed sentences with the purpose front-loaded and the operational instructions following. No filler and no redundancy.

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

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

For a 6-parameter, all-optional read tool with no output schema, the description covers purpose, trigger timing, scope, and targeting-mode exclusivity, which is most of what an agent needs. It leaves the max_chars/elisions contract and the deprecation of the files parameter to the schema, which is acceptable.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds one genuinely useful constraint not in the schema — that targeting modes are mutually exclusive ('one way at a time') — but it omits max_chars and lists 'file paths' as a live targeting mode even though the schema marks files as deprecated in favor of entity_ids.

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

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

The description states a concrete verb and resource — 'walk the graph from a change to every entity it could affect' — which conveys transitive impact traversal rather than a single-hop lookup. It does not explicitly name or contrast with siblings like find_references or graph_neighborhood, so the agent must infer the distinction from the tool 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?

'Call it before editing, across the whole repository' gives a clear situational trigger and scope. 'Target it one way at a time' adds a usage constraint on combining targeting modes, but no alternative tool or when-not-to-use condition is named.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine scope context (Dockerfiles, lockfiles, config, assets, symlinks are included) but says nothing about pagination behavior, default limits, or what happens with a large repo.

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, zero filler, with the core scope (tracked files at one change) front-loaded and the disambiguation clause second.

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 listing tool with full annotation coverage and no output schema, the description tells the agent what is returned (all tracked files, code and non-code) and when to use it. Only pagination semantics and the default 'current branch head' behavior for omitted source_change_id go unaddressed.

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 33% – source_change_id is documented, but limit and offset are not. The description's 'at one semantic change' hints at source_change_id but adds no detail on the limit/offset paging parameters, so the gap is only partially compensated.

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

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

States a specific verb (List) and resource (repository's tracked files) scoped to one semantic change, and explicitly distinguishes itself from the parser-based sibling by saying 'not what the parsers turned into entities.' An agent can separate this from list_file_entities without opening either schema.

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

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

Provides a clear usage rule – call it 'for what the repository contains' rather than entity output – which implicitly routes the agent away from list_file_entities. There is no explicit when-not condition or named alternative, but the context is unambiguous for this repo-listing 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds a genuine behavioral fact beyond that: content is returned as text when valid UTF-8, else base64. Auth/rate-limit behavior is still unspecified, but the return-encoding trait is real added context.

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 zero filler; the core purpose and the return-format caveat are front-loaded ahead of the usage hint. 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?

No output schema, so the description usefully explains the return form (text vs base64) and the identification modes. With read-only annotations and 75% schema coverage, this is largely sufficient, though it could clarify what happens when neither identifier resolves.

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% and the schema already documents path, include_bytes, and source_change_id. The description restates the artifact_id-or-path alternative identity, which mirrors the anyOf constraint rather than extending it; no extra syntax or defaulting detail for include_bytes is added.

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 (one tracked file's exact content) and specifies the two identification modes. It further distinguishes itself from entity-source siblings by scoping to 'a file the parsers made no entities for', so an agent can tell it apart from get_entity_source.

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 when-to-use criteria: 'Call it for a file the parsers made no entities for, which a locate hit's artifact_path means.' This ties invocation to the output of semantic_locate. It does not name the complementary tool (get_entity_source) for the opposite case, so no full when-not 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description goes beyond them by disclosing the semantics of the `sampling=last_settled_selected_graph` value and that a reading can be aged and reported as `stale` — genuine behavioral context about freshness that the annotations cannot express.

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 compact sentences: what it returns, when to call it, and how to read the sampling value. Front-loaded with the payload, no filler. The final sentence is jargon-dense and could be parsed only by a reader already familiar with the vocabulary, costing it a point.

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 burden of describing return content, and it does name the count categories and the sampling/stale semantics. It does not explain how to act on an 'unindexed' backlog or what thresholds matter, leaving a modest gap for a diagnostic 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?

The tool takes zero parameters, so there is no parameter surface to document; baseline 4 applies. The description instead spends its words on interpreting the returned sampling field, which is the only semantically load-bearing token in the call.

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

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

The description names the resource (the resolved graph) and the concrete payload: entity and relation counts plus embedded/pending/unindexed breakdown. That distinguishes it from search- and mutation-oriented siblings, though the opening phrase 'The graph this call is answered from' is slightly indirect about the fact that this is a status/diagnostic read.

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: 'Call it when a search returns less than you expect.' That is a clear context for reaching for this tool rather than semantic_search or the trace tools. It stops short of naming an alternative diagnostic to compare against, so it is a 4 rather than 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?

With annotations already declaring destructiveHint=true and idempotentHint=true, the description still adds value beyond them: atomicity and all-or-nothing validation before commit, and the fact that transaction begin/commit are managed internally. It does not describe the receipt/return payload or failure rollback semantics, so it stops short of a 5.

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

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

Three sentences, front-loaded with the core verb and resource, no filler. The third sentence ('Provide an operations array with mutation verb and payload') largely restates the required parameter already fully specified in the schema, which costs a point.

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

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

For a destructive batch mutation tool with annotations covering the safety profile and a fully documented schema, the description supplies the missing piece - atomic lifecycle management. It omits what happens on partial validation failure and what the receipt contains, but annotations and schema carry most of the remaining burden.

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 nested operation variants are documented exhaustively in the schema itself. The description only gestures at 'an operations array with mutation verb and payload', which the schema states in far more detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('validate and commit a batch of graph mutations') plus the scope ('in a single call', 'atomically'). The sentence 'Automatically manages transaction begin, validation, and commit' distinguishes it from the sibling tools kin_transaction_begin/stage/commit, so an agent can tell it apart without opening either schema.

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

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

Usage is implied: when you have a batch of mutations, pass an operations array and the tool handles the transaction lifecycle. But it never explicitly says when to prefer this over the manual kin_transaction_begin/stage/commit trio, nor does it state any prerequisite or exclusion. The alternative is only hinted at, not named.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds behavioral substance beyond that by disclosing the actual payload — change count, latest change, approvals, a newest-first page of changes, and recent audit events — which is meaningful since no output schema 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 sentences, front-loaded with the core answer and then the usage cue. Slightly dense in the enumeration but no filler or repetition.

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

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

With no output schema, the description compensates by listing the returned fields, and annotations carry the safety profile, so an agent has enough to invoke it correctly. Only minor gaps remain: no note on what happens with invalid/unknown entity_id or how approval status is represented.

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

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

Schema coverage is 100% and both parameters are documented in the schema (entity_id UUID, limit default/max/min). The description alludes to paging ('a page of changes newest first') but adds no syntax, format, or default information beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb and resource — answering who changed an entity and whether it was approved — and enumerates the data returned. It is clearly a read-only provenance query rather than a mutation or graph traversal, though it does not explicitly name the siblings it supersedes (e.g., kin_artifact_read, impact_analysis).

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 one directive: 'Call it before relying on code whose history matters.' That gives a use context, but there are no exclusions, no prerequisites stated, and no named alternative for cases where history doesn't matter. Usage is implied rather than fully specified.

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=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds 'release what it holds,' which hints at session-state teardown, but says nothing about what specifically gets released, whether in-flight transactions are affected, or error 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?

Two short sentences with the action front-loaded and the trigger condition second; zero filler. Slightly terse for the amount of behavioral surface a session-teardown tool has, 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?

For a single-parameter tool with rich annotations and no output schema, the description covers what it does and when to call it. Minor gap: no note on interaction with sibling session/transaction tools, which the adjacent siblings would suggest is relevant.

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

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

There is a single required parameter (session_id) with 100% schema description coverage, so the schema fully documents it. The description adds no syntax or format detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb+resource ('Close this session') and adds what the action does ('release what it holds'), which is clear enough to distinguish from siblings like kin_session_start or kin_session_heartbeat. It does not explicitly name any sibling, so the differentiation is implicit rather than stated.

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 it when your work is done' gives a genuine trigger condition, so usage is more than merely implied. However there is no when-not guidance and no mention of alternatives (e.g. heartbeats, transaction commit/abort ordering), leaving cross-tool 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 it is not read-only, not idempotent and not destructive, so the safety burden is light. The description adds meaningful behavioral context beyond the annotations: the tool's effect is TTL refresh and the consequence of omission (session lapses), which the structured fields do not convey. It does not specify a recommended interval, which is a minor 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?

Two short sentences, no filler, and the imperative action is front-loaded ahead of the rationale. 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?

For a single-parameter keep-alive tool with no output schema and annotations covering the safety profile, the description supplies enough to call it correctly. A recommended cadence would make it fully complete.

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

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

Schema description coverage is 100% for the single session_id parameter, so the schema already documents the input. The description adds nothing about the parameter itself (e.g. which session's UUID, defaults), so the baseline 3 applies.

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

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

States a specific action ('Keep this session alive') on a specific resource (the session), and clarifies the mechanism (preventing lapse at the idle TTL). An agent can distinguish this from kin_session_start/kin_session_end without opening a schema.

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

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

Gives clear invocation timing ('Call it periodically during long work') and the reason (idle TTL lapse). It doesn't explicitly state when not to call it or name a sibling alternative, but the when-to-use condition 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?

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the agent knows this is a non-idempotent mutation. The description adds useful context that the call should be made once at the start so activity is attributed, but does not disclose what happens if called twice, whether session_id expires, or any auth requirements.

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

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

Two sentences, zero waste. The primary action ('Register this agent...') and return value ('get a session_id') are front-loaded, followed by essential timing 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?

For a session-start tool with 100% schema coverage and an output value (session_id) mentioned in the description, the definition is nearly complete. It covers what the tool does, when to call it, and what it returns, though it omits lifecycle details such as how the session_id relates to kin_session_end or kin_transaction_begin.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema. The description mentions 'who you are, your transport, working directory and capabilities,' which maps to some parameters but adds no syntax, format, or semantic detail beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Register this agent with Kin and get a session_id.' It explicitly lists what is being registered (who you are, transport, working directory, capabilities) and the timing ('once at the start of your work, before any transaction'), which distinguishes it from sibling lifecycle tools like kin_session_heartbeat and kin_session_end.

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 clear when-to-use guidance: 'Call it once at the start of your work, before any transaction.' There is no explicit mention of alternatives or when-not conditions, but the timing and one-time nature of the call are 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so safety is covered structurally. The description adds real value beyond them: it specifies WHAT is destroyed ('everything staged on it') and a state-dependent refusal after the commit fence, which the annotations do not convey.

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

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

Three tight sentences, front-loaded with the core action and effect, followed by usage and a failure boundary. Every clause earns its place with no redundancy.

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

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

No output schema exists, and the description covers action, side effect, and the key failure mode, which is sufficient for a two-parameter transactional tool. The 'fenced' phrasing is slightly terse and could be clearer about the resulting state, keeping it just below a 5.

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%, including the enforce-mode session match caveat, so the description carries no additional parameter burden. It adds nothing beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Abandon an open transaction') plus the scope of effect ('discard everything staged on it'). This clearly distinguishes it from kin_transaction_commit and kin_transaction_stage without the agent needing to open any sibling schema.

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

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

Gives two concrete trigger conditions: deciding against a change, and starting clean after a refusal, which implicitly routes the agent away from commit. It also states a boundary condition (refused once commit has fenced it). It does not explicitly name commit as the alternative, so it falls just 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 non-read-only, non-idempotent, non-destructive behavior, so the description is freed to add the transactional semantics: a transaction_id is returned and mutations are buffered until commit. It does not cover what happens on abort, session expiry, or lock contention, keeping it short of a 5.

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

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

Two compact sentences, front-loaded with the purpose and followed by the commit dependency. Every clause earns its place and nothing is padding.

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 discloses the return value (transaction_id) and the buffering guarantee. It is nearly complete for a 2-param tool, though it omits transaction lifetime/cleanup behavior that an agent would need in edge cases.

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 both session_id and scope documented in the schema itself. The description adds no format, default, or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Open a transaction') and clarifies its role as a staging layer for mutations, which distinguishes it from kin_transaction_stage and kin_transaction_commit. An agent can identify it without opening the schema.

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

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

The sentence 'nothing lands until kin_transaction_commit' implicitly routes to the commit sibling, but there is no explicit when-to-use rule, no mention that kin_transaction_stage is the follow-up call, and no statement of prerequisites (e.g., an active session from kin_session_start). Usage 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the description isn't carrying the safety load. It nonetheless adds real behavioral context beyond them: atomic all-or-nothing landing, the daemon reparse + journal step, and the 'fenced commit' retry-safety nuance.

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 the core action front-loaded, followed by the atomicity guarantee and the retry note. No filler; each clause adds a distinct fact.

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 output schema, the description covers atomicity, idempotent re-send, and journaling, and annotations cover the safety profile. It stops short of stating the prerequisite staging step or failure/rollback reporting, leaving a small 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 100%, so the schema documents all four parameters thoroughly. The description adds only the framing that staged mutations are what gets published; it offers no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource — 'Publish every staged mutation atomically' — and the term 'staged' implicitly anchors it to the stage/commit/abort transaction trio, letting an agent separate it from kin_transaction_stage and kin_transaction_begin 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?

Usage is implied: you commit what has been staged, and 'Re-sending a fenced commit is safe' gives a retry rule. But it never explicitly says when to call this versus kin_transaction_abort, nor states the begin→stage→commit ordering, so the agent must infer the workflow.

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=false, idempotentHint=false and destructiveHint=false, so the mutation profile is partly covered. The description adds genuinely useful behavior beyond that: an 'update' replaces the whole body rather than patching it. It omits the most consequential staging fact, that nothing lands until kin_transaction_commit and can be discarded by kin_transaction_abort. No contradiction with annotations.

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

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

Three short sentences, front-loaded with the operation, then the verb glossary, then the one non-obvious rule plus the pointer to get_entity_source. No padding.

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 transaction-staging tool with no output schema and a large polymorphic operation union, the description covers the verb model but not the lifecycle (commit/abort, atomicity, ordering of operations) or the structured Entity/Relation shape. Adequate, but an agent still has to infer how staged work is applied.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a conceptual verb taxonomy, but it says 'four verbs' while the schema accepts many aliases (replace/overwrite/move/add/upsert) across six operation shapes, including the structured Entity/Relation mutation, none of which the summary mentions. The framing is helpful but incomplete against the schema.

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

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

The first sentence gives a specific verb and resource: stage mutations onto an open transaction. The verb glossary ('create' admits a file, 'update' changes an entity, 'delete' retires one, 'rename' moves one) sharpens what the tool does. It does not explicitly differentiate itself from kin_mutate, which is the obvious sibling it could be confused 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?

The description makes the prerequisite ('an open transaction') explicit and routes one case to a sibling: read with get_entity_source before an 'update'. It stops short of stating when to use this over kin_mutate, or what happens if no transaction is open.

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, destructiveHint=false and a closed world, so the safety profile is covered. The description adds genuinely new behavioral context: it returns the entire set rather than a ranked subset, and it reports a completeness flag, which the agent cannot infer from the annotations alone.

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 short sentences, front-loaded with the action and scope, then the differentiator, then the call trigger. Every clause earns its place and nothing is repeated from the schema or annotations.

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 burden of describing what comes back, and it does so at the right level: the full entity set plus a completeness signal. Pagination fields are covered by the schema, so for a three-parameter read tool this is nearly complete; only the shape of an entity record is left unstated.

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

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

Schema description coverage is 100%, so the schema already documents path, cursor, and page_size with defaults and bounds. The description only echoes the path semantics ('by repo-relative path') and the whole-set framing, adding little syntax or format detail beyond the structured fields — baseline 3 applies.

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

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

The description gives a specific verb and resource ('List every entity the graph holds for one file') and pins the scope to one file keyed by repo-relative path. It also carves out a distinctive property against the retrieval siblings ('the only retrieval tool that says what it left out'), so an agent can separate it from semantic_search, find_references, or graph_neighborhood 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?

It gives one explicit and valuable trigger: 'Call it before concluding a file holds nothing,' which is exactly the failure mode that matters for an exhaustive-listing tool. What's missing is the other half of routing guidance — when to prefer a narrower retrieval sibling instead — but the stated condition is concrete rather than 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds useful non-annotation context: the returned field set (id, name, kind, file, line, signature, score) and the hint to read `ranked_by`. It omits pagination/elision behavior, which the schema carries instead.

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

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

Three tight sentences, front-loaded with the purpose and routing rule before the return fields. Slightly telegraphic in places ('Read `ranked_by`') but no wasted sentences.

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

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

With no output schema, the description compensates by enumerating the returned fields, and it covers usage and the sibling alternative. It is adequate for this tool, though it doesn't explain ranking semantics or paging beyond what the schema states.

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

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

Schema description coverage is 100%, so every parameter is already documented with defaults, bounds, and enums. The description only implies the natural-language query and paging ('plain-language question', 'ranked_by'), adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Find code by a plain-language question') and adds the mechanism ('ranked from the graph'), which distinguishes it from lexical siblings. It explicitly contrasts itself with semantic_search by name, so an agent can route correctly without opening either schema.

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

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

Gives the selecting condition ('when you know what the code does but not its name') and names the alternative tool for the opposite case ('Know the exact name? Use semantic_search'). This is an explicit when/when-not/alternative triad.

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 safety is covered. The description adds the non-obvious behavioral trait that matching is lexical rather than semantic, overriding the misleading tool name — genuinely useful context beyond structured fields, though it says nothing about result shape or truncation 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?

Three short sentences with zero filler. The capability statement is front-loaded, followed by the routing rule and the counter-example, in exactly the order an agent needs them.

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, 5-parameter, no-output-schema tool, the description covers purpose and routing adequately, and the schema explains max_chars/elisions behavior. The only gap is that limit/default result volume and the shape of returned declarations are left entirely to the 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 coverage is 100%, so baseline is 3. The description goes further by enumerating concrete kind values (functions, methods, classes, structs, traits, enums, types, constants), which expands on the schema's terse 'Entity kind filter (function, class, etc.)' and clarifies the 'query' parameter as a name pattern.

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

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

The description gives a specific verb+resource ('Filter declarations by name, kind or language') and enumerates the entity kinds covered. It also preemptively distinguishes itself from the sibling semantic_locate, which matters because the tool's own name ('semantic_search') implies the opposite behavior.

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 states the selecting condition ('Call it when you know what the thing is called'), the exclusion ('It matches names, not meaning'), and names the alternative ('For a description, use semantic_locate'). An agent can route between the two without opening either schema.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is low. The description still adds real semantics not in annotations: it walks call/import edges rather than values through variables, and returns ordered steps rather than an unordered set. It does not describe pagination or clipping behavior beyond the schema's own hints.

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

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

Four short sentences, front-loaded with the action and result, then scope exclusion, then the alternative-tool routing rule. Only minor filler ('Give a focal, a direction and a depth') repeats what the schema enforces.

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, but the description compensates by stating the return shape ('the whole path back, as ordered steps'). With 100% schema coverage and full annotations, the agent has enough to invoke correctly; only edge-case behavior (clipping, response truncation) is left to the 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 100% across all 9 parameters, so the schema already carries the meaning of focal, direction, depth, target, and the char/limit aliases. The description only restates focal/direction/depth without adding format or interaction detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

Specific verb+resource: 'Walk the call chain out from ONE entity and get the whole path back, as ordered steps', with the traversal direction made explicit. It also differentiates itself from a named sibling ('Naming TWO things? Use trace_path'), so an agent can route between the two 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?

It states the required inputs ('Give a focal, a direction and a depth'), names the alternative tool and the condition that selects it (two named entities -> trace_path), and excludes value-flow tracing. That is clear positive and negative guidance, though no other siblings (impact_analysis, graph_neighborhood) are addressed.

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, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavioral guidance — 'Read `found` and `gap` before concluding A never reaches B' — warning that a negative path result may be an artifact. It stops short of describing truncation semantics beyond naming `elisions`, but adds real value over 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?

Five short sentences, front-loaded with the purpose, then the trigger, the argument forms, the output caveat, and the routing alternative. Nothing is padded and the reader gets the essentials first.

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 8-parameter graph traversal with no output schema, the description covers purpose, triggers, alternatives, and how to interpret the key response fields (`found`, `gap`). It names truncation signals (`elisions`) but does not itself explain the response shape, leaving a small gap for a tool with 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 100%, so the schema already documents all eight parameters including the enum direction, file-pinning, depth and char limits. The description's restatement that `from`/`to` take 'a name, an id, or name@file' mirrors the schema rather than extending it, so this lands at the high-coverage baseline.

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: 'Find how one entity reaches another, as ordered hops.' It also discriminates from the nearest sibling by naming trace_data_flow for the single-endpoint case, so an agent can choose between them without opening either schema.

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

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

Gives an explicit trigger ('when your question names TWO things') and an explicit exclusion with the alternative to use instead ('One endpoint? Use trace_data_flow'). The when/when-not/alternative triad is fully present.

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