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

No annotations are provided, so the description carries the full behavioral burden. It does disclose meaningful semantics: the edge type (GROUNDS), that it targets the belief's Beta state, and that it is local positive evidence only. But it omits reversibility, idempotency on repeat calls, permissions, and what happens to the belief on failure — real gaps for a mutation 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?

Three tight sentences that are well front-loaded: action first, constraint second, input sourcing last. No filler or redundancy. Slightly under-sized for the amount of undocumented behavior, but structurally clean.

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

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

With no annotations, no output schema, and 0% schema description coverage, the description should carry more. It explains the edge type but leaves weight semantics, belief_id meaning, idempotency, and reversibility undocumented, which is inadequate for a three-parameter mutation tool.

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

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

Schema coverage is 0%, so the description must compensate for all three parameters. It only clarifies the origin of chunk_id ('from query_document results'); belief_id is unexplained and weight (0-1, default 1) is never described — its meaning as evidence strength or its effect on the Beta update is unstated.

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: 'create a GROUNDS edge from a DocumentChunk to a Belief' and 'adds local positive evidence to the belief Beta state'. It also clarifies what it is not ('never becomes a causal or belief-to-belief edge'), which partially distinguishes it from record_cause. It does not explicitly name the closest sibling (record_support), so sibling differentiation is incomplete.

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 one concrete usage hint — 'Get chunk_id from query_document results' — establishing a prerequisite and data source. However, it does not say when to use this versus record_support, record_contradiction, or record_cause, nor any when-not conditions. Usage is implied rather than spelled out.

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

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

No annotations are present, so the description carries the full disclosure burden. It usefully states the effect (removing chunks and embeddings), the return shape ({"cleared": N}), and idempotency (no-op if never loaded), but it omits permissions, reversibility, and whether the source document itself is affected.

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

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

Three short sentences, purpose front-loaded, no wasted words. The return snippet and no-op note are directly useful.

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 one-parameter tool with no annotations or output schema, the description covers the operation, return value, and idempotency. It could be more complete by noting destructiveness/reversibility or path format, but the essentials are present.

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

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

Schema description coverage is 0%, so the description must compensate. It identifies the parameter as a 'document path', which adds some semantic meaning beyond the bare string, but gives no format, examples, or resolution rules. Partial compensation.

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 (remove) and resource (all chunks and embeddings for a given document path). The purpose is unambiguous and distinct from sibling document tools like load_document/query_document, but it does not explicitly name or differentiate against them, so it stops short of a 5.

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

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

No when-to-use guidance, no alternatives, no prerequisites. The only conditional is a no-op edge case, which is behavioral rather than usage guidance. An agent is left to infer that this is the cleanup/removal tool.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does disclose the mutation target (beliefs) and the return shape (updated count), but says nothing about reversibility, permission requirements, or side effects of decaying beliefs, which an agent running a batch mutation would want.

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

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

Two short sentences with the core action front-loaded and no filler. The second sentence largely duplicates the schema's project description, which is a minor redundancy but not bloat.

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 batch mutation with no annotations and no output schema, the description covers what changes and what is returned. However, it omits the mathematical effect of decay_factor and any warning about modifying many beliefs at once, leaving 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 coverage is 50%: project is fully documented in the schema (and the description merely repeats it), while decay_factor has no explanation anywhere. The description fails to compensate for the gap, e.g., it never explains what decay_factor does or that 1 means no decay.

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

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

The description names a specific verb+resource ('Apply time decay to beliefs') and states the return value (count of updated beliefs). It is clear what the tool does, though it never explicitly contrasts itself with the closest sibling, sweep_expired_defeated, so an agent must still infer which sweep applies.

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 explains the scoping behavior of the optional project argument but gives no guidance on when to call this tool versus alternatives in the belief-maintenance family (e.g., sweep_expired_defeated). There are no exclusions, prerequisites, or timing cues, leaving usage entirely inferred.

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 cascade behavior (edges are deleted too) and the not-found outcome via the return value. It omits irreversibility, required permissions, and any warning that edge removal may affect dependent beliefs.

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

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

Two short sentences, front-loaded with the action and scope, with the second covering outcomes. 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 one-parameter delete tool with no annotations and no output schema, the description covers the core action, its cascade side effect, and both return cases. It still lacks permission/irreversibility context, which would be expected for a destructive operation.

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

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

Schema coverage is 0% for the single 'id' string parameter, so the description must compensate. 'By ID' communicates that the argument selects the belief to remove, but gives no format, uniqueness, or sourcing guidance beyond what the name implies.

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 ('Delete a belief') plus the cascade scope ('and all its edges by ID'). An agent can distinguish it from get_belief/insert_belief by verb, though no sibling is explicitly named for contrast.

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

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

