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

With no annotations, the description carries the burden and mostly succeeds: it discloses the event emission, resolver/wikilink matching consequence, the kind default, and the two error codes (E_NOT_FOUND, E_VALIDATION) with their triggers. It does not address idempotency or what happens if the identifier is already attached, nor any permission requirements, which is the remaining gap 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?

Front-loaded with purpose and the sibling distinction before the example and error behavior, and every sentence carries information. The inline call example partially restates the schema but is justified as usage illustration; it could be trimmed slightly without loss.

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 three-parameter mutation with an output schema present, the description covers the mutation's meaning, its downstream effect on resolution, the default and allowed kinds, and failure modes. Nothing beyond return-value shape is missing, and return values are handled by the output schema.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds real value on top by stating kind defaults to "alias", listing accepted canonical kinds (email/username/phone/id) and domain snake_case types, and showing a worked call with the old-name alias case. Slight overlap with the schema's own kind description keeps it from a 5.

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 (attach) on a specific resource (identifier) with the critical scope constraint that the entity must already exist, plus the side effect of appending an entityIdentifierAdded event. It explicitly distinguishes itself from the two nearest siblings, createEntity and updateEntity.

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 concrete when-to-use scenario (retain the prior name after renaming displayName via updateEntity) and names the alternative it is not (createEntity only seeds identifiers at mint time). The condition that selects this tool over its siblings is unambiguous.

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

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

With no annotations at all, the description carries the full behavioral burden and does so well: it discloses that recurring feedback auto-promotes into per-session guidance, that the user can pin/edit/veto that guidance, that 'rule' is the field that actually gets promoted, and that high severity lowers the recurrence threshold. It also discloses the default recording scope as device-local diagnostic, which an agent could not infer from the schema alone.

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

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

One dense paragraph that front-loads purpose, then field expectations, then the promotion consequence. Every clause does work, though the parenthetical enumerations make it feel packed; a couple of sentences could be tightened without losing information.

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

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

For a 9-parameter mutation tool with no annotations, the description covers what an agent must know before calling: required fields, optional-but-encouraged fields, scope default, and the downstream effect on session guidance including user override. Since an output schema exists, the absence of return-value prose is not a 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 100%, so the baseline is 3, but the description adds real meaning on top: it identifies category/severity/summary as the required trio, clarifies 'surface' as part of the recurrence cluster and thus encouraged, and explains that severity's high value triggers promotion at a lower threshold — a consequence the enum alone doesn't convey.

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 opens with a specific verb and resource — 'Record durable feedback about using Mazarbul' — and enumerates the friction categories and the 'lesson' alternative, so the agent knows exactly what belongs here. It falls short of a 5 because it never names the sibling tools it could be confused with (remember, fact, contextPin) to draw the line between logging a rule as feedback versus storing it as knowledge.

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 clear usage condition ('File DURABLE friction or rules') and an explicit exclusion ('not one-off disagreements'), which is exactly the kind of judgment call an agent needs. What's missing is a pointer to the alternative path for non-durable cases or for facts, so the routing is only half-resolved.

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

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

Annotations are empty, so the description carries the full burden for a destructive mutation. It does not say whether cancellation is reversible, whether it is idempotent, what happens if the job already completed or failed, or whether any permission is required. An output schema exists, so return values need not be covered, but the core mutation semantics are missing.

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 waste; the identifier format follows the operation rather than burying it. It may be slightly too terse given what is left unsaid about the mutation.

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 tool with full schema coverage and an output schema, the description covers the minimum needed to invoke it correctly. It falls short on lifecycle semantics — job state at cancellation, post-cancel behavior — which matter for a cancel operation with no annotations.

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 parameter already documents the 'jobs/{uid}' format and the pattern. The description only echoes the same format, adding no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource — 'Cancel a tracked background job' — plus the identifier format, so the agent knows exactly what operation is performed. It does not differentiate from the related listJobs sibling, which would be the natural way to discover a job name, 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 statement of when to use this versus alternatives, no prerequisite that the job must exist and be in a cancellable state, and no pointer to listJobs for obtaining a valid name. The only implied context is the word 'tracked'.

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

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

Annotations are empty, so the description carries the full burden — and it does cover a lot: untrusted lineage (connector:<name>), facts landing as proposed rather than superseding, TTL-scoped idempotency by contentHash, and tombstoning via status. It does not state auth/permission requirements or what the response contains on a duplicate no-op beyond the idempotency claim.

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 distinction (pointer, not body) and each subsequent sentence adds a distinct constraint (freshness verdict, trust tag, idempotency, tombstones, refusals, dedup workflow). Dense but nearly every clause earns its place; minor tightening possible.

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 an output schema present, return values need not be explained, and the description covers the trust model, idempotency, refusal rules, and dedup ordering that the schema alone cannot convey. Sufficient for a 14-parameter mutation tool with no annotations.

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 14 parameters; the description largely restates what the schema says (contentHash idempotency within TTL, status=deleted|access-revoked tombstoning, summary requirement). It adds framing about why project scope is refused but no syntax or format detail beyond the schema — baseline 3 applies.

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

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

Specific verb and resource: 'Index an external item you fetched from a live connector ... WITHOUT copying its body', naming the pointer+summary+freshness-anchor model. It explicitly distinguishes itself from ingest/remember siblings by stating maz never fetches or holds the content.

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 both directions: 'recall FIRST before capturing, to avoid duplicates' and hard exclusions ('Refuses project scope and ephemeral connectors (gmail/gcal/slack; read those live)'). The alternative for ephemeral sources is named explicitly, and the tombstone path is described.

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 the trust model (ingested content is UNTRUSTED; facts land proposed and capped, never superseding your own) and the return shape (itemsApplied/Skipped plus a jobUid). It omits auth/permission requirements beyond the granola key hint and says nothing about idempotency or repeat-run 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?

Opens with the action and outcome in one clause, then packs connector selection, optional knobs, trust model, and return value into three dense sentences with zero filler. Parenthetical asides are used efficiently rather than sprawling.

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 mutating ingestion tool, the description covers the safety model, refusals, per-connector prerequisites, and the return report, and an output schema exists to carry return detail. A gap remains around the jobUid's lifecycle (polling via `listJobs`/`waitForIdle`) and how this differs from `ingestSource`.

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 real meaning: it groups which parameters apply to which connector, restates defaults (personal), and characterizes maxItems/maxExtractionCalls as run bounds and dryRun as a count-only preview. The enum for scope is reinforced with the project-refusal rationale.

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 ('Connect') and resource ('a source') plus the key scope ('bounded first backfill into the graph'), which is far more informative than a bare name. It implicitly separates itself from the ongoing-ingest sibling (`ingestSource`) via 'first backfill', but never names that sibling outright, so an agent must infer the distinction.

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

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

