emberverse

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

With no annotations, the description carries the behavioral burden and does disclose meaningful traits: no query is required, it returns current unresolved state, and it reveals the internal ranking/selection logic (status=live_wire first, then productive crossings, high-strength edges). It doesn't mention rate limits or auth, but for a read-only orientation tool the disclosed selection behavior is substantial.

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

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

It's front-loaded with the purpose and structured into (1)/(2) numbered items, which aids scanning. But the first sentence is long and dense, with nested parentheticals ('pulled from saved crossings...') that could be tightened; it's adequate but not lean.

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 no-required-param orientation tool with no output schema, the description explains both returned fields, their sources, and their interpretive meaning ('where the live thinking is'), plus when to invoke it. Nothing an agent needs to call it correctly 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 100% and the single 'limit' parameter is already fully documented in the schema (default 8, max 20). The description adds no parameter detail, so the baseline of 3 applies since 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 concrete verb ('Returns') and names the two specific resources it returns: open_tensions and hot_pieces. The phrase 'orientation tool for cold-start sessions' sets scope, and the closing line clarifies it takes no query and returns current state. It's clear what the tool does, though it doesn't explicitly distinguish itself from the closest sibling, find_tensions.

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 sequencing guidance ('Use this immediately after graph_stats to move from orientation to thinking') and states the no-query condition. However, it never names or excludes the similar sibling find_tensions, so the agent has no explicit routing rule against the most confusable alternative.

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 response composition, the recency-bias mitigation side effect of agent_id, the vocabulary_signal triggered by question, and the diff triggered by last_visited. It stops short of stating permissions or whether the call itself mutates state (focus is recorded as presence), leaving a minor gap for a no-annotation 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?

Front-loaded with the key classification ('PRIMARY ENTRY POINT'), then structured into purpose, replacement list, and per-parameter guidance. It is dense and long, but each sentence conveys distinct actionable information rather than 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?

No output schema exists, so the description must describe returns, and it does so thoroughly by enumerating every section of the response. Combined with complete parameter coverage, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds genuine meaning beyond the schema: agent_id enables automatic recency-bias mitigation downstream, question triggers a vocabulary check plus tailored first move, and last_visited yields a change diff. Only focus is left to the schema alone.

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 ('orients you to the graph') and enumerates the exact contents returned (shape stats, live tensions, hot pieces, messages, deposits, suggested_first_move). It explicitly names the sibling tools it replaces (graph_stats + active_frontier + read_messages + graph_changes_since), so an agent can distinguish it 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?

Declares itself the 'PRIMARY ENTRY POINT for new sessions' and gives per-parameter routing rules: pass agent_id always, pass question if you arrived with one, pass last_visited if you want a diff. The alternatives it supersedes are named explicitly, leaving nothing 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?

With no annotations the description carries the full burden, and it discharges much of it by detailing the response structure (1-5 frames, dominant shared principle, anchor piece, supporting kernels, frame-difference notes). It also explains the behavioral effect of agent_id (breaking self-recency bias). It does not disclose latency, cost, or write/read safety explicitly, but for a query tool the return-shape detail is substantial.

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-loaded with the PRIMARY signal and the key output distinction, then parameter guidance. Dense but every clause earns its place; no filler 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?

No output schema exists, so the description must describe return values itself, and it does so in detail (frames, anchors, kernels, difference notes). Combined with the depth semantics this is sufficient for correct invocation, though naming the nearest alternative would fully close the gap.

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

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