No when-to-use context, prerequisites, or alternatives are given. The cascading edge deletion hints at a destructive scope but doesn't tell the agent when this tool is appropriate versus other deletion tools like delete_pattern or delete_project.

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 and usefully discloses the cascade behavior ('all its edges') and both possible return values. It does not state irreversibility, permissions, or error behavior, but the key destructive effect is 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 tightly written sentences, front-loaded with the action and scope, with no redundant or filler 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?

For a simple one-parameter deletion tool with no output schema, the description covers the action, cascade side effect, and return values. It is nearly complete, though it omits permission or irreversibility 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 coverage is 0%, so the description must compensate; saying 'by ID' identifies the required parameter as the pattern identifier. It still does not specify ID format or constraints, so it adds only moderate 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?

The description states a specific verb and resource ('Delete a pattern') plus scope ('and all its edges by ID'), which clearly distinguishes it from siblings like delete_belief, delete_project, and insert_pattern.

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 operation implies when to use it—when deleting a pattern by ID—but it does not explicitly say when to choose it over alternatives or mention any exclusions or prerequisites.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the cascade ('along with their edges'), which is meaningful destructive context, but says nothing about reversibility, permissions, or what happens when no beliefs match the tag. This is a genuinely helpful disclosure on an otherwise under-specified destructive bulk 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?

Two tight sentences with no filler; the destructive scope and cascade are front-loaded before the usage hint.

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

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

For a destructive bulk delete with no annotations and no output schema, the description covers the action and cascade but leaves return behavior, idempotency, and failure modes unaddressed. Adequate but with clear gaps for a high-impact operation.

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

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

Schema description coverage is 0%, so the single 'project' param is undocumented structurally. The phrase 'tagged with a project name' implies the param is a project tag/name, adding some meaning, but it omits matching semantics (exact vs partial) and format.

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 ('Delete') and resource ('all beliefs tagged with a project name, along with their edges'), and the bulk-by-project scope implicitly distinguishes it from the single-item delete_belief/delete_pattern siblings. It stops short of naming those siblings explicitly, so differentiation is inferable rather than stated.

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

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

Provides a clear condition for use: 'to forget project-specific knowledge when a project is complete.' This gives good context, but it names no alternative (e.g. delete_belief for single-belief removal) and offers no exclusion for when NOT to use it.

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

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

With no annotations, the description carries full behavioral burden. It does disclose a meaningful trait—that results include superseded judgments and their rationale—which tells the agent this returns history rather than current state. It says nothing about pagination, ordering, or authorization, and only implies read-only behavior via the word 'Inspect'.

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

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

A single dense sentence with the core scope ('immutable experience and review versions') front-loaded and the clarifying detail trailing. 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 one-parameter lookup with no output schema, the description covers the nature of the returned data (historical, superseded, with rationale) but leaves the identifier's meaning and the result shape unstated. Adequate but not fully self-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 0%, so the description must compensate for the single 'id' parameter, and it does not. It never states whether 'id' is an experience id, a review id, or something else, despite the sibling set containing both experience and review concepts.

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 ('Inspect') and resource ('experience and review versions') and clarifies the scope as historical, including superseded judgments. However, it does not differentiate itself from siblings like get_experience or pending_experiences, so an agent must infer the distinction from the wording alone.

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

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

No when-to-use guidance and no named alternative. The presence of get_experience, pending_experiences, and review_experience in the sibling list makes the absence of routing advice a real gap—the agent is left to guess which tool returns current vs historical state.

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

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

With no annotations, the description carries the full burden. It discloses the return surface (provenance edges + a bounded page of active reviews) and that paging applies, but omits whether the call is read-only, what 'active' means, and any auth/permission expectations.

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

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

Three tight sentences, front-loaded with what is inspected, then follow-up routing, then a scope caveat. Little waste, though the final sentence is a clarification rather than new actionable 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?

There is no output schema and no annotations, so the description must carry everything, and it documents the return concept reasonably well. But it leaves all three parameters undocumented despite 0% schema coverage, a meaningful gap for an agent deciding how 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?

Schema description coverage is 0% across three parameters. The description only weakly compensates: 'the belief's' implies id is a belief, and 'bounded page' hints at limit/offset paging, but the max-of-20 limit, offset semantics, and id format go unexplained.

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

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