Gives per-connector guidance (repoPath for file-based, stored API key for granola, `maz source add granola` to set it) and explains dryRun as the preview/consent gate. It also states a hard exclusion ('Refuses project scope'). It stops short of saying when to prefer this over `ingestSource` or `listSources`.

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 does meaningful work: it discloses append-only semantics ('history is preserved'), conflict resolution ('the latest correction wins'), and the exact return shape (the overlay's contextPins/{uid}). It leaves out idempotency and permission failure behaviour beyond what the schema's scope caveat already covers.

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 action and the input contract, followed by the event-sourcing semantics and the return value. No sentence 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?

An output schema exists and parameter coverage is complete, so the description only needs to explain the non-obvious mutation model — which it does. It could still say what happens when the targetId isn't in the current brief or how the overlay interacts with the original pin, which is the only gap for a write tool with zero annotation coverage.

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 targetId, text and scope are already fully documented, including the ULID/entities/{uid} forms and the team membership caveat. The description restates the id forms and adds only that the text is rendered 'in its place' — a marginal delta over 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?

A specific verb-plus-target — correct a wrong item surfaced by the cold-start brief — plus a stated effect (the brief renders the corrected text in place). It distinguishes itself from updateEntity/editDocument by declaring the correction is a new event rather than an in-place edit, so an agent can pick it apart from the neighbouring mutation 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?

It clearly scopes usage to items the cold-start brief surfaced, and the 'NEW event, not in-place edit' note tells the agent when this is the right mechanism versus a normal edit. It never names an explicit alternative sibling or states a when-not condition, so it stops short of a 5.

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

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

No annotations, so the description carries the full burden and mostly succeeds: it discloses the ordering effect (the note wins a budget slot before auto-surfaced documents and entities) and the return shape (contextPins/{uid}). It does not discuss limits on how many pins are allowed or failure modes beyond what the schema states, 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 action and trigger, then the behavioral effect and lifecycle pointers. Every sentence carries distinct 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 3-parameter tool with an output schema and no annotations, the description supplies the trigger, the ordering behavior, the return reference, and the sibling lifecycle tools. An agent has everything needed to decide to call it and what to do afterward.

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 scope/targetRef semantics, including the E_PERMISSION condition, are already documented in the schema. The description adds the concept of what a pin steers but no parameter-level detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: pin a free-text steering note to the top of the cold-start context brief. It clearly distinguishes the tool from contextUnpin (retire) and contextCorrect (override) named in the same description.

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

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

Gives an explicit trigger ('when the user states a durable preference or constraint they want surfaced first every session') with a concrete example. It also names both alternatives and the conditions that select them: contextUnpin to retire, contextCorrect to override.

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

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

Annotations are empty, so the description carries the full burden and does well: it discloses that the row is tombstoned rather than deleted, that history is preserved, and that the retire converges across devices. It omits permission/scope requirements and any error behavior for unknown or already-retired pins.

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 outcome, then the input format, then the tombstone semantics, then the usage cue — a sensible ordering. The closing 'use when' sentence partly repeats the first sentence's framing, so there is minor redundancy.

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

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

An output schema exists, so return values needn't be explained, and the mutation's semantics (soft delete, cross-device convergence) are covered. The scope parameter's meaning is only in the schema, which is acceptable but leaves the description slightly incomplete.

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 documented, and the description's restatement of the contextPins/{uid} or bare ULID format adds little. The scope parameter and its 'match the pin's scope' guidance are 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 names a specific verb (retire/unpin) and resource (steering pin or correction) and states the observable effect: it stops surfacing in the cold-start brief. It also names the sibling tools that produce pin identifiers (contextPin/contextCorrect), so an agent can distinguish this teardown operation from the creation path.

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

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

It gives an explicit trigger: 'Use when a pinned note or correction is no longer relevant,' and implicitly pairs with contextPin/contextCorrect as the inverse. It does not discuss any when-not conditions or what happens if the pin is already retired or the UID is wrong.

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 behavioral burden and does well: it discloses that team entities are hidden unless scopes:["team"] is passed, that groupBy switches to a per-value breakdown, and that entities without an open fact bucket under the empty value. Minor gaps on return shape are offset by the output 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?

Front-loaded with the core purpose, then scope and groupBy behavior in tight sentences. No filler; each sentence carries distinct information.

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

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

With 0 required params, full schema coverage, and an output schema present, the description covers the behavioral essentials an agent needs: scope defaults, groupBy semantics, and filter grammar reference. Nothing critical 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 baseline is 3, but the description adds meaning beyond the schema — the team-hidden scope default and the groupBy bucketing behavior — which helps an agent reason about parameter outcomes rather than just syntax.

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 ('Count entities') and frames it as 'the deterministic answer to how many', which distinguishes it from a list/query tool. The groupBy breakdown and scope language further narrow what the tool returns.

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 scope default (project+personal) and the condition to include team entities, and points to 'the entities tool' for the filter grammar. It doesn't explicitly say when to prefer this over the 'entities' or 'query' siblings, but the usage context is clear.

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: it discloses deduplication semantics per status (reused, duplicate_candidates, created), that same-name or near-duplicates are NOT minted silently, that advisory candidates are still listed on a plain create, and that E_VALIDATION fires on malformed kind, empty displayName, out-of-range confidence or non-object properties. That is unusually rich behavior disclosure 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?

Purpose and usage are front-loaded in the first two sentences, followed by dedup behavior and error surface, which is the right ordering. It loses a mark for the middle "Inputs:" enumeration, which duplicates what the schema already says and bloats an otherwise tight paragraph.

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 mutation tool with nested identifier objects, no annotations, but a full output schema, the description covers what it must: prerequisites, dedup/override workflow, per-status outcomes and validation errors. Return shape is correctly left to the output schema, so nothing material 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%, so the schema already documents kind, force, confidence, identifiers, alternateNames and properties in detail; the description's "Inputs:" clause mostly restates it. It adds modest relational meaning — that identifiers anchor the resolver into a distinct lookup lane and that force overrides the duplicate gate — but not enough to 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?

The description opens with a specific verb+resource: "Mint a structured entity of a registered kind directly, bypassing LLM extraction." It immediately positions itself against siblings — the write-side complement to relate, explicitly not a remember() round-trip — so an agent can distinguish createEntity from remember, relate, updateEntity and defineEntityKind without opening any schema.

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

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

It gives an explicit use condition ("when you already hold an entity as (kind, displayName) and need its entities/{uid} to assert a relation") and then names the alternatives in the duplicate case: reuse a uid, merge with mergeEntities, or retry with force=true. The defineEntityKind/introspect prerequisite for extension kinds is stated outright, so there is nothing left to infer.

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: it discloses the automatic dedup pass (reused / closeMatch alias / maz:kind URN in sameAs), the expected multi-second latency with an explicit 'do not abort or retry' warning, the event-append plus dispatcher/materialisation and git-sync side effects, and the E_VALIDATION failure modes for core-kind edits and unknown parents.

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 long, but front-loaded with the purpose followed by dedup, latency, inputs, side effects, and errors in a deliberate order. Nearly every sentence carries operational information; a couple of clauses (event appending plus materialisation plus render pipeline) could be tightened without loss.

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 eight parameters, nested propertySchema, an output schema, and a mutation with real side effects, the description covers prerequisites, latency, dedup outcomes, error codes, and reversibility (force overwrite) — nothing an agent needs 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 the baseline is 3, but the description goes further by explaining name must be bare snake_case with no namespace, that description is required specifically for dedup, that extends must resolve to a core or active registered kind, and that sameAs is for external vocabulary IRIs. It adds real semantic framing beyond the property descriptions rather than repeating them.

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 clause states a specific verb and resource — 'Register a new entity kind in the dynamic-ontology registry' — and immediately names the siblings (introspect→entityKinds, describeType) that serve the alternative purpose. An agent can distinguish this from definePredicate/defineSchema/describeType 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 instructs the agent to check for an existing covering kind first and names the two concrete alternatives (introspect → entityKinds, describeType). It also flags the preview parameter as the way to inspect impact before committing and force=true for overwriting, giving both when-to-use and when-not-to-mint 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 does most of it: it discloses that re-registering mutates kind/description/domain-range/sameAs/propertySchema and returns status=updated, that domain/range constraints are advisory unless [ontology] strict_domain_range is enabled, and that malformed input returns E_VALIDATION. The gap is scope/authorization — a 'shared' vocabulary mutation with no statement about who may register or whether it affects other teams.

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 and the introspect prerequisite, then a compact parameter enumeration, then consequences and error behavior. Dense but nearly every clause is load-bearing; the parenthetical domain/range glosses are mildly redundant with the schema.

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 7-parameter mutation with nested propertySchema, the description covers semantics, config-gated enforcement, upsert behavior, error conditions, and cross-tool workflow. An output schema exists, and it still flags the status=updated shape, so nothing essential 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 already 100%, so the 3 baseline is met by structured fields alone; the description adds a domain/range framing for subjectKinds/objectKinds and connects propertySchema to the relation's attributes map, plus notes the advisory-vs-enforced behavior of those constraints. It doesn't add format detail beyond the schema's examples, so it stops short of a 5.

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?

Opens with a specific verb+resource ('Register a new predicate in the shared predicates vocabulary') and immediately positions it against siblings: introspect for checking, relate for consuming. An agent can distinguish this from defineEntityKind or defineSchema 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?

States an explicit prerequisite workflow ('first call introspect to check existing predicates ... so you don't mint a synonym'), explains re-registration as an update path, and names where the result is used (queryable via introspect, usable in relate calls). No alternative tool is left 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 does reasonably well: it discloses that core schema kinds are protected, that E_VALIDATION is returned for non-object definitions or protected kinds, and that schemas become immediately usable via ValidateEntityProperties. It omits auth/permission requirements and doesn't describe the preview/dry-run behavior, which is only in the 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?

It is front-loaded with the core action and use cases in a compact four-sentence block. The repeated E_VALIDATION mentions are slightly redundant, but nothing is wasted at a structural level.

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 an output schema present, the description covers purpose, use cases, protection rules, and error conditions. The preview parameter and version-conflict behavior are left entirely to the schema, which is acceptable given 100% schema coverage, but mentioning preview would strengthen 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 coverage is 100%, so the schema already documents all four parameters, including preview and version-conflict semantics. The description mentions the same shapes (bare camelCase or colon-namespaced, semver) but adds little beyond the schema, so the 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 opens with a specific verb and resource: 'Register a JSON Schema document in the dynamic-ontology schema registry.' It distinguishes the tool from siblings like defineEntityKind and definePredicate by naming the schema-kinds it applies to (entityKind:vehicle, new event types).

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 contexts for use: attaching validation schemas for custom entity-kind properties, or defining schemas for new event types. It also states the 'when not' case for protected core kinds. It does not explicitly name a sibling alternative (e.g., defineEntityKind), 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 present, the description carries the full burden and does so: it discloses irreversible hard-delete scope, the safety refusal (E_VALIDATION), the E_NOT_FOUND case, tombstone/audit side effects, and that cascade tombstones relations first. That is exactly the pre-call risk context an agent needs for a destructive 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?

Front-loaded with the destructive action and scope, followed by the alternative, the default safety behavior, and the error case in that priority order. Dense but every clause adds distinct decision-relevant information; no filler.

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

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

Covers everything an agent needs before a destructive call: what is destroyed, what happens to connected data, the safe default, how to override it, which sibling to prefer, and failure modes. An output schema exists, so the description is not obliged to explain return payloads, and it doesn't waste space doing so.

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 nonetheless adds semantic consequence beyond the schema by framing cascade as a confirmation gate ('pass cascade=true to tombstone those relations first and proceed') rather than just a boolean. It adds less for entityUid and reason, which the schema already documents thoroughly.

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?

Opens with a specific verb+resource+identifier type: 'Hard-delete an entity by ULID', then enumerates exactly what is removed (relations, facts, mentions, identifiers, citations, graph node, audit tombstone). It explicitly distinguishes itself from mergeEntities, so an agent can tell which destructive tool applies 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?

States the intended case ('unwanted or junk entities') and the alternative with its condition ('to consolidate DUPLICATES without losing data use mergeEntities instead'). Also gives the operational branch: default refusal on active relations vs. cascade=true to proceed.

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 burden, and it does disclose real behavior: name resolution semantics, the E_NOT_FOUND failure mode with near-name suggestions, and the depth of the returned record. It stops short of stating permission/auth requirements, which for a read tool is a minor gap rather than a serious one.

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 returns, then usage routing, then input resolution and error behavior — a sensible order with no filler sentences. The field enumeration overlaps with the output schema, which is slight redundancy but still aids scanning.

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 an output schema and no annotations, this covers everything an agent needs: what it returns, when to prefer it over siblings, how names resolve, and what happens on failure. Nothing material 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%, so the baseline is 3. The description's note about a bare local name resolving to the user: kind when unambiguous largely restates the schema's own parameter description, adding little beyond it.

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 (describe) and resource (a single entity kind) and enumerates exactly what is returned: displayName, description, parent, child kinds, sameAs aliases, provenance lane, entity count. It explicitly differentiates itself from introspect's 'cheap kind index', so an agent can distinguish it from the sibling without opening a schema.

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

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

Gives concrete when-to-use triggers: confirm a kind's shape and reuse before minting a near-duplicate with defineEntityKind, or before createEntity. It also names the cheaper alternative (introspect) and the condition that selects it, 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 present, the description carries the full burden and does substantial work: it discloses the durable event append, the terminal 'dismissed' state, removal from hot recall, no re-promotion by access, and survival across rebuilds. What is missing is idempotency behavior (dismissing an already-dismissed insight) and any permission/scope authorization requirements for the mutation.

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 action and followed by the state effects and the contrasting non-use case. Every sentence carries information, though the identification-format sentence partially duplicates the schema 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 mutation tool with empty annotations, the description covers lifecycle effects, durability, and visibility consequences, and an output schema exists so return values need not be re-explained. The remaining hole is operational detail: error behavior for unknown or already-dismissed uids, and what 'scopes' resolution means for lookup failures.

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 in the schema, including the name formats. The description repeats the 'insights/{uid} or a bare uid' identification guidance and says nothing about 'reason' or 'scopes', so it adds essentially no 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 uses a specific verb (dismiss) and resource (synthesized insight) and immediately fences off the closest conceptual neighbor: 'This is NOT a decay/demotion (which the system does on its own)'. An agent can distinguish this from system-driven insight lifecycle handling without consulting any other tool.

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 clear trigger condition ('the user judges wrong or unhelpful') and explicitly excludes the system-managed decay case, which is the main ambiguity risk. It also tells the agent where to obtain the identifier (a listInsights / recall hit's name). It does not name a preferred alternative tool for other cases, so it falls short of a full when/when-not/alternatives 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 behavioral burden and does so well: it discloses that edits create a new revision, history is kept, wikilink edges are re-resolved, removed links are forgotten, and the vault file refreshes. It also explains that edges and unresolved counts are whole-document snapshots after the edit.

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 operation and then layers behavioral consequences and the sibling alternative in only three sentences. Every sentence adds distinct 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?

Although annotations are absent, the description explains the side effects an agent most needs to know for a mutation: revision history, link re-resolution, and refresh behavior. Because an output schema exists, it need not fully describe return values, and its note about result counts is sufficient 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%, so all five parameters already carry their own documentation in the input schema. The description repeats the key oldString uniqueness rule and replaceAll behavior but does not add syntax or format detail beyond 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 specific verb and resource: editing a document by exact string replacement. It immediately distinguishes this from whole-body replacement by naming writeDocument in the next sentence, so an agent can select it 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?

It explicitly contrasts the tool with writeDocument, giving the alternative and the condition that selects it: use writeDocument to replace a whole body. The uniqueness and replaceAll rules further clarify when the edit will be accepted.

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 key traits: it is an LLM-free read/discovery surface, recallCount ordering depends on usage stats, and merge/delete are noted as separate lossless/destructive operations rather than being conflated with this tool. It stops short of stating permission or scope implications for reading across project/personal/team, which leaves a small gap for a 10-param 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 sentences, front-loaded with the core list/filter capability, then routing and lifecycle escapes. Every sentence either defines scope or redirects to a sibling; nothing is redundant with the schema 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?

An output schema exists so return values need not be explained, and all 10 parameters are documented in-schema, making this largely sufficient for correct invocation. The remaining gap is behavioral: with an empty annotations object, the description could state read-only safety and any scope/permission caveats for cross-scope reads.

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 every parameter and baseline is 3. The description adds value beyond it by explaining the intent of sortBy=recallCount (most-recalled first, and that it replaces listTopEntities) and framing the name/confidence filters as discovery levers, though it doesn't elaborate on filter syntax since the schema already does.

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

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

States a specific verb and resource ('List and filter entities by kind, name substring, and confidence, with pagination') and immediately frames its role against siblings: an anchor-discovery surface that feeds neighbors/relations, plus explicit replacement of listTopEntities. An agent can distinguish it from query, neighbors, or relations without opening a schema.

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

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

Gives explicit routing: start here to find an anchor, then pivot into neighbors/relations; use the duplicate detection path with mergeEntities and junk cleanup with deleteEntity. It also names the deprecated alternative it supersedes (listTopEntities), which is exactly the kind of when-to-use signal that prevents wrong-tool selection.

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

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

Annotations are empty, so the description carries the full burden, and it delivers the key non-obvious behavior: a later write to the same stateKey supersedes the prior value, which is retained as history. It also discloses that this bypasses LLM extraction. It does not cover failure modes or permission behavior beyond what the scope parameter already documents.

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 action and slot shape, then sibling differentiation, a concrete example, supersede semantics, and read paths in that order. Every sentence carries information; nothing is restated from the schema verbatim.

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 7-parameter mutation tool with an output schema (so return values need not be explained), it covers the slot model, supersede/history behavior, and how to read back. Gaps are the absence of guidance on removal (retractFact) and on error/permission outcomes.

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 reinforces stateKey as a hierarchical slot and combines it with a sample value, but adds no format or default detail beyond what the schema already documents for scope, source, eventStart, and sourcePriority.

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 ('Record a scalar fact ... as a (subject, stateKey, value) slot') and explicitly contrasts itself with the sibling `relate`: edges between entities vs. a single entity's slots. The parenthetical example (state.task.status=pending) makes the shape 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?

Gives an explicit selection rule against `relate` and names the read path (get(entities/{uid}) for current slots, get(facts/{uid}) for a single fact). It does not mention `remember` (extraction-based writing) or `retractFact` for removal, so the when-not / deletion story is incomplete.

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 does useful behavioral work: it discloses tombstoning, derived-state removal across storage layers, audit-trail preservation, and hard deletion for factUid. It does not discuss permissions, confirmation, or broader irreversibility beyond the fact case.

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-load the core action and then add the important factUid exception. There is no filler, and the alternative is placed where it matters.

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 rich schema and existing output schema, the description is nearly complete: it covers the operation's storage effect and the key retractFact alternative. Minor gaps around permissions or confirmation are acceptable because the schema and annotations carry most structural details.

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 parameters, including mutual exclusivity and the factUid/retractFact distinction. The description reinforces the ULID-based selection model but adds little parameter meaning beyond what the schema provides.

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 scope: forget an Episode, Relation, or Fact by ULID. It also distinguishes the factUid hard-delete path from retractFact, so an agent can differentiate this tool from a key sibling 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?

It gives clear usage context for fact deletion by explicitly naming retractFact as the alternative when history should be kept. It does not fully address when to use forget versus relation-specific siblings such as unrelate, so it stops short of full 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?

No annotations are supplied, so the description carries the full burden, and it does substantial work: it discloses the resolution precedence (non-document entity beats same-named document), that passed-over documents appear in `shadowedDocuments`, that ambiguous non-document names return a pointed error naming candidates, and that demoted insights remain fetchable. It never states permission/scope requirements around the `scopes` default or side-effect freedom beyond what 'get' implies.

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

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

It is front-loaded correctly, leading with the fetch action and the accepted name forms, but the back half is a long per-type enumeration of returned fields (insight statement/insightType/state, consolidated memory summary/memoryType, etc.) that duplicates what the output schema already declares. That block is padding against a tool that has an output schema and dilutes the high-value resolution rules.

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 six parameters, no annotations, and an existing output schema, the description covers everything an agent needs to call it correctly: accepted name forms, resolution precedence, the ambiguity error path, scope semantics, and temporal anchors by reference to the schema. Nothing required for a 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 the baseline is 3; the description earns above that by adding resolution semantics the schema does not state — case-insensitive display-name resolution, the entity-over-document precedence rule, and the fact that `kind` is ignored for resource-name and bare-uid lookups. It leaves `at`, `asOf`, `scopes`, and `includeInactive` 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 first sentence gives a specific verb+resource ('Fetch one record by AIP resource name') and enumerates the exact collection prefixes the lookup accepts. It also positions itself against the sibling recall tool ('the structured, LLM-free way to follow any recall hit's name field' ... 'get is not the hot-recall index'), so an agent can pick between them without opening a schema.

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

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

Usage context is clear: use this to resolve a name coming out of a recall hit, and use `kind` / a vault path when a document and a domain entity share a name. It stops short of an explicit exclusion sentence (e.g. 'to search by content or filter by user, use recall/query instead') and gives no guidance on when to prefer the sibling `entities`, `relations`, or `fact` readers over this one.

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 does disclose a key behavioral trait: the document body is deliberately excluded, so only edges are returned. It also explains the semantics of each returned field, though it says nothing about permissions, dangling/unresolved links, or ordering.

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: what it returns, why it's useful, and how to identify the target. The scope qualifier and payoff are front-loaded, and no sentence 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 two-parameter, fully documented read tool with an output schema, the description covers purpose, return shape, and identification well. Remaining gaps (link resolution behavior, whether backlinks include entity references, permissions) are minor but not trivial for graph tooling.

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 itself already states the exactly-one constraint between path and documentUid. The description's final sentence repeats that same rule without adding format or resolution guidance, so it merely matches structured data rather than exceeding it.

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 a document's wikilink edges') and enumerates the two edge categories returned (backlinks, links). The clause 'without its body' distinguishes it from readDocument/get, and 'the graph' framing separates it from the entity-oriented relations/neighbors 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?

'The fast way to map a note's place in the graph' gives clear context for when to reach for it versus the heavier document readers. It does not name an explicit alternative or state exclusions, so it falls short of a full 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 behavioral burden. The verb "Return" strongly implies a read-only operation and there are no parameters that could mutate state, but the description does not explicitly confirm read-only behavior, side effects, authorization needs, or rate limits.

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

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

The description is a single front-loaded sentence that states the return scope immediately. The enumerated storage layers earn their place by making the output scope concrete, with no wasted wording.

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 tool with an output schema, the description is largely complete: it explains what gets returned and the output schema can define the exact response shape. The only gap is the lack of explicit read-only or safety framing, which is more noticeable because annotations are empty.

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 there is no parameter semantics for the description to explain. The schema coverage is 100%, and the baseline for no-parameter tools is a 4.

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 and resource: it returns on-disk byte totals by storage layer. It enumerates the exact layers covered plus free disk, which makes the tool's scope unambiguous and distinguishable from the sibling 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?

The description states what the tool returns but gives no explicit guidance on when to use it, when not to use it, or what alternative to prefer. Usage is only indirectly implied by the tool name and the capacity-related return fields.

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 does disclose key traits: deterministic, no LLM call, hard budget cap, and visible truncation markers. It doesn't explicitly state that it is a read-only operation with no side effects, which is the main remaining safety question for an agent.

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 tight sentences; the purpose is front-loaded, then behavior, then the routing hint. Every sentence carries distinct information with no restatement of the name or title.

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?

An output schema exists and the return format (markdown brief) is already characterized, so the description needn't explain return values. For a zero-required-parameter tool with full schema coverage, the description covers purpose, budget behavior, and session-start usage — nothing essential 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 baseline is 3. The description reinforces the effect of `query` (adds a co-ranked relevance section) and `budgetTokens` (never exceeded, tail dropped behind a marker), but adds little beyond what the schema descriptions already say, and `scopes` semantics are 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 opens with a specific verb and resource ('Assemble a token-budgeted markdown brief of the user's working set') and enumerates exactly what goes into the brief: pinned docs, recently-updated docs, key entities, and query-relevant hits. An agent can distinguish this from recall/readDocument/listDocuments siblings without opening any schema.

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

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

It states a clear usage context ('for loading at the start of a session') and an explicit preference rule ('Prefer this over many small reads when you need to warm up context about the user'). It doesn't name specific sibling tools (recall, readDocument, query) or state when not to use it, which keeps it 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 fully carries the behavioral burden. It discloses truncation behavior ('lower-priority bullets are dropped behind a marker'), time-slice semantics ('header is unchanged'), and error contracts ('E_NOT_FOUND' for unknown, 'E_VALIDATION' naming candidates for ambiguous names). It also defines the dossier's structure (header, Connections, What I know, Mentioned in, counts footer).

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 purpose is front-loaded and every sentence contributes useful information. The description is dense but appropriately sized for a composite tool with five parameters, though it could be slightly tighter by avoiding restatement of schema details such as entity formats and budget truncation.

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, the description covers the critical dimensions: what the dossier contains, how time-slicing behaves, how truncation works, and what errors to expect. An output schema exists, so return-value formatting need not be explained further. The definition is complete enough to call 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 every parameter in detail, including accepted `entity` formats, `at` time semantics, `scopes` defaults, `include` filtering, and `tokenBudget` truncation. The description largely restates that information rather than adding new parameter-level meaning, so the baseline of 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 opens with a specific verb and resource: 'Assemble a single token-budgeted markdown dossier for ONE entity.' It immediately distinguishes itself from siblings by naming the five calls it collapses (get + relations + neighbors + recall + facts) and explicitly says to prefer it over 'many small reads' for a full picture. An agent can tell exactly what this tool does and that it is a composite read.

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

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

Usage is explicit: use it when you need the full picture of one entity instead of many small reads. It also names the alternative pattern ('many small reads') and explains the section-filtering option via `include`, plus the time-slicing use case via `at`. No major inference is required to choose this 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?

With no annotations, the description carries the burden and does real work: it discloses that provenance is SELF-ASSERTED and UNVERIFIED, that trustState is always 'unverified', and that no cryptographic attestation exists. That is exactly the kind of trust caveat an agent would otherwise mishandle. It stops short of stating read-only semantics explicitly or what happens when the name does not resolve.

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 verb and resource path, then the domain explanation, then the sibling pointer. No filler and no repetition of the schema.

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?

An output schema exists, so return values need not be explained, and the schema fully covers both parameters including scope defaults. What remains unaddressed is failure behavior for an unknown or unreachable sourceRefs name, which matters slightly for a name-pattern-constrained lookup.

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 `name` (with its ULID pattern) and `scopes` are already fully documented in the schema. The description restates the sourceRefs/{uid} shape but adds no new meaning about scopes or identifier provenance, 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 ('Fetch') and a precisely bounded resource ('one external-source provenance record (SourceRef) by AIP resource name sourceRefs/{uid}'). It then explains what a SourceRef actually is (connector, stream, external id/url, content hash, fetch time), which distinguishes it cleanly from siblings like get, recall, or listSources.

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 only routing guidance is the closing sentence 'Use recordSourceRef to create one,' which correctly points at the sibling for the write direction. There is no guidance on when to call this versus other read tools (get, getContext, recall, getBacklinks) that might also surface provenance, nor any when-not condition.

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 disclosure burden. 'Return' weakly implies a read-only operation, and enumerating the metrics tells the agent what kind of data comes back, but it says nothing about snapshot freshness, cost, permissions, or whether 'current' means pre-aggregated versus computed live — the main behavioral unknown for a telemetry 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 sentence, front-loaded with the verb and resource, followed by a compact enumeration of the returned metrics. Nothing is redundant or padded.

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

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

An output schema exists, so return shapes need not be spelled out, and the description still names the key metrics. What's missing is only the relationship to similarly-scoped siblings (getCapacity) and any note on snapshot recency, which is a modest gap for a read-only telemetry 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 100% and the single 'window' parameter is fully documented with its enum and default ('today'), so the baseline is 3. The description adds no meaning about how window affects aggregation or which window the metrics default to, so it neither compensates nor detracts.

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 ('Return') and resource ('current usage snapshot') and enumerates the exact metrics returned (events written, recalls, embed-cache hit rate, recall latency percentiles). It does not, however, distinguish itself from the closely related sibling getCapacity, which an agent could easily confuse with a usage/telemetry call.

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 only implied: the enumerated metrics suggest 'call this to read telemetry', but there is no explicit when-to-use statement, no exclusion, and no pointer to alternatives such as getCapacity or idleStatus. The agent must infer the choice from the metric list 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?

No annotations are provided, so the description carries the full burden. It does so adequately: 'Return' plus 'current ... counters' plus 'poll' makes clear this is a non-blocking read-only snapshot rather than a mutation or a blocking wait. What remains implicit is that it does not wait for idle and returns immediately even when work is pending, which is the one behavioral trait that would most change how an agent sequences the call.

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, no filler. The return contents come first and the usage scenario second, so the agent gets the 'what' before the 'when'. Every clause carries information: each of the three counters is named, and the remember()/recall() context is specific rather than generic.

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?

An output schema exists, so the description is not obligated to explain the return shape, and with no parameters and no annotations this is a low-complexity tool that the text covers well. The only material omission is the relationship to waitForIdle — whether to poll this or block on that — which is exactly the decision an agent faces when background work is in flight.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and no risk of undocumented inputs. Baseline for a no-param tool is 4, and the description does nothing to lower it.

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 current background-work counters') and enumerates exactly which counters: extraction queue depth, in-flight enrichment, in-flight embeddings. That is far more precise than the bare name idleStatus. It stops short of a 5 because it never names its obvious sibling waitForIdle, so the agent must infer the polling-vs-blocking split from the surrounding tool list.

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

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

Gives a concrete usage scenario: poll after a burst of remember() calls, before recall(), for a clean retrieval measurement. That is real when-to-use guidance tied to named siblings. It offers no when-not or exclusion, and does not say why an agent would poll here rather than call waitForIdle, which is the main alternative an agent would weigh.

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 most of it well: it discloses that the tool writes data, that it is idempotent via content-hash comparison, that project scope is refused and why (plaintext vs. sensitive external content), the default caps, and that dryRun acts as a consent gate. The gap is job lifecycle — it returns a jobUid but doesn't say whether the run is synchronous or must be polled via listJobs/waitForIdle, nor what failure mid-ingest leaves behind.

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 its incremental nature, then moves to inputs, then to guarantees and return value — a sensible order. Dense but nearly every clause carries information; the stacked parentheticals in the parameter sentence make it slightly harder to scan than it needs to be.

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

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

For a six-parameter mutation with an output schema, this covers prerequisite state, connector-specific setup, scope safety, defaults, and idempotency — enough to invoke correctly. What's missing is how the returned jobUid is meant to be used (job tracking via the sibling job tools), which matters given the ingest is potentially long-running and bounded by maxItems/maxExtractionCalls.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real meaning by grouping parameters by connector type (repoPath applies to file-based connectors, omitted for granola) and by characterizing dryRun as a consent gate and maxItems as a backfill bound. It also flags the one hard constraint that matters most — scope only accepts personal/team and project is refused — before the agent reads the enum. Minor redundancy with the schema's own descriptions keeps it from a 5.

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 ("Ingest the delta from a previously connected source, resuming from its saved watermark") and immediately frames the operation as incremental rather than full-sync. The phrase "previously connected source" distinguishes it from connectSource, and the connector list makes the operating domain concrete without opening a schema.

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

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

Gives clear selection context: use this for a cheap incremental pull against an existing connection, with an explicit exclusion ("Refuses project scope") and per-connector setup guidance (granola needs a keychain key set via 'maz source add granola', file-based ones need repoPath). It never names what to call when no source is connected yet (presumably connectSource) or how to follow up on the returned jobUid, so the alternative-routing guidance is implied rather than 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 present, the description carries the behavioral burden and does well: it explains provenance namespace behavior, live counts, taxonomy metadata, and the caveat that registered predicates may be unused. It does not explicitly state permissions or side effects, though 'Return' and 'LLM-free' strongly imply a safe read-only 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?

The description is front-loaded with the core purpose and every clause contributes useful information. The first sentence is long and dense with nested parentheticals, which slightly reduces readability, but it remains efficient for a complex ontology introspection tool.

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?

An output schema exists, so the description need not fully explain return values. Given that, it provides complete context: what is returned, how custom kinds appear, when to call it, and a caution about unused predicates.

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 and full schema coverage, so parameter semantics are not a concern. The baseline for a parameterless tool is 4.

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 a concrete resource, 'the ontology you navigate by', then enumerates relation predicates, entity kinds, namespaces, and event types. It also distinguishes the tool's role by saying to call it before filtering neighbors/relations/entities, making it clearly identifiable among siblings.

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 explicitly advises calling once to learn the vocabulary before filtering neighbors/relations/entities, and it points to relations as the way to confirm a predicate is actually in use. It lacks an explicit when-not statement, so it falls short of a full 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 present, the description carries the disclosure burden and does well: it declares the operation read-only, notes that it scans the entire vault (a cost signal), and flags `nearDuplicates` as "non-blocking lint signal only" so the agent won't treat it as an error. It does not quantify scan cost or note whether results stream or are returned in one payload, 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?

A single dense sentence that front-loads the action, then lists categories with backticked names and tight parenthetical definitions. The final independent clause carries the scope/arity constraint. No sentence is redundant.

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

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

An output schema exists, so return values need not be explained, and the read-only, whole-vault, no-argument contract is fully stated. The only material gap is the absence of any indication of runtime cost or result-volume expectations for a full-vault scan, which matters for an agent deciding when to invoke 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 takes zero parameters, so there is no schema semantics to add; the description correctly confirms "takes no arguments" and explains that scope is implicitly the whole vault. Baseline 4 applies for a 0-param tool.

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 ("run a read-only health check over the markdown vault") and then enumerates all six check categories with a definition of each, including the precise thresholds (`cosine 0.92`). An agent knows exactly what this tool inspects and can distinguish it from `listInsights` or `listDupCandidates` at a glance.

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

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

Usage is implied by the tool's nature (a health check) and the scope note "takes no arguments; scans the whole vault" clarifies it is an all-in-one sweep. However, it never states when to prefer this over related siblings like `listDupCandidates` (overlapping with `nearDuplicates`) or `listInsights`, and offers no when-not guidance for large vaults.

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 still discloses two meaningful traits: results are sorted by recency, and bodies are omitted to keep responses lightweight. It does not discuss pagination behavior or what happens when limit is exceeded, but with an output schema present that burden is partly absorbed elsewhere.

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, both load-bearing: the first defines scope and ordering, the second defines what is returned and where to go for more. No filler and the key scoping constraint is front-loaded.

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

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

For a four-param optional-filter list tool with a 100%-covered schema and an output schema, this covers scope, ordering, and payload shape. The only gap is pagination/limit interaction, which the schema's defaults and maximum largely cover.

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 each parameter's meaning is already documented. The description adds only that filters are optional and combinable ('and/or'), which is marginal value on top of an already complete 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?

States a specific verb and resource (list vault documents) plus the ordering guarantee (most-recently-updated first) and the filter set. It also names the sibling readDocument, so an agent can tell listing apart from fetching a single document 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?

Explicitly routes the agent: use this to enumerate, call readDocument when a full body and edges are needed. That is a clear when-to-use plus named alternative, though it gives no guidance on when this tool is the wrong choice versus query/recall-style 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 burden and does disclose key traits: results are advisory-only ('need human review'), auto-merged pairs are filtered out, and the source is a post-consume sweep. It leaves unstated that the operation is read-only, whether the list is paginated or how fresh it is, which keeps it out of the top band.

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

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

Two sentences, front-loaded with the primary scope and followed by the exclusions and next action. Every clause earns its place; nothing is repeated from the schema or annotations.

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

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

A simple 0-param read whose return values are covered by the output schema, so the description only needs scope and follow-up — both present. Minor gap: no statement of read-only safety or whether an empty list is a normal outcome, which matters given the absent annotations.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond what the empty schema already shows. Baseline for a 0-param tool applies; no param text is needed.

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

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

Specific verb + resource with full scope: 'List entity pairs the post-consume dedup sweep flagged as likely cross-device duplicates.' It even carves out what is excluded (auto-merged strong-identifier pairs), so an agent can distinguish this from mergeEntities or listInsights without opening a schema.

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

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

Explicitly routes the agent forward: 'Call mergeEntities on a pair to consolidate' and names an alternative surface ('maz review dups for the interactive CLI view'). It does not state a when-not-to-use condition (e.g., after a full merge pass), but the follow-up path is unambiguous.

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

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

With no annotations, the description carries the burden and does well: it discloses the read-only nature, the default filter, the sort order (most-confident first), and what each row contains. It stops short of stating permission requirements or pagination behavior beyond the limit parameter, 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 purpose and default, then alternatives, then sibling pairings — a logical order. The parenthetical about citation format is slightly dense but still earns its place by clarifying output shape.

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

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

For a read-only list tool with a full output schema and 100% schema coverage, the description supplies everything an agent needs: default behavior, state alternatives, ordering, and the sibling workflow. No gaps remain.

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 state enum is fully documented in the schema, so the description's restatement of state values adds little. It does reinforce the default and the ordering, but limit and scopes semantics come entirely from 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?

States a specific verb (List) plus resource (synthesized insights) and scope (by lifecycle state), and explicitly frames itself as 'the Insight Inbox read surface', distinguishing it from get, dismissInsight, and triggerReflection.

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 default behavior (hot insights), gives the exact escape hatches for other states (state=demoted/dismissed/all), and routes to the correct siblings for inspecting, dismissing, and generating insights. Nothing is left 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. It usefully discloses that only running jobs plus a bounded 'recent history' are returned, which is real behavioral context, but it omits retention window, ordering, and pagination/result limits.

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

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

One sentence, front-loaded with the resource and scope, with the optional filter clause last. Nothing 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?

An output schema exists so return values need no explanation, and the single optional parameter is fully specified. The only gap is the unquantified 'recent history' window and lack of result-volume guidance for a list 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 100% and the single enum parameter is fully documented in the schema, including the absent-means-all behavior. The description's 'optionally filtered by state' merely restates 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?

Specific verb ('Return') plus resource ('currently-tracked background jobs') and scope ('running and recent history'). It is clearly distinct from the mutation sibling cancelJob, though it never names that relationship 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?

Usage is only implied: an agent can infer this is the read-side counterpart to cancelJob, but the description never states when to call it versus alternatives or that it should be paired with cancelJob to find a job ID.

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 does so for the key traits: it declares the operation read-only and enumerates returned fields (name, version, description). It doesn't discuss errors or empty states, but for a zero-parameter read tool the risk surface is minimal.

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 clauses: what it lists, what it returns, and how presets get created. Every sentence earns its place and the core purpose is front-loaded.

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

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

For a no-argument read tool with an output schema, the description supplies everything an agent needs: the meaning of the resource, the field set, read-only status, and the fact that this tool cannot create presets.

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

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

The tool takes no parameters, so the baseline is 4. The description correctly says nothing about filtering inputs, matching the empty 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?

States a specific verb and resource ('List the presets currently active') and even defines what a preset is in this system ('steering this agent's operating instructions'), which no sibling tool name conveys. An agent knows exactly what it gets back.

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

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

The final sentence explicitly rules out the obvious wrong assumption by saying presets are installed via the `maz preset install` CLI, not by agents — a clear exclusions signal. There are no true alternatives among the siblings, so the absence of a 'use X instead' pointer is not a gap.

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 burden; it does disclose 'Read-only', which is the key safety signal. It also enumerates the data returned (connector, stream, items ingested, last advance time). It stops short of pagination, volume, or auth expectations, so it's adequate rather than rich.

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

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

Two sentences, front-loaded with what is listed and the parenthetical field list that removes ambiguity, then 'Read-only.' as a terminal safety note. Dense but every clause adds information; the first sentence is long but not padded.

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

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

Zero parameters, an output schema that covers return shape, and a stated read-only guarantee mean little more is required. The only residual gap is operational context — how large the result can be or whether unconnected-but-available connectors are distinguished from connected ones.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies an unfiltered global listing with no arguments needed.

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 pair: lists available external ingest connectors (with an example, local-git) plus the per-source resume watermark. The example connector and enumerated returned fields make the scope concrete. It doesn't explicitly name siblings like connectSource or ingestSource, 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?

Usage is implied — check what connectors exist before connecting, and check progress of existing ingests — but the description never says when to call this versus connectSource, ingestSource, or recordSourceRef. No exclusions or prerequisites are given, leaving 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?

With no annotations, the description carries the full behavioral burden and does well: it discloses destructive effects (source row removed), side effects (relations, facts, and mentions repointed), audit logging, and specific error conditions. It stops short of mentioning permissions, authorization requirements, or explicit irreversibility.

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 action and uses three tight sentences with zero waste: operation mechanics, audit behavior, and error returns all 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?

Given the output schema and fully described input schema, the description is nearly complete for invocation: it explains behavior, side effects, and error modes. It misses only usage guidance and permission/auth context for this 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 100%, so the parameter descriptions already provide detailed ULID semantics and constraints. The tool description reinforces source/target roles but adds no syntax or format details beyond what the schema provides.

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: merging a source entity into a target entity. It explains the operation's mechanics—repointing relations, facts, and mentions, then deleting the source row—which clearly distinguishes it from sibling tools like deleteEntity or updateEntity.

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 does not say when to use this tool versus alternatives such as deleteEntity, updateEntity, or listDupCandidates. It provides no explicit context, prerequisites, or exclusions to guide tool selection.

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

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

With no annotations, the description carries the full load, and it does disclose the key behavioral trait: the default view is point-in-time NOW with only currently-valid, non-superseded edges, plus the fact that limit caps neighbors across all hops. It says nothing about permissions, scope enforcement behavior, cost of deep walks, or what happens when the walk is truncated by limit — meaningful gaps for a traversal 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-loads the core action and return shape, then layers defaults, time modes and the limit cap. Dense but nearly every clause carries information; the 'LLM-free graph walk' framing is the only clause that is more rhetorical than operational.

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

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

Covers the essentials for an 8-parameter traversal tool: seed forms, depth, the three time modes, predicate filtering, scope defaults and the cross-hop limit cap. Since an output schema exists, it need not describe the return payload, and its remaining omission (pagination/truncation behavior and permission requirements) is minor but real.

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 each parameter is thoroughly documented in the schema (seed ref formats, depth 1–6, limit, scopes, at/asOf semantics). The description restates depth, limit default, includeInactive, predicate filtering and time anchors, adding emphasis but little meaning beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb and resource — 'Expand an entity's neighborhood up to 6 hops' — and names exactly what comes back (hydrated neighbors plus connecting relations, hop-tagged direction). It is clearly not a generic query, but it never contrasts itself with plausible siblings like relations, getEntityContext, or recall, leaving disambiguation 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?

Gives a concrete usage pattern ('pass a recall anchor as the seed and traverse the structure yourself') and explicit mode selection guidance: default NOW view, includeInactive=true for full history, or at/asOf for time travel. No statement of when NOT to use it versus sibling graph tools, so it stops short of a 5.

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

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

Annotations are empty, so the description carries the full burden and does well: it discloses idempotency (already-asserted promotion is a no-op), the trust-quarantine model, and the supersession exclusion semantics. It omits reversibility (whether retractFact can undo a promotion) and any notes on what the call returns, leaving a small but real gap for a mutation.

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, then the rationale, then the behavioral guarantee. No sentence repeats the name or the schema, and the idempotency note is placed where an agent would look for safety information.

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

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

With an output schema present, return values need not be explained, and the trust-model context is thorough for a two-parameter mutation. The remaining gap is the absence of guidance on undoing a promotion or on what happens to dependent edges, which matters for an operation whose whole purpose is changing assertion state.

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% — both `name` and `scope` are documented in the schema, including the E_PERMISSION case for team scope. The description adds no parameter-level detail beyond that, so the baseline 3 applies; the schema does the work here.

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 opens with a precise verb+resource+state transition: 'Promote a proposed relation to asserted'. It further distinguishes the operation by explaining the source of the input (connector-ingested fact) and the resulting behavior change (behaves like a user-authored edge), so an agent knows exactly what class of operation this is versus siblings like relate or relateBatch.

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 context on when this applies — facts from external sources land status=proposed, surface in recall, and are excluded from supersession until confirmed. That tells the agent when promotion is needed. It does not name an alternative tool or state when-not to use it (e.g., how to create a fresh edge instead via relate), so it stops short of explicit routing.

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

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

With no annotations, the description carries the full behavioral burden and does so well: single SELECT/WITH statement only, writes rejected, read-only connection, scopes pre-filtered, and no WHERE scope clause needed. These are exactly the safety and execution traits an agent needs.

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 and safety constraints, then adds scope behavior efficiently. Every sentence contributes operational context without redundant restatement of the schema.

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 output schema and fully described parameters, the description is complete enough to call the tool correctly. It covers the SQL surface, safety constraints, scope semantics, and the dependency on introspect for column knowledge.

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 useful meaning beyond the schema by explaining that the views are pre-filtered to the requested scopes and by directing the agent to introspect for columns.

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: run a read-only SQL SELECT over curated views. It explicitly positions the tool as an analytical escape hatch for questions the structured entities/count filters cannot express, which distinguishes it from sibling 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?

Gives a clear use condition—questions that structured entity/count filters cannot express—and points to introspect for view columns. It also explains scope defaults and how to include team rows, leaving little ambiguity about when and how 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 the full burden and does explain the returned sections, observation projection, and graph pivot behavior. However, it omits operational behavior such as missing-document errors, permissions, and an explicit statement that reading has no 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?

The main action and return contents are front-loaded in a single dense paragraph with no wasted preamble. It is somewhat complex due to the observation projection and graph-walking instructions, but those details are relevant to understanding the result.

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?

An output schema exists, so the description need not fully explain return values, but it still gives useful semantic context for the document, links, backlinks, and observations. It is nearly complete for a read operation, lacking only edge-case behavior such as missing documents.

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 documents the path/documentUid alternative with examples and the exactly-one constraint. The description repeats the selectors but adds no new parameter semantics beyond what the schema provides.

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: 'Read one vault document by path or documentUid', and lists exactly what is returned. This clearly distinguishes it from sibling tools such as listDocuments, writeDocument, and editDocument.

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 clearly frames usage as fetching a single document and notes that exactly one of path or documentUid should be provided. It also points to get for querying projected observations, but does not explicitly contrast with listDocuments, getBacklinks, or writeDocument.

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