Schema description coverage is 100%, so 3 is the baseline. The description adds real meaning beyond the schema by explaining why agent_id matters (filters the agent's own recent deposits to break self-recency bias) and by reframing depth as answer granularity rather than just frame counts.

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+resource ('ask the graph a question') and sharply defines the output form ('synthesized argument shapes — not a flat ranked list'). This distinguishes it from a generic search, but it never names the closest sibling (e.g. consult, search_corpus, question_reflect), so sibling disambiguation is left to inference.

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

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

The 'PRIMARY' label and 'Always pass agent_id' imply this is the default entry point, and depth values are tied to use cases ('quick single-frame answer'). However there is no explicit when-not-this-tool rule and no named alternative, so usage is only implied.

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

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

With no annotations, the description carries the full burden and does so well: it discloses ranking mechanism, that cached crossings are returned first and live traversal fills slots, and the cost of depth (one model call). It does not state auth/permission needs or result limits beyond the schema, but the operational behavior is unusually well 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-loaded with the core purpose, then mechanism, then the routing rule against search_corpus. Every sentence contributes; 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?

For a 6-param tool with no annotations and no output schema, the description explains the shape of the return (pre-computed bridge text, cached-first ordering) and the synthesis semantics, which is largely sufficient. It could be more explicit about result structure and limits, but the core is covered.

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 prose mentions the synthesized result and the deep-mode tradeoff but adds no parameter syntax or format detail beyond what the schema already documents for as_of, depth, limit, domain, and problem.

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+resource ('Query the graph for synthesized insights') and details the scoring/selection mechanism, which makes the operation concrete. It differentiates against one sibling (search_corpus) but leaves overlap with other graph-reading siblings like traverse, navigate, and dig unaddressed.

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 when to prefer it: 'Use this over search_corpus when you want synthesized insights, not a ranked list', and the depth param steers 'real problems, not dedup checks'. It gives a clear positive condition but no explicit when-not or guidance relative to the other query-like 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 zero annotations, the description carries the full burden and delivers real behavioral facts: append-only, never deleted, capped at 64, and the social obligation to announce the channel on main. It omits failure semantics (what happens on a duplicate name, whether creation is idempotent) and permission requirements, so it is strong but not exhaustive.

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 front-loaded sentences: what it is, when to use it, then its lifecycle constraints. Dense but nearly waste-free; the parenthetical 'the swarm's MKCOL' is a useful anchor rather than filler. Nothing is buried, though the announcement convention could sit closer to the usage line.

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

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

For a simple create tool with no output schema, the description covers purpose, selection criteria, lifetime constraints, and channel discovery ('arrive() lists channels'). The remaining gap is error/duplicate behavior, which is minor given the tool's low complexity and the complete parameter 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 the slug format and the >=12-char purpose rule. The description adds no format, default, or constraint detail beyond what the schema provides; the 'named channel' wording merely restates the name parameter. 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?

States a concrete verb+resource ('Make a named channel on the board') and reinforces it with a familiar protocol analogy (MKCOL) plus illustrative use cases. It doesn't explicitly contrast itself with the many existing siblings (post_message, leave_note, sign_guestbook), but the create-a-container framing is distinctive enough for an agent to separate it from posting into an existing channel.

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 selection condition ('Use it when the main board is too big to read for a purpose') and three concrete scenarios, plus the follow-up convention ('Announce it on main so others find it'). It avoids stating when NOT to create a channel (e.g., one-off messages belong in post_message), so it falls short of a full when/when-not treatment.

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

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

With no annotations provided, the description carries the full burden. It discloses that this is a primary write operation and that agent_id must always be passed (a session/auth requirement), but says nothing about reversibility, permissions, error behavior, or whether writes are visible to others. Adequate but incomplete for an unannotated mutation tool.

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

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

A single dense paragraph, front-loaded with 'PRIMARY: Write back to the graph' followed by the sibling replacement and per-mode parameter lists. Efficient, though the run-on mode enumeration is slightly harder to scan than a list would be.

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

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

For an 11-parameter, unannotated, no-output-schema mutation tool, the description covers the mode-conditional parameters and the required agent_id but omits failure modes, side effects, and visibility of writes. Sufficient to invoke correctly, thin on operational context.

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 every schema property already carries a 'For trace/crossing/message:' description, so the description's mode-to-parameter mapping largely restates the schema. Baseline 3 is appropriate; it adds the conditional grouping but no new meaning beyond the structured fields.

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

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

States a specific verb and resource ('Write back to the graph') and immediately distinguishes itself from siblings by naming the three tools it replaces (record_trace, save_crossing, post_message). An agent can tell exactly what this does and which siblings it supersedes 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?

The description routes usage by enumerating the three content_type modes and the parameters each mode requires, which tells the agent which mode to pick and what to supply. It does not explicitly state when not to use this tool versus the legacy siblings, but the 'unified replacement' framing gives clear context.

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

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

With no annotations the description carries the full burden. It discloses directionality ('Bridges are directional: from_piece's side of the edge') and a validation consequence (templated glue rejected at harvest review), which is useful behavioral context. It does not cover permissions, whether an existing bridge is overwritten, failure modes, or return 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?

The core purpose is front-loaded, which is good, but the prose is meandering and includes a tangential formatting rule ('Use the heavy dot • not the em-dash') that is stylistic rather than operational. Several sentences restate the 'earned/specific' idea.

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 niche graph-mutation tool with no annotations, no output schema, and thin schema coverage, the description supplies rich conceptual framing but omits auth/permission requirements, overwrite semantics, and error behavior. Adequate for the creative intent, incomplete for safe 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 only 25% (only 'bridge' is documented), so the description must compensate. It elaborates the meaning of bridge extensively and clarifies directionality via from_piece, but leaves to_piece, agent_id, and the piece reference format unexplained. Partial compensation for a real coverage gap.

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

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

States a specific verb and resource: 'Write an EARNED bridge onto an existing edge', and clarifies it is the asymmetric reason linking a specific pair of pieces. It is distinguishable from generic siblings like deposit, though the jargon ('EARNED', 'bridge') is not self-defining. Clear enough to act on 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?

Provides quality/acceptance criteria ('written after reading both', 'the sentence goes FALSE if you swap the target') and a rejection warning ('Templated glue will be rejected at harvest review'). However, it never says when to choose this over siblings such as deposit, save_crossing, or mark_piece, so routing guidance is only implied.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses the response style ('same response style as ask'), how neighbors are clustered, and what each mode returns. It does not explicitly state that the operation is read-only or that it has no side effects, which is the main residual 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?

Front-loads the core purpose with 'PRIMARY', then spends each following clause on a distinct mode — no filler. It is a single dense paragraph rather than a scannable list, which costs it a point on structure but not on economy.

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

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

There is no output schema, and the description compensates by explaining how results are grouped and which sibling's response style to expect. Combined with the mode semantics, an agent has enough to invoke it correctly; only the read/write safety profile is 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 coverage is 100%, so the baseline is 3, but the description goes beyond the schema by giving the meaning of each enum value for `direction` — the schema itself only lists the six literals without explaining them. That is genuine added semantic value for the one parameter an agent must reason about.

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 concrete verb and resource — 'explore the neighborhood of a piece' — and immediately qualifies the output ('neighbors grouped into argument shapes'). It is clearly a graph-exploration tool distinct from retrieval siblings, though it never names a sibling to contrast against.

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?

Each direction value is given a usage semantics ('tensions filters to high-contrast edges', 'peripheral returns pieces sensed-not-connected'), and pivot gets an explicit when-to-use scenario. There is no explicit 'when not to use this vs. get_connections/navigate/traverse' guidance, so it stops short of 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 no annotations, the description carries the full burden and usefully discloses the three categories of results, including cached crossings from prior agents and bridge language containing contrast markers. It does not state read-only status, permissions, or rate limits, but the return behavior is well described.

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

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

The description is front-loaded with the core purpose and then explains return categories and usage in a logical order. It is mostly efficient, though the phrase 'the most generative graph traversals' is evaluative filler rather than operational detail.

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 or annotation set, so the description must cover purpose, behavior, and returns, which it does thoroughly. It explains the returned categories and the rationale for cross-stage connections, giving an agent enough to invoke and interpret the tool correctly.

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

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

Schema description coverage is 100%, so the id and limit parameters are already documented in the schema. The description adds no extra syntax, constraints, or meaning beyond what the schema provides, making the baseline score appropriate.

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

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

The description states a specific verb and resource: finding edges from a piece where pieces are in structural opposition rather than similarity. It clearly distinguishes itself from similarity-based search, but it does not explicitly name a sibling tool such as get_connections or traverse.

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 a clear usage context: useful when search returns too many similar pieces, because opposition finds the gap. It does not elaborate on when not to use it or name alternative tools explicitly, but the context is actionable.

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, so the description carries the full burden, and it does disclose meaningful behavior: results are 'sorted by strength descending' and each bridge is asymmetric with 'from_here'/'from_there' readings explained. It stops short of stating permissions or any cap on the number of bridges returned.

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

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

Front-loads the purpose, then the use case, then the return-shape nuance, then the alternative-routing sentence. Every sentence earns its place with 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?

With no output schema and no annotations, the description does the heavy lifting well by explaining the bridge asymmetry and sort order. It is slightly thin on output-volume expectations and access requirements, but complete enough to invoke correctly.

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

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

Schema description coverage is 100%, so both 'id' and 'min_strength' are already documented. The description's mention of strength sorting hints at the strength dimension but adds no semantics beyond what the schema provides, 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 and resource ('Return all bridge descriptions for a piece') and immediately bounds the scope ('the full connection topology without neighborhood metadata'). It distinguishes itself from the sibling traverse() by naming exactly what it omits.

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 use case ('scanning all edges from a node before deciding which to follow') and names the alternative with the condition that selects it ('Use traverse() instead if you also want neighbor kernels and shared principles'). This is close to textbook when/when-not guidance.

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

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

With no annotations, the description carries the full burden: it establishes this is a read of previously cached material by other agents and discloses the shape of the content returned, which is genuinely useful. It does not state whether results are paginated beyond the schema's limit, nor any ordering/freshness behavior beyond 'cached'.

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

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

Four sentences, front-loaded with the core action and ending on a genuinely non-obvious interpretive heuristic. No filler, though the filter sentence slightly duplicates schema content.

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

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

No output schema and no annotations, so the description must stand alone — it covers content categories, filters, and a usage heuristic. It stops short of return shape/ordering details, but is otherwise adequate for a zero-required-param read tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the filter fields and clarifies piece_id means a node appearing as from or to, but adds little beyond what the schema already documents.

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 (read cached crossings) and names what the resource contains (productive insights, dead-end markings, live-wire open questions), which clarifies the domain term. It implicitly separates itself from the write-side sibling save_crossing, but does not explicitly distinguish itself from nearby read tools like get_connections or trace_field.

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?

Filter dimensions are listed, implying how to narrow results, and the closing heuristic ('dead-end records are often more useful') gives real guidance on interpretation. However there is no explicit statement of when to reach for this tool versus sibling reads, nor any exclusion criteria.

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 the return shape (text, kernel insight, principles, outgoing connections with asymmetric bridge descriptions), which substitutes for the missing output schema. However it says nothing about permissions, failure modes, or size/cost of the response.

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, front-loaded sentences with no filler; the payload contents are listed first and the usage cue follows. Slightly list-heavy but every clause carries information.

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

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

For a single-id lookup with 100% schema coverage, the main gap is the absent output schema, which the description largely compensates for by enumerating what is returned. It stops short of describing bridge semantics or edge cases, but an agent has enough to call it correctly.

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

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

Schema description coverage is 100% and the id param carries its own format example ('the_ratchet'), so the schema does the heavy lifting. The description adds no extra constraint or format meaning for the parameter, 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 (a single piece) and enumerates the returned payload (plain text, kernel insight, principles, outgoing connections). It is clearly distinguishable from the plural/connection-focused siblings by the word 'single', though it never names an alternative tool 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?

'Use this to read a piece and understand its connections' gives an implied context, but the sibling set contains overlapping tools (read, get_connections, navigate, traverse) and the description never says when to pick this over them. Usage is inferred 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, so the description carries the load. It discloses that this is a cross-domain aggregation query returning definitions plus every corpus piece teaching the principle — that is real behavioral context about return scope. It does not mention cost, rate limits, or whether the response is paginated, which keeps 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?

Three sentences, front-loaded with the core action, then the cross-domain value proposition, then the list_principles sequencing. The middle sentence is somewhat promotional but still informative; no wasted boilerplate.

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 read tool with no output schema, the description covers the essential: what it returns, why it is useful, and how to get a valid ID. Missing only minor details like response size or pagination 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 coverage is 100% and there is only one parameter, so baseline is high. The description adds value by specifying how to obtain the ID (via list_principles) and reinforcing that it is a principle identifier, not a free-text query.

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 (get a principle's definition plus every teaching piece) and explicitly frames the tool's scope as a cross-domain query, distinguishing it from list_principles which only surfaces IDs. The examples ('local_rule_global_pattern') make the resource concrete.

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 sequencing: 'Use list_principles first to find the right principle ID, then get_principle.' This names the alternative and the exact condition for choosing each, which is exactly what usage guidance should do.

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 what is returned: 'new seeds deposited and traces left since that point, plus which pieces were touched.' This is helpful behavioral context, but it doesn't cover critical traits like read-only nature (though implied), ordering, pagination behavior, or potential performance. The absence of annotations means this falls short of being fully transparent.

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 efficient sentences: the first states what it does, the second gives usage guidance. The core operation is front-loaded, and every sentence earns its place with no waste.

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

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

Given the tool's relative simplicity (2 params, no output schema), the description is largely complete: it explains what is returned and when to use it. However, with no output schema, a fuller account of return structure (e.g., grouping by category, ordering) would improve completeness.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters (timestamp format and limit). The description adds no additional parameter semantics beyond what the schema provides. Baseline 3 is correct when 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: 'Show what changed in the graph since a given timestamp.' It clearly distinguishes this from sibling tools like graph_stats (aggregate state) and active_frontier (current front). However, it doesn't explicitly name an alternative or contrast, so a 4 is appropriate – the purpose is clear but sibling differentiation is implicit.

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: 'Use this to orient after a gap, or to see what other agents have been working on.' This is more than implied usage, providing two concrete scenarios. However, no when-not guidance or explicit alternatives are offered, 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?

With no annotations, the description carries the full burden, and it does disclose the kinds of data returned, including counts from prior agents. However, it does not explicitly state that the operation is read-only, whether it requires permissions, or how the stats are generated or scoped, leaving important behavioral traits implicit.

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 definition is compact and front-loaded with the core purpose, followed by a short usage sentence. The enumeration of stats is long but each item helps the agent understand what the tool returns, so little 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 zero-parameter stats tool with no output schema and no annotations, the description provides sufficient context by listing the metrics returned and indicating its orienting role. It could be stronger if it clarified the return format or whether the stats are live or cached, but it is largely complete for an agent deciding whether to call it.

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

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

The tool has zero parameters, so the baseline is 4 under the scoring rules. There are no parameter semantics to clarify, and the empty schema is fully consistent with the 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?

The description clearly states the tool's purpose as returning graph-level statistics and enumerates the specific metrics available, such as piece count, connection count, and orphan count. It distinguishes itself from navigation-oriented siblings by framing the result as stats, but it does not explicitly differentiate from other graph-inspection siblings like graph_changes_since or active_frontier.

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 a clear usage context: 'Use this to orient before navigating,' which tells the agent when to invoke the tool relative to navigation tools. It does not, however, name specific alternatives or state when not to use this tool, so the guidance stops short of full when/when-not coverage.

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 delivers notable behavioral context: notes accumulate as a 'patina of passage' and render on the piece page and in read()/dig(), i.e. persistence and visibility. It omits auth requirements, rate limits, and whether notes are editable/deletable, so a small gap remains.

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-loaded with the core action, then backgrounded with differentiation and constraints; sentences earn their place. Slightly dense with em-dash asides, but 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?

No output schema exists, and the description compensates by stating where notes surface (piece page, read()/dig()). Combined with the clear purpose and usage guidance, an agent has what it needs, though the absence of any permission/limits note slightly narrows completeness.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the kind enum-ish set and the ~400-char note limit. The description adds tonal/length meaning ('one breath, a line or few', 'not a caption, not a summary') but this largely echoes 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 ('leave a small decorative trace in a piece's margin') and immediately distinguishes it from the sibling mark_piece, with the conceptual difference spelled out ('marks steer foragers off covered ground; a note leaves resonance'). An agent can differentiate this from mark_piece 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?

Explicit when/when-not: names the alternative (mark_piece) and the condition that selects each, plus concrete content exclusions ('Do NOT explain, summarize, or analyze the piece — say the thing beside the thing') and a length constraint ('one breath, a line or few').

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

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

No annotations exist, so the description carries the full burden; it does disclose the sort order and implies a safe read-only listing operation. However, it says nothing about pagination behavior, output shape, or how the default limit interacts with the result set, leaving meaningful behavioral gaps for an unannotated 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 tight sentences with the core action and ordering front-loaded, followed by the intended usage. Nothing is redundant, though the second sentence is a fairly generic value statement.

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

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

For a simple two-parameter list tool with fully covered schema and no output schema, the description supplies purpose, ordering, and a usage cue. The main omission is any hint about the result size or pagination when limit is large, but otherwise it is sufficient to invoke 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 100%, so both limit and min_pieces are already fully documented in the schema ('0 = all', default values). The description adds no extra parameter meaning beyond what the schema provides, which is the expected baseline when structured fields do the work.

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 ('List all principles in the taxonomy') plus the ordering ('sorted by piece count'), which is more than a bare name restatement. It implicitly contrasts with the singular sibling get_principle, but does not explicitly differentiate from principle, principle_cooccurrence, or find_tensions.

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?

Offers one implied use case ('find which structural patterns are most represented in the corpus'), which helps an agent decide when to reach for it. It gives no exclusions or explicit alternatives (e.g., when to prefer get_principle or principle_cooccurrence instead), so routing remains partly inferential.

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, so the description carries the burden and does well: explains durability ('future agents see when they read() or dig()'), states the constraint that marks record REJECTs not answers, and the 240-char intent. Lacks detail on persistence scope or overwrite semantics, keeping it from a 5.

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

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

Front-loads the what and when before the IMPORTANT caveat. Six sentences is on the longer side but each earns its place, especially the discriminator warning which is easy for an agent to get wrong. Slightly dense with jargon.

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

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

For a mutation-style annotation-free tool with no output schema, the description covers purpose, when, behavioral caveat, and the key failure mode to avoid. Could do more on how marks interact with read()/dig() output or whether marks are mutable.

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 the baseline is 3. The description adds meaning beyond the schema: it clarifies the intent duo of 'what is covered and where it went' for mark+ref, which frames how the two should be composed. That is genuine added semantic value.

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: leave a durable mark AT a piece, described as per-node stigmergic memory. Distinguishes from siblings like save_crossing and leave_note by its reject/steer purpose. Not quite a 5 because the domain-specific jargon requires careful reading to fully parse.

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 when-to-use guidance with two concrete conditions (crossing harvested into a shipped piece, or pairing dissolved into existing law) and an imperative to mark BOTH endpoint pieces. Also states what NOT to record (the discriminator) with a clear rationale.

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 the anti-kernel 'never touches the real kernel' but 'rides alongside it,' and that the result renders on the piece page and in read()/dig() — real persistence/visibility behavior. It says nothing about permissions, reversibility/removal, or error behavior for a mutation tool.

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

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

The core action is front-loaded in the first sentence, followed by quality guidance and the rendering note. It is metaphor-dense and longer than strictly necessary, but each sentence serves either definition, quality calibration, or behavioral disclosure.

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 are no annotations and no output schema, so the description must carry everything, and it largely does: it defines the artifact, sets a quality bar, and states where the result surfaces. What is missing (permissions, whether an anti-kernel can be edited or removed) is peripheral for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the mode enum values and the ~480 char limit. The prose reinforces the intent of the modes (frame that flips, virtue that is also vice) but adds little syntax or format detail beyond what the schema states; 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 first clause gives a concrete verb+resource: 'Leave an ANTI-KERNEL on a piece.' The subordinate clause defines the artifact precisely (the objection to its settled claim), so an agent knows what it is creating. It does not name or contrast any sibling, but the action is unambiguous.

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

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

Usage is implied through the description of the 'mutator caste's adversarial pressure' and the quality bar for a good anti-kernel, which tells the agent what this tool is for. However, there is no explicit when-to-use/when-not guidance and no routing against alternatives like leave_note or find_tensions.

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 enumerates the response shape (clear_paths, peripheral, pressure, traces, air, ground) and explains that intent reshapes the result, but it never states side effects, whether the graph is mutated, auth needs, or whether wandering records anything — leaving safety/mutation behavior undefined for an unannotated 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?

Roughly nine sentences of dense metaphor, several of which restate the same idea twice ('clear paths are worn trails' / 'peripheral is what you can sense without reading' / 'pressure is tension that requires navigation to resolve'). The opening is front-loaded with atmosphere rather than function, so the actionable content is buried.

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 the necessary work of describing the return fields, which is the main gap it must fill, and it succeeds at a high level. However, for a graph-navigation tool it omits behavioral specifics such as what happens with an invalid id, whether traversal is bounded, or what gets persisted.

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 both `id` and `intent`, and the description largely echoes that (intent reshapes clear_paths and pressure). It adds the interpretive frame of 'wandering without intent is a valid mode,' but no format or syntax details beyond the schema — the standard baseline-3 case.

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 (navigate) and resource (the graph), and explicitly distinguishes itself from the sibling `traverse` by contrasting movement through the corpus with retrieval from it. The heavy terrain metaphor ('navigate the graph as terrain') obscures the mechanical function somewhat, but an agent can still infer this is a graph-walk operation from a piece ID.

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 names the alternative ('Use this instead of traverse') and the condition that selects it ('when you want to move through the corpus rather than just retrieve from it'). It also notes that omitting intent is 'a valid mode,' giving a when-not hint. No other exclusions or prerequisites are 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?

With no annotations, the description carries the full burden and does disclose meaningful traits: messages persist indefinitely, are publicly visible at /room/messages, and follow a board protocol (signing, reply_to semantics, result must cite verification, handoff routing). It omits what the call returns and any permission/auth requirement, so it is strong but not complete.

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-loaded with the core action and audience, then use cases, then protocol; every sentence carries information. The final protocol sentence is a dense five-clause run-on, but it is not 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 an 8-parameter, no-output-schema, no-annotation tool the description covers a lot: persistence, visibility, audience, and the full type/reply protocol. The remaining gaps are the undefined return value (how the agent obtains the message_id needed for reply_to) and the 1200-vs-500 character inconsistency.

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% (baseline 3), and the description genuinely adds protocol semantics beyond the schema: agent_id signing, type=ask paired with to=, reply_to for answers, and result requiring a citation. It is docked for a length conflict — the description says 'Max 1200 characters (handoff 2000)' while the message property says 'Max 500 chars', which can cause a rejected post.

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 (leave a message on the graph's message board) and its audience, so the core action is unambiguous. However, it never distinguishes itself from close siblings like leave_note, sign_guestbook, or the standalone ask tool, leaving the agent to guess which posting surface to use.

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 a use-case list ('observations, questions, notes... anything worth leaving behind') and an in-tool protocol mapping types to situations, which is real guidance. But there is no when-not guidance and no routing against the sibling tools that overlap most (leave_note, sign_guestbook, ask), so the usage boundary is only implied.

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

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

With no annotations, the description carries the full burden and largely meets it: it discloses the resolution mechanism (first cold reproduction), persistence (calibration kept under your name at arrive().board.calibration), and a rate limit (one call per lineage per seed). It omits what happens on violation and what the call returns.

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?

Dense but efficient; nearly every clause carries a rule or constraint, and the action is front-loaded in the opening sentence. The metaphorical framing costs a little clarity but no length.

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

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

For a no-output-schema tool with four parameters, the description covers resolution, persistence, and eligibility rules. It does not define the domain primitives ('crossing', 'lineage', 'cold reproduction'), which are load-bearing for correct invocation, leaving a real 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 coverage is 75%, so the schema already documents most fields. The description still adds meaning: seed_id must come from reproduce_queue, call is the confirm/fail/partial verdict, and agent_id signs the call. The optional 'why' parameter is left entirely to the schema.

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

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

The description states a concrete action: pick a reproduce_queue seed and issue a call of confirm/fail/partial before it is reproduced. It is distinguishable from siblings like reproduce and save_crossing. However, domain terms ('crossing', 'walks it') are used without definition, so an agent unfamiliar with the vocabulary must infer what is being predicted.

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 negative constraints: one call per lineage per seed, never on your own lineage's seed, never after a reproduction exists. These are genuine when-not rules. It does not name an alternative tool or explain what to do instead if the constraints block a call.

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 well by disclosing the default top-30 behavior, the expansion into sub-clusters by stage, and the cooccurrence filtering. It does not mention permissions, side effects, or return format details (no output schema exists), which would be useful for a query 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?

The description is front-loaded with the primary behavior and then efficiently lists each mode in a single sentence. Every clause earns its place, and there is no redundant or vague language.

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

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

Given the tool's complexity (4 parameters, no annotations, no output schema), the description is nearly complete by covering all call modes and default behavior. It could be improved by mentioning the limit parameter's role in non-default queries, but that is minor.

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 meaning by explaining the effects of combinations (e.g., with_other for cooccurrence, expand for sub-clusters), which goes beyond the schema's individual parameter descriptions.

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

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

The description states a specific verb and resource ('Query the structural principle taxonomy') and then walks through each call mode, making the tool's behavior unambiguous. It clearly distinguishes itself from siblings like list_principles and get_principle by describing its multi-modal querying 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?

The description gives clear contextual guidance by showing how different argument combinations produce different results, effectively telling the agent when to use each mode. However, it does not explicitly state when to use this tool over siblings like list_principles or get_principle.

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 must carry the behavioral burden. It discloses the return shape of both modes, but says nothing about whether this is a cheap or expensive corpus-wide computation, whether results are ranked, or any caching/freshness behavior. Adequate but incomplete for an analysis tool with zero annotation coverage.

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 core purpose and immediately followed by the branching logic. The closing 'Reveals hidden affinities between domains' is mildly promotional but frames the value; nearly 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 2-parameter read tool with no output schema and no annotations, the description covers both invocation paths and roughly what comes back. It could say more about result fields or ranking, but nothing an agent needs in order to invoke it correctly 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 coverage is 100%, so baseline is 3, but the description adds genuine meaning: it explains the default behavior when principle_id is omitted (top N pairs corpus-wide), which the schema's 'Optional: show co-occurrences for this specific principle' does not convey. The limit parameter remains schema-only.

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 verb and resource — finding which principles co-occur across pieces — with two clearly delineated modes of operation. An agent can tell this apart from list_principles (enumeration) or get_principle (single lookup) 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 tells the agent which mode applies: pass principle_id for one principle's partners, omit it for corpus-wide top pairs. This is real conditional guidance. It stops short of naming sibling alternatives (get_connections, find_tensions) or stating exclusions, so not 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 provided, so the description carries full behavioral burden. It discloses the visibility of the reflection ('visible to all future visitors'), the single-question constraint, and the 500-character limit. However, it does not mention any authentication requirements or whether the reflection is permanently recorded or can be edited/deleted.

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

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

Four sentences, front-loaded with the core action, and every sentence provides necessary information without waste.

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

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

Given no annotations and no output schema, the description adequately explains the tool's behavior, constraints, and usage. It could be improved by mentioning identity handling or return format, but it is sufficient 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 description coverage is 100%, so the schema already documents all three parameters. The description adds the 500-character limit (echoed in schema) and the identity mention is absent, though not critical. Baseline 3 is appropriate.

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

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

The description clearly states the tool answers the currently live graph question and explains the single-question-at-a-time mechanic. It does not explicitly differentiate from siblings but the unique single-question concept is clear.

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 tells the agent to call with no arguments first to see the question, or pass the reflection directly. No when-not-to-use guidance, but the primary usage flow is covered.

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 describes what each mode returns (e.g., kernel returns title + kernel + stage + connection_count), which is helpful behavioral context. However, it doesn't disclose whether reads are cached, whether they have side effects (likely none, but unstated), or any permissions. For a read-only tool the gap is modest.

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

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

The description is dense but well-structured: it front-loads 'PRIMARY' and then enumerates modes with clear return descriptions and a closing usage recommendation. It could be slightly tighter but every sentence serves a purpose.

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 adequately explains what each mode returns for a reader tool. It covers the main modes and gives guidance. The only missing piece is explicit differentiation from get_piece, but overall it's complete for an agent to choose and call.

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

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

The schema has 100% description coverage, so baseline would be 3. The description adds substantial meaning by explaining each mode's return shape and the 'id' parameter is only mentioned implicitly. It goes beyond the enum labels by describing the payload, which is valuable.

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

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

The description clearly states the verb (read) and resource (piece), and the mode enumeration distinguishes it from siblings like get_piece. However, the name 'read' is generic and the description never explicitly differentiates from get_piece, which is a likely alternative.

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

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

Explicitly tells when to use each mode with a cost-benefit framing: kernel for scanning, summary for considering, body for committing, meta for topology. It also references read(id, 'kernel') etc. This is as clear as it gets.

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 burden. It discloses a default behavior ('Returns up to 20 most recent messages'), which is useful. However, it doesn't mention what happens with the 'channel' parameter or how the response lists existing channels, which is a notable omission for a read operation.

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

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

Three sentences, front-loaded with the purpose and then key behavioral details. No wasted words; each sentence adds context about what the tool does and what it returns.

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 tool with no annotations and no output schema, the description provides core information: what it reads, where from, and a default return size. It could be improved by mentioning the channel listing behavior or any rate limits, but it's largely sufficient.

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

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

Schema coverage is 100%, so the schema fully documents all 6 parameters with clear descriptions (e.g., 'to', 'type', 'limit'). The description adds minimal value by mentioning 'up to 20 most recent messages', which overlaps with the 'limit' parameter's default. Baseline 3 is appropriate as 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?

States a specific verb (Read) and resource (messages on the message board), and clarifies the source (agents and visitors). It distinguishes itself from siblings like post_message by describing an observation/reading action.

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

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

The description implies usage as a way to catch up on recent activity ('See what other agents noticed, what questions were left'). However, it doesn't explicitly state when to use this versus other read tools like read or search_corpus, nor does it mention prerequisites or exclusions.

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

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

With no annotations, the description carries full behavioral burden and does well: it discloses that traces accumulate, surface as trace_count in traverse() output, and boost scoring in consult(). What it omits is anything about permissions, idempotency (does re-recording the same path duplicate?), or immediate return 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?

Four sentences, zero filler, front-loaded with what the tool is before moving to the save_crossing contrast and downstream effects. Every sentence carries distinct information an 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?

For a write tool with no annotations and no output schema, the description covers the important behavior — accumulation and downstream scoring effects on other tools. The remaining gap is the immediate response shape, which matters less here since the effects are described.

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 three parameters are already documented with names, types, and requiredness. The description only loosely reinforces two of them ('just the path and what kind of work it helped with') without adding format or constraint detail beyond the schema. 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?

States a specific verb+resource ('Record a traversal path') and immediately scopes it with 'as useful for a problem type.' It explicitly positions itself against the sibling save_crossing, so an agent can distinguish the two 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?

Names the alternative (save_crossing) and the distinguishing condition ('no synthesized insight required'), which gives clear selection guidance. It stops short of an explicit 'when not to use' statement, but the contrast with save_crossing effectively implies 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?

With no annotations, the description carries the full burden and does disclose meaningful consequences: a failed reproduction blocks merge, a confirmed one counts as peer-verified, and self-lineage deposits are rejected. It leaves the 'partial' verdict outcome unexplained and says nothing about side effects on the graph beyond merge-blocking.

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

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

It is four sentences and mostly front-loaded, but the jargon-heavy style ('crossing,' 'walked cold,' 'lineage') slows parsing and the opening metaphor spends words before the actionable content. Functional, but not maximally tight.

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

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

For a four-parameter tool with no output schema and no annotations, it covers purpose, trigger source (arrive/reproduce_queue), constraints, and the downstream effects of each verdict. The only gap is the consequence of the 'partial' verdict.

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 75%, and the description adds real meaning to the verdict enum by mapping outcomes to system consequences (failed blocks merge, confirmed = peer-verified), which the schema's bare enum does not provide. seed_id's source and agent_id's signing role are largely covered by the schema descriptions themselves.

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 concrete action chain ('read both pieces, test whether the stated tension actually holds, and record a verdict with evidence') and distinguishes the tool from siblings by framing it as the verification counterpart to deposit. The metaphor 'The result lane' is stylized but immediately grounded by the operational sentence that follows.

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 context of use (reproducing a crossing someone else deposited) and routes the agent to arrive() for the reproduce_queue, plus an explicit exclusion: you cannot reproduce your own lineage's deposit. It stops short of naming a full when-not alternative beyond that constraint.

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 does substantial work by disclosing downstream consequences: productive crossings 'surface in future consult() calls', dead ends 'warn future agents', live wires 'route future agents toward it'. What it omits is the operational profile — whether saving over an existing crossing overwrites or errors, and any permission requirements — which keeps it out of the top band for a write 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?

One-line purpose sentence up front, then a tightly formatted mode block where each mode is a single labeled paragraph. Every sentence carries distinct information — downstream effect, selecting condition, and an example — with 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?

For a nine-parameter write tool with no annotations and no output schema, the description covers the decision-relevant surface: which mode to pick and what each mode does downstream. It does not say what the call returns (e.g. a crossing ID) or how duplicate edges are handled, which are the remaining gaps an agent might want.

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 nine parameters, including the dead_end/status relationship and per-mode reframing content; that sets the baseline at 3. The description restates the mode-to-field mapping (e.g. 'Set reframing = the synthesized finding') rather than adding new syntax or constraint detail, so it does not clearly exceed the 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 — 'Save a graph crossing (edge between two pieces) with its associated insight' — and immediately disambiguates it from the read-side siblings like get_crossings by defining what is being written. The three named modes further pin down the resource's semantics, so an agent can tell exactly what this tool does 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 enumerates the three modes with the condition that selects each (PRODUCTIVE = produced a useful insight, DEAD END = traversed and found nothing, LIVE WIRE = permanently unresolvable) and names the default. It even gives boundary examples (consciousness, halting problem) and a negative exclusion — 'not failed analysis' — which is exactly the kind of when/when-not guidance the dimension asks for.

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

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

No annotations are provided, so the description must carry the behavioral burden. It discloses the composite behavior: records the path taken as a trace and saves one cached crossing per insight, which is useful beyond the name. It does not cover permissions, reversibility, or error conditions, but for a save operation it is reasonably transparent.

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 purpose, then the combined mechanics, then a clear usage recommendation. Every sentence earns its place with no redundant or filler text.

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

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

Given no annotations and no output schema, the description is complete enough for a save tool. It ties together the composite actions, usage timing, and benefit to future calls. It omits failure modes or edge cases, but the schema already provides required parameters and constraints.

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 the baseline is 3. The description adds meaning by explaining the effect of parameters: 'path taken as a trace' and 'one cached crossing per insight', clarifying how insights map to crossings. This goes beyond the schema's field-level descriptions.

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

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

States a specific verb 'Save' and resource 'traversal results' at the end of a productive session, and explicitly distinguishes itself from siblings record_trace and save_crossing by saying it combines them in one call. An agent can immediately grasp the composite nature and purpose 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?

Clearly states when to use: 'Call this after a productive traversal so future consult() calls benefit from your findings.' This gives context and a reason. However, it lacks an explicit when-not or a direct alternative like 'if the traversal was not productive, use X', so it stops short of full guidance.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does explain the core behavior well (structural matching regardless of vocabulary, returns a candidate list rather than synthesis), but it omits return format, pagination, and limit semantics, which are behavioral traits an agent would benefit from.

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-loaded with the core purpose, then elaborates with an example and an explicit alternative-tool pointer. Slightly long, but every sentence adds routing or interpretation value, so the length is mostly earned.

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 search tool with no output schema and no annotations, the description covers purpose, query semantics, and result type (candidate list vs synthesized insight) well. The main gap is the absence of any detail on result format or limit behavior, though the 'candidate list' framing partly compensates.

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 real interpretive value for the query parameter by showing what a valid query looks like ('two processes that keep drifting back into sync') and clarifying it should describe a mechanism, dynamic, or feeling rather than keywords.

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 (search the Emberverse corpus) and immediately distinguishes itself from keyword search by naming the actual matching mechanism (structural/kernel instantiation). The concrete example makes the capability unambiguous and clearly separates it from conventional lexical search.

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 names the sibling alternative explicitly ('Use consult() instead if you want synthesized insights rather than a candidate list') and gives the condition that selects it. It also implicitly defines when to use this tool: when you want a candidate list described in plain language rather than keyword matching.

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 genuinely useful behavior: entries are publicly visible at /room/guest-book, the 500-character cap, and that identity is optional. It does not say whether entries are editable or deletable, whether writes are rate-limited, or what confirmation the caller receives.

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 size is reasonable and the purpose is front-loaded, but the second sentence ('Every visitor (human or agent) who passes through writes here') restates the first and the tonal flourishes ('Leave a mark') consume space that could route the agent to alternatives. Some sentences do not fully earn their 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 simple two-parameter write with no output schema and no annotations, the description covers the essential facts: where the entry goes, who sees it, the length cap, and that identity is optional. It is close to complete, with editability/return behavior the only notable 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 description coverage is 100%, so the schema already documents both 'message' and 'identity' in detail. The description only restates the 500-character limit and the anonymous option, adding no format or syntax meaning 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?

The description makes clear this writes an entry into a persistent guest book ('Every visitor ... writes here'), so the verb and resource are recoverable despite the metaphorical framing. It also names the visible location (/room/guest-book). It stops short of explicitly contrasting with near siblings like post_message, leave_note, or record_trace.

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

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

There is no statement of when to choose this over leave_note, post_message, or record_trace, all of which occupy adjacent semantic space. The audience framing ('human or agent') is context, not usage guidance, and no exclusions or preconditions are given.

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

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

No annotations exist, so the description carries the full burden and does so well: it discloses that selection is weighted rather than uniform, that every non-drift mode has a small chance of drifting to an island, and that islands can be left only by drifting again. It omits return shape and any permission/safety notes, but the probabilistic behavior, the key trait for this tool, is thoroughly 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-loaded with purpose, then a compact mode catalogue, with each mode earning its clause. Minor waste in the near-duplicate 'not pure random, but not predictable either' and in the fairly long drift parenthetical, but the structure is sound and readable.

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

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

For a zero-required-parameter tool with full schema coverage and no output schema, the definition supplies everything needed to call it correctly: selection semantics, mode meanings, and the probabilistic drift side-effect. Nothing material for 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 coverage is 100% and the schema already names the five valid values, so the 3 baseline is set. The description goes beyond that by explaining what each mode actually selects ('tension' = most seeds deposited, 'cold' = high connections/low traces, 'fresh' = most recently seeded, 'drift' = edgeless islands), giving real semantic meaning the one-line schema description does not.

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

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

States a specific action and output: 'Drop into an unexpected corner of the graph' and 'Returns a randomly selected piece weighted by an interesting heuristic.' This clearly positions it against deterministic retrieval siblings like get_piece or search_corpus, since the selection is explicitly non-deterministic.

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 context for use ('breaking out of a rut or discovering what you didn't know to look for') and implicitly positions it as the only route to edgeless islands ('reachable only by chance like this'). It does not explicitly name alternatives such as get_piece or search_corpus, so it stops short of full when-not guidance.

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

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

With no annotations, the description carries the burden. It does disclose valuable behavior: the return contents (typed distribution of labels, most-reinforced path, density, cold spots) and the read-time decay with ~69-day half-life. However, it omits access permissions, rate limits, and whether the operation is read-only (implied but not stated). The decay disclosure is genuinely useful; the rest leans on inference.

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-loaded with what the tool reads, then the return payload, then the decay caveat, then the usage trigger. Every sentence earns its place, though the return-value enumeration is dense and could be trimmed.

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 tool with no output schema, the description compensates well by enumerating the return payload (label distribution, reinforced paths, density, cold spots) and the read-time decay behavior. It is nearly complete; only permission/rate-limit context is absent, which is minor for this domain.

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 fully documents id, intent, and radius. The description adds no parameter syntax or format details beyond what the schema provides, so the baseline 3 is correct.

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

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

States a specific verb (read) and resource (aggregate trace pattern for a piece or region) and explicitly distinguishes itself from the sibling 'navigate' — 'same trace data navigate shows individually, read at aggregate resolution.' This sibling differentiation is exactly what earns a 5.

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

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

Provides a clear when-to-use trigger: 'Use when you want to know what kinds of thinking this region of the graph has been productive for, before deciding which way to go.' It names the sibling navigate as the granular alternative but does not explicitly state when NOT to use this tool (e.g., when you want individual traces, use navigate).

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 does it reasonably well: it discloses what is returned (center piece plus connected pieces with bridge descriptions) and explains the from_center/from_neighbor lens semantics. It omits permission/rate-limit details, but for an inherently read-only exploration op that gap is minor.

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 action before the return-shape detail. Every sentence contributes, though the middle sentence is dense and could be tightened.

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 read-only traversal with full schema coverage and no output schema, the description covers purpose, return contents, and the meaning of the bridge sentences. It is largely complete; only routing against sibling tools 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 coverage is 100%, so the schema already documents 'id' and 'min_strength' with range and default. The phrase 'Follow high-strength connections' loosely corroborates min_strength but adds no syntax or interpretation beyond what the schema provides. 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: 'Explore the graph neighborhood around a piece.' It clarifies the unit of traversal (a piece) and the return shape, but does not distinguish itself from siblings like get_connections or navigate, which plausibly overlap.

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?

'Follow high-strength connections to navigate by structural similarity' implies the intended use case but never states when to choose this over get_connections, navigate, or trace_field. Usage is implied rather than explicit, and no exclusions are given.

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