States a specific verb (inspect) plus concrete resources: the belief's incoming reasoning edges and a bounded page of active evidence-backed reviews. It clearly distinguishes itself from the bare get_belief sibling by naming what it returns and explicitly scope-limits to provenance, not causal identification.

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 downstream routing ('Follow experience_id with get_experience or experience_history') and a scope exclusion ('not causal identification'), which tells the agent what this tool is not for. It does not, however, explicitly state when to pick this over get_belief or record_cause.

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 discloses nothing beyond what the verb implies. It does not say whether a missing ID returns null, an empty result, or an error, nor whether the read is free of side effects.

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

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

A single short sentence with the action and scope front-loaded and no filler. It is appropriately terse for a one-parameter lookup, though the brevity leaves nothing to structure.

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 trivial single-item fetch the description is minimally sufficient, but with no annotations, no output schema, and a rich sibling set it should have said something about failure behavior and how it relates to explain_belief or list_beliefs.

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

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

Schema coverage is 0% and the single parameter is documented only as an untyped string. The phrase 'by ID' clarifies that the value identifies a belief rather than a project or pattern, but no format, source, or lookup behavior is given, so the description does not compensate for the coverage gap.

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

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

States a specific verb (get) and resource (belief) scoped to a single retrieval by ID, which separates it from list_beliefs. However it does not distinguish itself from likely-overlapping siblings such as explain_belief or get_evidence beyond the resource name.

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

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

No guidance on when to retrieve a belief directly versus using list_beliefs, explain_belief, or query_relevant. Nothing is said about prerequisites or what to do when the ID is unknown.

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 discloses one non-obvious semantic rule (untagged/global beliefs count as in-scope) and implies read-only behavior via 'Find', but it never defines 'actively contradicting' (e.g. whether defeated contradictions are excluded) and says nothing about result volume, ordering, or cost.

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

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

Two short sentences, with the core action front-loaded before the parameter caveat. The second sentence is slightly redundant with the schema's own parameter description, which keeps it out of 5 territory.

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 optional-parameter query tool with no output schema and no annotations, the description covers what is being looked for and how scoping works, but leaves the return shape (list of belief pairs? with what fields?) and the definition of 'active' unexplained.

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 schema already spells out the 'tagged with this project or untagged' rule and the omit-to-consider-everything behavior. The description largely restates that rule ('both beliefs visible in that project's scope'), adding only slight framing, 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 ('Find all actively contradicting belief pairs'), which cleanly separates it from the write-side sibling record_contradiction and from get_belief. It does not explicitly name an alternative tool or define what 'actively' excludes, so it stops short of a 5.

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

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

The description explains the effect of supplying project, which implies when to narrow results, but gives no explicit when-to-use/when-not-to-use guidance versus siblings like query_relevant or explain_belief. Usage is inferable 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?

With no annotations, the description carries the behavioral burden. It usefully discloses that the result is document passages, that they correspond to GROUNDS edges, and that they are ordered strongest first, but it does not cover permissions, error behavior, or what happens when no evidence exists.

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

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

The description is a single front-loaded sentence with no wasted words. It puts the purpose and ordering behavior immediately in view.

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 one-parameter read tool with no output schema and no annotations, the description covers the essential purpose and ordering but leaves the return shape and failure/empty cases unspecified.

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

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

Schema coverage is 0% and the sole parameter belief_id is undocumented in the schema. The description contextualizes belief_id as the belief whose grounding evidence is returned, which is helpful, but it does not specify ID format or additional semantics.

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

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

The description uses a specific verb ('Return') and resource ('document passages grounding a belief'), and clarifies the underlying relation ('GROUNDS edges'). It distinguishes itself from belief-detail tools like get_belief, though it does not explicitly name a sibling 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?

It implies the tool is used when evidence for a belief is needed, but it gives no explicit when-to-use guidance, no when-not-to-use guidance, and does not mention alternatives such as get_belief or query_relevant.

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

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

With no annotations, the description carries the full burden. It does disclose a meaningful behavioral trait: the returned revision tokens enable concurrency-safe correction, hinting the tool is a read-only fetch paired with a versioned update. It still omits whether this is strictly read-only, what permissions are needed, and what happens for a stale id.

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

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

One compact sentence with the tool's core action front-loaded. It earns its length, though the trailing 'revision tokens for safe correction or review' clause is terse enough to be ambiguous rather than merely brief.

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

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

For a simple single-param getter this is borderline adequate, and the revision-token mention adds useful context. But with no output schema and no annotations, the description should still specify the id's meaning and roughly what the response contains; both are left to inference.

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

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

Schema description coverage is 0% and the single required 'id' (uuid) parameter is never mentioned in the description at all. There is no statement of what the id identifies, whether it is an experience id or a belief id, or how revision tokens relate to it, so the parameter is entirely undocumented.

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

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

The description pairs a specific verb ('Inspect') with the resource ('experience') and notes it returns revision tokens, so the basic purpose is legible. However, it never distinguishes itself from close siblings like review_experience, experience_history, or pending_experiences, and 'revision tokens' is unexplained jargon an agent must infer.

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

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

The phrase 'for safe correction or review' implies a usage context (fetch state before mutating), which is more than nothing. But it gives no explicit when-to-use rule, no prerequisites, and does not name or contrast with the obvious alternatives review_experience or experience_history.

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

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

No annotations are supplied, so the description carries the full behavioral burden. It usefully discloses that provenance is required and persisted, which is real behavioral context. However, it says nothing about permissions, idempotency/duplicate handling, or what an add returns, leaving meaningful gaps for a mutation 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?

Three sentences, front-loaded with the core action before the provenance requirement and the routing caveat. Every sentence is doing work, though the third sentence is dense and jargon-heavy ('standalone prior plus review feedback would count one incident twice').

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

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

For a 6-parameter tool with a nested provenance object and no annotations or output schema, the description covers purpose, provenance duty, and sibling routing but omits meaning for several scalar parameters and any dedup/return behavior. Adequate to call correctly in the common case, incomplete around the edges.

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 50%, so half the parameters rely on the description. The description clarifies provenance semantics (must cite an independent source, not an experience) and the persistence implication, adding value beyond the enum. But it says nothing about probability, confidence, or content semantics, so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource ('Add a belief') and narrows the scope to sources grounded in an explicit user instruction or document. It also differentiates itself from the incident-derived path by naming record_experience and review_experience, so an agent can route without opening another schema. It does not distinguish itself from pattern-related siblings like insert_pattern, but the core 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?

Provides a clear when-to-use (independent user instruction/document) and a when-not-to-use with named alternatives ('Incident-derived conclusions must use record_experience and review_experience candidates'). The double-counting warning reinforces the boundary condition. Lacks a positive prerequisite checklist, but the routing guidance is explicit.

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

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

With no annotations, the description carries the full behavioral burden and discloses nothing: no persistence/dedup behavior, no permission requirements, no mention of the success_rate range constraint or what happens on duplicate patterns. A one-line mutation description with zero annotation coverage leaves the agent with no behavioral model.

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 a single front-loaded sentence, so there is no padding, but the brevity reflects under-specification rather than economy. The one sentence provided does not earn its place by adding information beyond the name.

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

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

A write tool with 3 required, undocumented parameters, no annotations, and no output schema. The description omits the return value, error behavior, and the semantics of the required fields — nothing an agent needs in order to call this correctly is present.

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

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

Schema description coverage is 0% across 4 parameters, and the description supplies no meaning for situation, approach, success_rate, or project. Key ambiguities — whether project is a link or a label, whether success_rate is a probability or a count — are unresolved in both schema and prose.

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?

"Add a new pattern to the graph" is essentially the tool name reworded: insert_pattern → add a pattern. It adds only the vague notion of "the graph" and does nothing to distinguish this from siblings like insert_belief, insert_experience, or delete_pattern. No indication of what a "pattern" is in this system.

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

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

No when-to-use guidance, no prerequisites, no alternatives. The agent gets no signal about when a pattern should be inserted versus a belief or an experience, nor whether the referenced project must already exist. Completely silent on routing.

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

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

With no annotations, the description carries the full burden, and it does disclose the two distinct return modes (legacy full array vs paged object) and oldest-first ordering — valuable behavioral context. It stops short of describing permissions, error conditions, or the concurrency caveats that the memory_type param hints at.

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

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

Three tight sentences, front-loaded with the core action and scope, then the paging modes. Every sentence carries meaning, though the project sentence overlaps the schema description.

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 list tool with 100% parameter coverage and no output schema, the description supplies the key missing piece — the dual array-vs-paged return behavior. It is adequate, with only minor gaps around auth and error conditions.

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

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

Schema coverage is 100%, so the schema already documents all four parameters, including the project and paging semantics. The description largely restates the project and limit/offset behavior rather than adding syntax or edge-case meaning beyond what the schema provides, so baseline 3 applies.

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

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

The opening verb+resource 'List beliefs' is unambiguous and the following sentences define the listing scope (project-filtered vs everything). It does not explicitly differentiate from siblings like get_belief or query_relevant, so it stops short of a 5.

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

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

It gives real contextual guidance for the parameters — 'omit to list everything', and 'use limit and offset for bounded, oldest-first pages'. However it never names an alternative tool or states when to prefer this over get_belief/query_relevant, so usage is implied rather than routed.

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 does add one genuinely useful non-obvious behavior: a project scope also includes untagged (global) patterns. However, it omits pagination, result size/ordering, or any other operational behavior an agent might need.

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

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

Two sentences, zero waste, with the core purpose front-loaded and the scoping rule following immediately. Every clause earns its place.

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

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

For a single optional-parameter, read-style list tool with no output schema and no annotations, the description covers the essential scoping semantics. It is largely sufficient, with return format/pagination the only notable omission.

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 single 'project' parameter fully. The description merely restates that same semantics, adding no syntax, format, or example beyond the structured field, which is the 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+resource ('List patterns') that an agent can map directly to the tool's function. It does not, however, distinguish itself from sibling listing/query tools such as list_beliefs or query_relevant, leaving the selection ambiguous.

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 explains what the 'project' argument does but never says when to call this tool versus alternatives like query_relevant or list_beliefs. There is no when-to-use/when-not-to-use guidance, only parameter behavior.

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 meaningful work: it discloses upsert semantics ("Replaces existing chunks for the same path on reload") and an environment prerequisite. It stops short of authority requirements, failure behavior, or return shape, but the mutation profile is well conveyed.

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

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

Three short sentences, each earning its place: operation, replacement behavior, and prerequisite. The core action is front-loaded with zero 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 two-parameter tool with no output schema and no annotations, the description covers the action, the idempotency/replacement semantics, and the config requirement well. Minor gaps remain around permissions and failure modes, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so both parameters are already fully documented in the schema, including the delete_project tie-in. The description adds no syntax, format, or constraint detail beyond that, so the baseline 3 applies.

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

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

The description gives a precise verb chain (parse, embed, index) and a clear resource (markdown file), specifically describing the indexing operation. It is functionally distinct from siblings like query_document and clear_document, but it never names them, so the differentiation must be inferred.

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 a real prerequisite ("Requires [embeddings] in config.toml") and implies the reload/upsert use case, which is useful guidance. However, it gives no explicit when-to-use vs. when-not, and never routes the agent to query_document, clear_document, or delete_project.

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 notably well: it discloses that successful review removes that exact version, failed/stale submissions persist, deferred IDs may be filtered, an empty result is not proof of an empty queue, and there is no lease (reviewers use revision checks). Gaps remain on return shape and pagination, but the mutation/concurrency semantics are richly covered.

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

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

Four dense sentences, front-loaded with the core purpose followed by behavioral caveats. Every sentence contributes; 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 concurrency-sensitive queue tool with no annotations, no output schema, and 0% parameter coverage, the description covers behavior well but leaves parameter meaning and return/pagination shape undocumented. Adequate on the hard parts, incomplete on the structured-field 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?

All three parameters (limit, project, exclude_ids) have 0% schema description coverage, so the description should compensate and largely does not. It hints at exclude_ids semantics ('a judge may temporarily exclude deferred IDs') but says nothing about limit or project, leaving their meaning unaddressed.

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 ('Get the oldest new or changed experiences awaiting LLM review') and characterizes ordering (oldest) plus scope (awaiting review), which implicitly distinguishes it from review_experience and get_experience. It stops short of naming an alternative sibling explicitly, so it is clear but not maximally differentiated.

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

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

Conveys implied context - this is the queue-fetching step for bounded incremental review work with concurrency safety - but never states when to prefer it over review_experience or get_experience, and gives no explicit exclusions. Usable for the target agent but leaves routing to inference.

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

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

No annotations are provided, so the description carries the full burden. It only says to 'Run defeat propagation' without disclosing whether beliefs are modified, whether changes are reversible, permissions required, rate limits, or what the propagation affects. This is minimal disclosure at best.

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

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

One short sentence, front-loaded with the action and input. No filler is present, though the extreme brevity leaves little structure for a potentially complex operation.

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

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

With no annotations, no output schema, and a single undocumented parameter in the schema, the description should carry more context. It names the seed input but omits propagation semantics, side effects, and usage conditions, leaving an agent unable to predict the outcome.

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

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

The sole parameter is named 'id' and the schema gives only type string with no description (0% coverage). The description adds that 'id' is a 'seed belief ID', which is a useful semantic mapping, but it does not specify format, constraints, or expected source.

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 ('Run defeat propagation') and the input source ('from a seed belief ID'). It is clearer than a tautology, but it does not define what 'defeat propagation' entails or distinguish this operation from sibling tools like record_defeat or sweep_expired_defeated.

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

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

No guidance on when to use this versus record_defeat, sweep_expired_defeated, or other belief operations. The only implicit usage is that it requires a seed belief ID. That is minimal, not misleading.

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?

Since no annotations are provided, the description carries the burden. It adds crucial behavioral context by explaining that the search is semantic, uses cosine similarity for ordering, and requires a specific external configuration file, which goes beyond the scope of the input schema.

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

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

The description is highly concise, fitting the core function (semantic search, chunk return, cosine similarity) into the first sentence. The second sentence efficiently front-loads a critical configuration dependency.

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

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

The description is sufficient for correct tool invocation. However, because there is no output schema, the description is incomplete in explaining the *structure* of the returned 'chunks' (e.g., whether they contain just text or also metadata/IDs).

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

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

With 100% schema description coverage, the baseline is 3. The description reinforces the meaning of the 'context' parameter by stating the query must be 'embedded,' providing operational insight that complements the schema's simple definition of 'Query text to embed and search.'

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 defines the tool's function as 'Semantic search over indexed document chunks.' It specifies the mechanism—embedding the query context and ranking results by cosine similarity—providing a highly specific operational purpose.

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?

While it does not explicitly state when to use it versus sibling tools like query_relevant or get_evidence, it provides a critical usage constraint: 'Requires [embeddings] in config.toml.' This dependency serves as an important operational usage guideline.

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 read-only status, that it severs incoming edges, propagates along CAUSES edges only, returns projected probabilities, and does not modify the graph. It does not cover error behavior (e.g., unknown id) or performance characteristics, keeping it short of a 5.

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

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

Opens with the formal definition, then the graph mechanic, then the read-only guarantee, then the routing sentence. Dense but every sentence carries distinct, load-bearing information 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?

No output schema or annotations exist, so the description must explain behavior and returns; it does explain the returned projected probabilities for causal descendants. It is largely sufficient for a two-param tool, missing only edge-case/error handling detail.

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

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

Schema coverage is 0%, so the description must compensate. It maps the do(target = value) notation onto the two params conceptually, but never clarifies what 'id' actually references (belief name, UUID, etc.) or how it is resolved, leaving a real gap for the caller.

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 precise operation (counterfactual intervention query) with the formal semantics P(downstream | do(target = value)) and the exact graph operation performed. Explicitly names the sibling tools it differs from, so an agent can select it without opening other schemas.

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 an explicit user-facing trigger phrase ('if I change X, what downstream is affected?') and distinguishes itself from two named alternatives: query_relevant (evidential association) and propagate_from (which mutates). When-to-use, when-not, and alternative selection are all 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?

With no annotations this description carries the full burden. It valuably discloses non-obvious traits: outcome counts cover current experience versions in this project only, agent reports/unknown outcomes do not count as measured success, pattern matching is lexical and belief retrieval is hybrid. However, it omits return structure, ordering, and any cost/permission notes.

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?

Purpose is front-loaded in the first clause, with the semantic caveats following in terse sentences. Dense but no filler sentences; the only cost is that caveats compete with the core purpose early on.

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

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

A retrieval tool with 3 undocumented parameters, no annotations, and no output schema needs more than this. Return shape and the meaning/format of 'context' are missing, leaving the agent unsure how to invoke it correctly despite the useful caveats about counts.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does not. The critical 'context' parameter is never explained (how a situation is expressed for lexical pattern matching), nor is 'project' scoping or the 'limit' bound clarified beyond the incidental note about lexical matching.

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 ('Retrieve') and resource ('relevant beliefs and situation-matched procedures') along with return contents (outcome counts, Beta estimates). It is distinguishable from simple list/query siblings in spirit, though it never explicitly contrasts with 'query_relevant' or 'list_beliefs'.

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

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

No when-to-use guidance is provided: it does not say when this tool should be chosen over 'query_relevant', 'list_beliefs', or 'query_intervention'. The disclaimers about counts and retrieval are interpretive caveats, not invocation 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, and it fulfills it by detailing the underlying system behavior (hybrid retrieval, probability ordering) and explaining what the boolean flag does ('also return, per belief, the document passages that ground it').

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 extremely dense and concise. It immediately front-loads the core mechanism and efficiently explains the functionality of the most important parameters in subsequent 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?

The description is highly complete regarding the complex logic (hybrid search, evidence handling, project scoping). It only misses mentioning parameters like `limit` or `prefer_type`, which are details better suited for the schema itself.

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?

Given the low schema coverage (33%), the description compensates significantly by adding crucial semantics. It explains that `include_evidence` provides 'document passages that ground it (with weights),' which is much richer than a simple boolean 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 goes beyond a simple 'search' by specifying the exact mechanism: 'Hybrid retrieval: text match + graph-proximity expansion,' which immediately tells the agent how the information is gathered and ranked by probability.

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 provides excellent internal usage guidelines by detailing the conditional effects of key parameters. It tells the agent to use `include_evidence=true` for grounding context and specifies that `project` restricts the search space to a specific pool.

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

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

With no annotations the description carries the full behavioral burden. It usefully discloses a non-obvious trait that no structured field encodes: this edge does not trigger propagation, unlike record_defeat. However, it says nothing about weight semantics, error behavior for missing ids, duplicate-edge handling, or 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?

Two tightly packed sentences, front-loaded with the core action and direction, followed by the two behavioral facts that matter most. 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 mutation tool with no annotations, no output schema, and 0% parameter coverage, the description is directionally complete but leaves weight semantics, failure modes, and duplicate/idempotency behavior unstated. Adequate, but gaps remain for a 3-param write operation.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies the direction of the two id parameters ('from_id causes to_id'), which is the key semantic ambiguity, but the required weight parameter's meaning is entirely unaddressed despite the schema's 0-1 bounds.

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 (Add), a specific resource (a CAUSES edge), and the exact direction semantics (from_id causes to_id). It explicitly differentiates itself from sibling record_defeat, 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?

Tells the agent the causal consequence ('what query_intervention traverses for counterfactual do(...) queries') and contrasts with record_defeat ('does NOT trigger propagation'), which effectively routes the agent between the two record_* tools. It stops short of stating explicit prerequisites (e.g., both beliefs must already exist).

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 disclosure, but it only mentions that the relationship is bidirectional and named CONTRADICTS. It omits important traits such as whether the operation is idempotent, what happens if the beliefs do not exist, permission requirements, or whether weight affects propagation.

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 a single, front-loaded sentence with no wasted words. It states the action and relationship type immediately, making it efficient even if it is terse.

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

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

For a mutation tool with no annotations, no output schema, three parameters, and zero schema description coverage, the description is far too thin. It does not cover weight semantics, duplicate handling, error conditions, or expected return behavior, leaving important gaps for an agent to call it correctly.

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

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

Schema description coverage is 0%, so the description must explain all three parameters. It implies that id_a and id_b are beliefs, but it does not clarify their order, their string format, or the meaning and effect of the weight parameter at all.

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 (Add), a specific relationship type (CONTRADICTS), and a specific resource (beliefs). It clearly distinguishes this operation from sibling relationship tools such as record_support, record_cause, and record_defeat because the relationship type is named explicitly.

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

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

The description says what the tool does but provides no guidance on when to use it versus alternatives such as record_support or record_cause. There are no exclusions, prerequisites, or contextual cues to help an agent choose this tool over siblings.

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

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

With no annotations, the description carries the full burden, but it does disclose a real side effect: a defeat propagation cascade. It doesn't say what the cascade affects, how far it propagates, or whether it is costly or reversible, which matters for a mutation on a belief graph.

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

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

A single front-loaded sentence with no filler; the primary action comes first and the cascade side effect second. It is appropriately terse, though the terseness contributes to the parameter and usage gaps.

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

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

A mutation tool with no annotations, no output schema, and no parameter documentation is under-specified; the undefined cascade is the only behavioral detail. An agent cannot confidently supply weight or predict the effect on other beliefs.

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

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

All 3 parameters have 0% schema description coverage, so the description must compensate and does not. It never mentions from_id, to_id, or weight — notably the 0-1 weight range and which id is the defeated belief remain unexplained.

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

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

States a specific verb (Add) and resource (DEFEATS edge), and the edge type distinguishes it from siblings like record_support and record_cause. It stops short of explicitly routing the agent among the parallel record_* tools.

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

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

No when-to-use guidance and no comparison against record_contradiction, record_support, or record_cause, despite those being obvious alternatives for a parallel naming family. The agent must infer the distinction from the edge type alone.

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

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

With no annotations, the description carries the full burden and delivers real behavioral content: idempotency ('exact retries do not duplicate evidence'), provenance caveats (caller-reported, not server-verified), and correction semantics ('invalidates the old review and retracts its effects atomically'). It does not disclose what happens on a revision mismatch or other failure modes, so it is 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?

Five dense sentences, all front-loaded with the purpose before mechanics, and every sentence carries information (revision protocol, exclusion, idempotency, provenance, atomic correction). The 'review-owned candidates avoid that duplicate prior' phrasing is jargon-heavy and slightly opaque, but nothing is 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 nested-object mutation tool with no annotations and no output schema, the description covers the concurrency contract, idempotency, provenance trust level, and correction side effects. The remaining gaps are return-value shape and conflict/error behavior on stale revisions.

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

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

Schema description coverage is 0%, and while the description explains expected_revision well (0 to create, returned revision to correct) and hints at id as a stable incident key, the seven required nested experience fields (project, context, action, outcome, source, evidence) get no explanation. The enums are self-describing, but the description only partially compensates for the coverage gap.

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

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

States a specific verb and resource with scope: 'Record one observed action and outcome for incremental LLM review.' The 'one observed action and outcome' framing plus the correction-vs-create semantics clearly separate it from siblings like review_experience, pending_experiences, and insert_belief.

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

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

Gives concrete operational guidance: stable UUID for the same incident, expected_revision=0 to create, returned revision to correct. It also states an explicit exclusion ('Do not also insert a standalone conclusion from this same incident'), which routes the agent away from a duplicating sibling. It stops short of naming that sibling tool by name, so it is strong but not maximal.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a mutation (adding an edge) but says nothing about idempotency for duplicate edges, whether the edge is directed, error behavior for unknown belief IDs, or whether existing weights are overwritten.

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

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

A single front-loaded sentence with zero filler, and the edge type is stated immediately. It is arguably too terse rather than padded, but it is not under-specified in the tautological sense of restating the tool name.

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

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

For a required-parameter mutation tool with no annotations, no output schema, and 0% schema description coverage, the description omits weight semantics, duplicate handling, and failure modes. It is not sufficient on its own to invoke the tool confidently.

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

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

Schema coverage is 0% across all three parameters, so the description must compensate and largely does not. The phrasing 'from one belief to another' loosely maps to from_id/to_id direction, but the required 'weight' parameter (0-1) is never explained in terms of what it represents or how it affects propagation.

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 ('Add') and resource ('SUPPORTS edge'), with the source and target being beliefs. Naming the edge type distinguishes it somewhat from siblings like record_cause, record_defeat, and record_contradiction, but it never explicitly contrasts with those parallel tools.

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

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

There is no guidance on when to use record_support rather than record_cause, record_defeat, or record_contradiction, all of which appear to create analogous edges. No prerequisites, no mention of what happens if the same edge already exists.

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 discloses atomicity, revision checking, key-to-UUID response mapping, the fact that candidate creation is not observed successful use, legacy UUID-only validity, and retraction behavior for corrections. It still omits permissions, error behavior, and rate or effort constraints.

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

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

Five compact sentences are front-loaded with the core action and key behavioral rules. Although jargon-dense, there is little wasted 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?

For a high-complexity, nested mutation with no annotations and no output schema, the description explains only a slice of the required input and output semantics. It says the response maps keys to UUIDs but does not cover required fields or enough revision and error behavior 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 description coverage is 0% and the nested review object contains many undocumented fields such as experience_id, experience_revision, expected_review_revision, reviewer, rationale, links, feedback, and superseded_beliefs. The description only partially explains candidates and legacy UUID-only reviews, leaving most parameter meaning to the raw 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 names the action ('Apply one atomic, revision-checked review') and its candidate-declaration scope, so an agent knows this submits a review rather than merely recording an experience. It does not explicitly say the review targets an experience record or name a sibling alternative, so it is clear but not fully differentiated.

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

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

No sentence states when to choose this tool over siblings such as record_experience, record_support, or insert_belief. The compatibility note ('Existing UUID-only reviews remain valid') is not usage guidance; the reader must infer the use case from the name and schema.

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

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

With no annotations, the description carries the full burden and does well: it discloses that beliefs are permanently deleted, the AND-combined eligibility criteria, the attenuation safeguard, and the return value. It omits any statement about irreversibility or permission requirements, which keeps 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-loaded with the core action, followed by necessary qualifying detail. The long parenthetical is information-dense rather than wasteful, though it slightly delays the project-scoping note that 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 destructive batch tool with no output schema and no annotations, the description covers what gets destroyed, the gating conditions, and the return value ('count of beliefs deleted'). Adequate, with the only gap being irreversibility/permission 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 coverage is 100%, so the baseline is 3, but the description adds value by spelling out the AND relationship between prob_threshold and grace_hours and clarifying that project scope includes untagged global beliefs — semantics beyond the isolated per-parameter schema text.

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 (delete) and resource (defeated beliefs) qualified by precise scope criteria (grace period elapsed, probability decayed). The conditional semantics self-distinguish it from single-item delete_belief and time-based decay_all, so an agent can route without opening schemas.

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?

Explains the triggering condition clearly, including the rationale for the grace period (letting a wrong record_defeat be reversed), which tells the agent when this sweep is appropriate. It stops short of explicitly naming delete_belief or decay_all as the alternative and giving exclusion rules.

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