Muninn by Bizat

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

Annotations only declare the safe/mutating profile (readOnlyHint=false, idempotentHint=false); the description adds the critical behavioral facts beyond them: single-use, 10-minute expiry, and the instruction not to persist or repeat the link. It also tells the agent how to present it (clickable) — well beyond structured fields.

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

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

Front-loaded with purpose, then triggers, then behavior. The closing sentence is a multi-clause instruction list that is slightly dense but each clause (works once, 10-minute expiry, don't save/repeat, re-call if expired) carries distinct operational value.

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

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

With no output schema and no parameters, the description fully covers what is returned (a clickable sign-in link), its lifecycle (one use, 10 minutes), and handling on expiry. An agent has everything needed to call and use it correctly.

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

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

Zero parameters, so there is nothing to document and the baseline of 4 applies. The schema description coverage is trivially 100% for an empty object.

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

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

States a specific verb+resource ('Get a link to open Muninn in the browser') and immediately qualifies it as a one-time passwordless sign-in link to the web app/dashboard. None of the ~80 sibling tools do this, so it is unambiguously distinguishable.

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

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

Explicitly enumerates trigger phrases ('Muninn link', 'app link', 'login or sign-in link', 'open, see or log into Muninn') and closes the loop on the alternative action when expired ('call this tool again for a new one'). 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?

Annotations only state readOnly=false, destructive=false, non-idempotent, openWorld=false; the description adds a great deal beyond that: source stored in full never a link, artifacts deliberately excluded from semantic search, the return shape {success, memoryId, format, url, length, connect}, sandboxed iframe on a separate origin, the connect/CORS gating rule for fetch(), and that editing replaces in place with the public link refreshing automatically.

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 contrast, and the sectioned structure (LINKS / READING / EDITING / HANDLES) makes it scannable. It is long, however, and partially duplicates schema content — the mime enumeration and connect constraints are restated from parameter descriptions — which costs a point.

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

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

For a 9-parameter write tool with no output schema, the description covers the return shape, the edit lifecycle, handle scoping, sandbox/link behavior, and routes to muninn_help for full rules. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema descriptions are already detailed, so the baseline is 3; the description nonetheless adds the rationale that makes parameter choices meaningful ('artifacts are deliberately excluded from semantic search, so give a clear title and tags — that is how they are found again') and explains the default-handle behavior in prose. It does not re-list per-parameter syntax beyond the closed format set, which is already in 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+resource ('Store a text-based artifact you generated') and enumerates concrete artifact types (markdown, csv, json, mermaid, svg, html). It explicitly draws the boundary against the nearest sibling: 'not for notes or facts about the user; those are muninn_memory_add.'

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

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

Gives explicit when-to-use ('OUTPUT you produced'), explicit when-not ('not for notes or facts about the user'), and names alternatives for both the wrong case (muninn_memory_add) and the deferred case (muninn_memory_update / muninn_memory_anchor_replace / muninn_memory_append since there is no update tool). Handle selection is also conditioned: 'Pass handle only when the user says which 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?

Annotations cover the safety profile (destructiveHint=true, idempotentHint=true, openWorldHint=true), and the description adds substantial context beyond them: the sandbox blocks fetch()/WebSocket for undeclared hosts, Muninn's own hosts are refused here, the whole list is replaced, and a published artifact's public copy updates in the same call. It also surfaces two non-obvious consequences an agent could not infer — the list is shown to every reader of the page, and the host must answer Access-Control-Allow-Origin: * because the frame origin is null.

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 verb+resource and the primary use case, then layers constraints and warnings in descending priority. It is a single dense paragraph running long, and the CORS/key-mirror digression could be split or trimmed, but nearly every clause carries actionable information and nothing is padding.

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

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

Even with no output schema, the description names the return shape ({success, artifactId, connect}) and covers hostname format, count limit, clearing behavior, public-copy propagation, and failure fallbacks. An agent has everything needed to call this correctly on the first attempt without discovering the sandbox rules by error.

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 contributes real constraints the schema does not encode: bare lowercase hostnames only, no scheme, path, port, wildcard or IP, and a security rationale for declaring 'exactly what the source calls and nothing more.' It also restates the [] / null clearing semantics with the consequence ('returning the artifact to Muninn-only fetches').

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 precise verb triple and resource: 'Declare, change or clear the outside hosts an html/svg artifact may fetch data from at runtime.' This is unmistakably distinct from siblings like muninn_artifact_add, muninn_artifact_publish, or muninn_mirror_connect, and names its own scope (runtime fetch allowlist) rather than a generic artifact edit.

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 three concrete triggers (a dashboard/chart reading an external API, the user saying 'let it load live data from X', or muninn_artifact_add warning that a host is undeclared) and an explicit exclusion ('Not needed for <script src>, images, fonts or styles from a CDN'). It also routes to an alternative (mirror the data into a Muninn json/csv artifact and fetch /raw) when CORS or a key blocks direct fetching.

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

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

Annotations already establish readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the returned payload (source, format, title, provenance, published/publicUrl, expiresAt/expired), that a published link auto-refreshes, and that `rev` must be returned as `expectedRev` on later writes or the write FAILS rather than clobbering a concurrent edit. The conflict-detection semantics are the kind of trait annotations cannot express.

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

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

Front-loaded with the core action and return contents, then the write-back routing, then the rev/expectedRev caveat. The final sentence is long and dense, and a few clauses (e.g. the parenthetical field list) border on enumeration for its own sake, but every sentence carries actionable information.

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

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

With no output schema, the description must carry return-value disclosure, and it does, enumerating the fields returned and the conditional publish/expiry fields. Combined with the write-path and revision guidance, nothing an agent needs to call this 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 adds cross-tool meaning the schema cannot: the artifactId IS the memoryId, so the same value is what you pass to the memory write tools. That reframes the single parameter usefully, exceeding the schema's 'full UUID or unique prefix' note.

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 ('Retrieve a stored artifact by ID') and immediately distinguishes itself from siblings like muninn_artifact_list by scoping to a single artifact, and clarifies the artifactId/memoryId identity that separates it from muninn_memory_get. An agent can route correctly 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 context ('continue working on something a previous session... produced') and, more valuably, routes writes to muninn_memory_update / muninn_memory_anchor_replace / muninn_memory_append while stating there is no muninn_artifact_update. It stops short of saying when to prefer this over muninn_memory_get, which retrieves by the same identifier.

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

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

Annotations already declare readOnly/destructive/idempotent, but the description adds substantial behavior beyond them: backed by a D1 index rather than a KV scan, returns slim rows without source bodies, and reports expired links as published:false, expired:true. It also discloses that it returns a `handles` list, which is non-obvious side output.

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 long but front-loads the core capability, then layers return shape, performance rationale, use cases, and cross-tool routing with no filler. Every sentence carries distinct information an agent needs.

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

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

With no output schema, the description fully specifies the returned row fields, the optional expiresAt, the derived expired state, and the extra `handles` collection. Nothing an agent needs to call or interpret this tool 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 by explaining that the returned `handles` array supplies the valid values for the `handle` parameter and that a link past expiry surfaces as published:false/expired:true. This goes past restating schema text.

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

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

States a specific verb (List) and resource (stored artifacts) with ordering (newest first) and scope (optionally one format or one handle). It also implicitly distinguishes itself from muninn_artifact_get by noting it is 'cheap to call before deciding what to fetch' since it returns no source bodies.

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

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

Explicit when-to-use cases are given: 'see what you have already made for this user' and 'answer what have I shared publicly.' It also routes editing away from a non-existent sibling by stating 'To edit any row, pass its artifactId as memoryId to muninn_memory_update — there is no muninn_artifact_update.'

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?

Goes well beyond the destructive/idempotent annotations by naming exactly what breaks: the old named address stops working immediately with no redirect, shared links break, while the token link is unaffected. It also discloses refusal semantics (target name collision, non-owned handle = nothing changes) and the full return shape.

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 trigger phrases, then the critical breaking-change warning is visually flagged so it is not lost. The opening sentence's four paraphrased user quotes are slightly redundant, but the overall length is earned by the number of refusal and side-effect 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?

For a destructive, open-world mutation with no output schema, the description covers prerequisites (owned handle, not suspended), failure modes, irreversible side effects, and even enumerates the returned fields — nothing an agent needs to call it safely 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 the schema does not: a new `name` requires the Paid plan, and an omitted `name` silently keeps the current name while a collision causes refusal. The `handle` constraint (must be owned, list via muninn_artifact_list) is largely mirrored 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 and resource ('Move an artifact to another of the user's handles') and pins the domain model ('an artifact lives under exactly one handle'), which cleanly separates it from siblings like muninn_artifact_name, muninn_artifact_publish, or muninn_bundle_edge_move.

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 user phrasings that should trigger it ('move this to my company handle', 'file it under a different handle') and explicit when-not conditions: the target must be a held handle, suspended-handle artifacts cannot move, and it 'Does not publish or unpublish anything' — routing the agent away from publish/unpublish 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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them: naming does not publish and does not change read access, name:null makes the address stop working immediately while the token link survives, names are unique per handle, and a durable twin on muninn.bizat.co is created. Plan behavior (Paid for new/changed names, free for removal/re-apply) is also disclosed. This is exactly the additional context annotations cannot carry.

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 trigger phrases and the core operation, then layers on constraints, the Plan section, and the return shape. Efficient for its density, though there is minor redundancy between the 'durable twin' sentence and the returned durableUrl field.

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

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

No output schema exists, but the description enumerates the return shape ({success, artifactId, handle, slug, namedUrl, durableUrl}) and covers preconditions, plan constraints, removal behavior, and the sibling tool for handle changes. An agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the null-removal semantics and plan requirement. The description's extra notes (null stops the address immediately, uniqueness is per-handle, the returned slug/namedUrl) add some value but largely restate or extend the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource: give a published artifact a readable address under its handle, rename it, or remove the name. It explicitly distinguishes itself from muninn_artifact_move ('To change WHICH handle the page is under, use muninn_artifact_move') and muninn_artifact_publish ('The artifact must already be published'), so an agent can route correctly 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?

Gives concrete trigger phrases ('name this page', 'give it a nicer url', 'rename that link'), names the alternative tool for the adjacent operation, and states the precondition (must already be published) plus the plan gating for each operation. When-to-use and when-not-to-use are both covered.

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

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

Beyond annotations, it discloses critical behavior: the password is stored one-way and can never be read back, the exact password must be said back to the user because it is only visible once, and forgotten passwords are replaced rather than recovered. It also explains cross-artifact password sharing, the 401 failure mode for data fetches, and clarifies the password is a page gate rather than artifact encryption.

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 trigger phrases, and every major warning is relevant. It is somewhat long and repeats the critical 'cannot read back / say it back' point, but the repetition is purposeful for a destructive, irreversible password operation.

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

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

Although there is no output schema, the description supplies the return shape {success, artifactId, hasPassword}. It also covers prerequisites, destructive reversibility constraints, password sharing interactions, and fetch failure behavior, which is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents password length, null semantics, and artifactId. The description adds operational meaning beyond the schema by explaining that null removes the password, that identical passwords across artifacts create one shared lock, and that different passwords can cause 401 on cross-artifact data fetches.

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: set/change/remove the password a reader must type to open a published artifact. It distinguishes this from publish behavior by noting the artifact must already be published and by explicitly naming muninn_artifact_publish as the prerequisite.

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

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

It gives explicit user phrases that should trigger the tool (password protect this, put a password on that link, lock this page, change/remove password) and states the prerequisite that the artifact must already be published. It also explicitly says to pass password: null to remove the password and make the link open freely again.

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

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

Annotations already declare destructive/openWorld/idempotent, but the description adds much more: the link stays LIVE and reflects later edits, is unguessable, requires no login, is not search-indexed, and reveals plan gating for named URLs. It also documents re-publish semantics (keeps link, can change expiry, expired publish mints a new link).

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 trigger phrases, and every clause carries information. The trigger enumeration and the expiry/idempotency explanation are somewhat verbose, but no sentence is wasted.

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

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

For a mutation tool with no output schema, the description enumerates the return shape ({success, artifactId, publicUrl, namedUrl, durableUrl, live, expiresAt}) and covers plan limits, expiry, revocation, and idempotency. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces `name` with a concrete example (chai.munn.is/my-notes), states the Paid-plan condition, and clarifies re-publish/expiry behavior, adding routing context (move first for a different handle). It does not surface the `password` parameter at all, so it is not fully additive over 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 and resource ('Share a stored artifact publicly and get back a link anyone can open'), plus the concrete outcome (an unguessable munn.is link). It clearly distinguishes itself from muninn_artifact_unpublish and muninn_artifact_move, which it names directly.

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

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

Gives explicit trigger phrases ('publish this, share this, make this public'), explicit exclusions ('never assume an artifact is public, and never publish as part of saving or editing'), and routes to the correct siblings: muninn_artifact_move to change handle, muninn_artifact_unpublish to revoke.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it explains that only the public copy is deleted while the artifact stays in Muninn, that the URL dies immediately for everyone, that any named address also stops resolving, and that republishing mints a NEW link so the old one is permanently dead. That is exactly the extra context needed before an irreversible action.

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 action and the intent triggers before the consequences, then closes with the return shape. Six short sentences, each carrying distinct information — scope of deletion, side effect on named addresses, irreversibility, safety on the no-op case, response fields — with no filler.

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

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

With no output schema present, the description supplies the return shape ({success, artifactId, wasPublished}), and the annotations cover the safety profile. Between them, an agent has everything needed to decide whether to call this and what it will get back.

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

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

Schema description coverage is 100% for the single artifactId parameter, which already documents that a full UUID or unique prefix is accepted. The description adds no syntax, format, or naming detail beyond the schema, so the baseline of 3 for fully-covered schemas 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 (revoke/unpublish) on a specific resource (an artifact's public link) and immediately distinguishes it from its sibling muninn_artifact_publish by describing the opposite direction of the operation. An agent can identify the tool from the name plus the first clause alone.

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

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

Gives an explicit trigger list ('unpublish, unshare, make this private again, take it down, stop sharing that link') that maps user phrasing to the tool, and explicitly resolves an edge case — 'Safe to call on an artifact that was never published' — so the agent knows the no-op case is acceptable rather than an error.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuine behavioral value by specifying the exact return shape (every ancestor/descendant/depth pair, including self-pairs at depth 0), which is not in any structured field since no output schema exists.

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

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

Front-loaded with the core action and kept to two sentences. The parenthetical definition of a bundle is helpful context; the trailing 'Useful for...' sentence is slightly weaker but not wasteful.

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

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

With no output schema, the description usefully explains the closure return format, which is what an agent most needs here. For a single-parameter read tool whose annotations already cover the safety profile, this is nearly complete, minor gap being no explicit sibling routing.

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 parameter rootKey is fully documented as 'the node_key of the bundle root'. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('List') and resource ('everything beneath one item in a bundle') and clarifies the bundle concept as an ordered outline of memories. It defines the return semantics (ancestor/descendant/depth pairs) precisely, though it doesn't explicitly name a sibling to differentiate from, e.g., muninn_bundle_get or muninn_bundle_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?

'Useful for checking what a section contains' gives an implied use case, but there is no explicit when-to-use guidance and no contrast with alternatives like muninn_bundle_get. The condition selecting this over other bundle reads 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description discloses two valuable behaviors: it returns the rootKey and the id of the memory holding title/description, and it fails if the slug is already in use. There is a mild tension between idempotentHint=true and the stated failure-on-duplicate behavior, but this is not a direct contradiction.

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 concept definition before the action and return values. Every sentence carries information, though the opening conceptual framing is slightly longer than strictly needed for a caller already familiar with bundles.

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

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

With no output schema, the description usefully explains the return values (rootKey and title/description memory id) and the duplicate-slug failure mode, which is what an agent needs to chain calls correctly. Minor gap: the project and okf_type parameters are not touched on, though the schema covers them fully.

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 are already documented, setting the baseline at 3. The description reinforces that title and description are stored in a backing memory and that slug uniqueness matters, but adds little 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 defines what a bundle is (ordered outline of memories: sections and items) and states the specific action: creating a new, empty bundle. It clearly separates this from node-level sibling tools like muninn_bundle_node_create by specifying the bundle is created 'empty' at this stage.

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 establishes the creation context and implicitly positions this as a prerequisite by noting the returned rootKey is 'the key every other bundle tool takes.' However, it does not explicitly name alternatives or state when not to create a bundle, so guidance stops short of the top tier.

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

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

Annotations already declare the safety profile (not read-only, not idempotent, not destructive). The description adds real behavioral context beyond that: it discloses the persisted shape ({question, chosen, rejected[], reason, decided_by, date}), the 'decision' tag, and the link/rendering behavior. It does not warn that repeated calls are non-idempotent (duplicate decisions), which would have earned a 5.

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

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

Two sentences, purpose front-loaded, no filler. The second sentence carries dense but useful information (storage shape, linking, use case). Marginally long, but every clause earns its place.

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

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

No output schema exists, and the description states what gets persisted and linked, which is sufficient to call it correctly. For a non-idempotent mutation it could note that each call creates a new stored decision, but overall it is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by grouping the parameters into a coherent decision record ({question, chosen, rejected[], reason, decided_by, date}), letting an agent see how the fields relate rather than viewing nine isolated params.

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: 'Record a decision about a bundle' and it immediately defines the domain concept ('an ordered outline of memories') and the effect (attaches the reason to the governed item so it renders wherever that item does). An agent can tell this apart from generic memory tools. It stops short of naming the closest sibling (muninn_memory_add) as the thing it is not, so it is not 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?

'Use it for structural choices made in conversation that would otherwise be forgotten and argued again' gives a clear, concrete trigger condition. There is no explicit when-not clause or named alternative, so it falls short of the 5 bar that names an alternative 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?

Goes meaningfully beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing the one-home invariant, the refusal-with-error behavior on a second 'contains', and that 'reference' does not move the item. It stops short of describing return value or how position interacts with existing siblings.

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

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

Three sentences, front-loaded with the core action before the relation nuances. Dense but each sentence carries information; only the parenthetical definition of a bundle is arguably surplus.

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 annotations and no output schema, the description covers the essential invariants and error behavior. Missing details are minor: return shape and how explicit positions order against existing siblings.

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

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

Schema coverage is 100%, so the schema already documents all four parameters, including the same relation semantics and the position default. The description's relation explanation adds only marginal value beyond the schema, and position is not elaborated at all. 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?

States a specific verb+resource ('Link two items in a bundle') and clarifies the resulting structure ('placing the child under the parent'), even defining what a bundle is. It distinguishes the two relation modes clearly enough that an agent knows exactly what operation it is invoking.

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 guidance on choosing between relation='contains' and relation='reference', including the consequence of each. It does not, however, say when to prefer this tool over siblings like muninn_bundle_edge_move or muninn_bundle_edge_remove, so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the mutation/safety profile is covered. The description adds the reordering effect and positional outcomes, but says nothing about permissions, what happens to existing edges, or error behavior for an invalid sibling key.

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 operation before the parameter mechanics, and every sentence carries meaning. Slightly dense with repeated key terminology, but no wasted 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 focused, idempotent mutation with full schema coverage and an annotation-declared safety profile, the description supplies enough to invoke it correctly. Only edge cases (invalid sibling, cross-parent moves) remain unaddressed.

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

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

Schema coverage is 100%, so all four parameters are already documented with the same before/after semantics. The description largely restates this and only adds the combined case ('both null appends at the end'), which is one genuine increment over 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 (Reorder) and resource (an item among its siblings in a bundle) and disambiguates 'bundle' with a parenthetical definition. An agent can distinguish this from muninn_bundle_edge_add/remove and muninn_artifact_move without opening any schema.

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

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

The description explains the semantics of beforeKey/afterKey, which implies when to use the tool, but never explicitly contrasts it with sibling reorder/edge tools such as muninn_bundle_edge_add or muninn_artifact_move, nor does it state prerequisites or failure conditions. Usage is implied rather than guided.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful blast-radius context beyond that: nothing is destroyed except the link, and an orphaned child is promoted to a top-level item — a non-obvious post-condition that prevents an agent from assuming data loss.

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

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

Three short sentences, front-loaded with the action, then the non-destructive guarantee, then the edge-case outcome. No filler and nothing redundant with 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?

There is no output schema, and the description supplies the key return-relevant fact (child becomes top-level if left homeless), which is what an agent most needs. Missing only failure behavior for a non-existent edge, which is largely covered by the idempotentHint annotation.

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

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

Schema description coverage is 100% for both node_key parameters, so the schema already carries the semantics and the baseline is 3. The description implies the parent/child link being removed but adds no format, nesting, or ordering details beyond what the schema states.

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 — 'Unlink an item from its parent in a bundle' — and defines the bundle domain parenthetically as an ordered outline of memories. It also draws the boundary against the neighboring node-deletion tools by asserting 'Neither item is deleted, only the link between them', so an agent can tell it apart from muninn_bundle_node_delete and muninn_bundle_edge_add.

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 context of use is implied by 'unlink an item from its parent', and the clarification about non-deletion steers away from delete tools. However, there is no explicit when-to-use statement and no routing to alternatives such as muninn_bundle_edge_move (reparenting) or muninn_bundle_node_delete for actual removal of an item.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the shape and ordering of the payload (outline order + generated TOC) in a portable JSON format, which matters because there is no 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?

Two sentences, zero filler, with the output format defined first and the disambiguation to the sibling placed at the end. Every clause carries information.

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

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

With no output schema, the description does the necessary work of describing the returned object's contents and ordering. Minor gaps remain, such as whether the result is returned inline as JSON or as a downloadable artifact and any size constraints, but the essentials for correct invocation are present.

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

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

Schema description coverage is 100% and the single rootKey parameter is already documented as 'the node_key of the bundle root to export.' The description adds no format or syntax detail for the parameter, so the baseline 3 applies.

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

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

States a specific verb (Export), resource (a bundle), and the concrete output (an OKF v0.1 object, a portable JSON format containing memories in outline order plus a generated table of contents). It also names the sibling it is not (muninn_render_bundle), so an agent can separate it from the render path 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: 'For a readable document, use muninn_render_bundle,' which gives a clear alternative and the condition that selects it. It does not spell out exclusions or prerequisites (e.g., whether the bundle must exist or be non-empty), so it stops just short of the top band.

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

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

Annotations already carry readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context the annotations do not: children are returned unresolved by default, and resolve:true triggers hydration plus memory previews, which implies extra cost/depth when enabled.

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

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

Two sentences, zero filler, with the core behavior front-loaded and the optional flag described second. The parenthetical definition of a bundle is compact and earns its place.

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

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

With only two params, full schema coverage, rich annotations and no output schema, the description needs to explain the return shape and the default-vs-resolved distinction, which it does. It stops short of describing ordering guarantees or how deep 'directly beneath' goes, a minor gap for an outline 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 rootKey is already documented as 'the node_key of the bundle root'; the description's resolve explanation largely restates the schema's own 'hydrate child node details (slug, type, and a preview...)' wording. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource ('Look at one bundle') and goes further by defining what a bundle is ('an ordered outline of memories for a book or project') and what it returns (root plus items directly beneath). That 'directly beneath' phrasing implicitly separates it from muninn_bundle_closure, but no sibling is named explicitly.

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

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

Usage is implied rather than stated: 'Look at one bundle' plus the resolve:true hint tells an agent how to inspect a single bundle's immediate children, but there is no explicit when-to-use/when-not guidance and no pointer to muninn_bundle_list or muninn_bundle_closure as alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered elsewhere. The description adds domain meaning for 'bundle' but says nothing about result ordering, pagination, or scale of the listing, which would be genuinely additive.

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

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

Two compact sentences, no redundancy, with the core action front-loaded and the optional filter trailing. Every phrase earns its place.

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

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

For a simple zero-required-parameter list tool with full schema coverage and annotations covering safety, the definition is nearly sufficient. Only the omission of return shape/pagination context, absent since there is no output schema, keeps it short of full completeness.

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

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

Schema description coverage is 100% and the single 'project' parameter is already documented in the schema. The description's 'filter to one project' merely restates that; it adds no syntax or format detail beyond the structured field.

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

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

States a specific verb (List) and resource (bundles), and the parenthetical gloss 'ordered outlines of memories for a book or project' tells an agent what a bundle actually is. It is separable from bundle_get/bundle_create by the verb, though it never explicitly contrasts itself with those 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?

The only guidance is 'Optionally filter to one project,' which is really parameter behavior rather than when-to-use-this-vs-alternatives context. There is no statement of when to reach for bundle_list versus bundle_get or bundle_closure, so usage is implied rather than spelled out.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description only needs to add context — and it does: it discloses the duplicate-slug failure mode and explains that 'contains' is a single canonical home versus a second 'reference' link. It stops short of describing the response payload or what position/ordering guarantees apply on append.

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 scope, and every sentence carries information. It is slightly long and duplicates the okfType and relation explanations that already live in the schema, which is the only 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?

For a mutation with no output schema, the description should say what comes back (presumably the created node or its key) so the agent can chain follow-up calls like node_repoint or render_bundle. Ordering behavior on append ('Omit to append') is left entirely to the schema, and the relationship to muninn_bundle_nodes_create is unaddressed.

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

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

Schema coverage is 100%, so the schema already documents all six parameters, including okfType and relation. The description restates the okfType values and relation semantics but adds no new meaning, and it never mentions position, memId, or parentKey beyond the vague 'under a section'. 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?

States a specific verb and resource ('Add an existing memory to a bundle... as an item under a section') and parenthetically defines what a bundle is. It also explicitly distinguishes itself from muninn_bundle_create, so an agent can separate the two without opening a schema.

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

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

'Use it to place something the user already wrote, such as a chapter's full text or its summary' gives a concrete use case, and the sentence contrasting with muninn_bundle_create routes the agent away from the wrong tool. It does not address the near-sibling muninn_bundle_nodes_create (bulk/plural variant), which is the most likely confusion.

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

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

Annotations already flag destructive=true and idempotent=true, but the description adds substantial behavioral context beyond them: the cascade refusal rule, the strong 'never deletes a memory the user wrote' guarantee with its three-part precondition for deleteBackingMeta, and the dryRun-by-default safety behavior. That is exactly the kind of context annotations cannot express.

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

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

Purpose is front-loaded in the first clause and every subsequent sentence carries an actual rule rather than filler. It is a single dense paragraph with nested conditions that read a little run-on, but no sentence is wasted.

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

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

For a destructive, no-output-schema tool this covers what an agent needs: what is removed (node plus links), the refusal conditions, the memory-preservation guarantee, and the dryRun default. Nothing material is left unstated.

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

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

Schema coverage is 100%, so the schema already documents all four parameters and the baseline is 3. The description goes further by explaining the interaction semantics: cascade removes 'the whole section,' deleteBackingMeta fires only when the memory holds nothing but a title/description and has no other referrers, and dryRun defaults to a non-committing report.

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 ('Remove an item or section from a bundle') and defines a bundle inline as 'an ordered outline of memories for a book or project,' with the important scope note that all links to/from the node go too. It stops short of naming a sibling alternative (e.g. muninn_bundle_nodes_remove or muninn_memory_delete), so an agent still has to infer the single-vs-multiple split.

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 conditional guidance: it refuses a section that still has items unless cascade=true, and it deletes the backing memory only under three explicit conditions. However it never points to the alternative tool for bulk removals or explains the memory-vs-node deletion boundary against muninn_memory_delete.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the mutation profile is covered. The description adds meaningful semantics beyond that: exactly what is preserved (key, position, links, children) versus what changes (the shown memory), which is the key behavioral fact for this 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?

Three tight sentences, front-loaded with the core action, followed by preservation semantics, usage trigger, and the parameter format note. The parenthetical defining 'bundle' earns its place by grounding the domain term, and nothing is redundant.

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

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

For a 2-parameter mutation tool with annotations covering safety and no output schema, the description supplies purpose, usage, and preservation behavior. It omits failure/error behavior and permission requirements, but the annotations and simplicity of the tool make those minor gaps.

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

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

Schema coverage is 100% and both parameters are documented there. The description's note that newMemId accepts a full or 8-char prefix merely restates the schema's own description, so it adds no information beyond structured data. 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?

States a specific verb (repoint) and resource (an item/node in a bundle), and defines what a bundle is in-line. It clearly delineates the operation from siblings like muninn_bundle_node_delete and muninn_bundle_node_create by specifying that key, position, links and children are preserved and only the pointed-to memory changes.

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 when-to-use trigger ('when a newer memory replaces the one an item showed') and names the competing approach (removing and re-adding the item) along with its downside. It stops short of naming a specific sibling tool as the alternative, but the routing condition 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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description adds substantive behavioral context: exactly what is preserved (key, position, links, target memory), the surprising fact that rendered documents are unaffected while exported file names change, the failure mode on slug collision, and the default dryRun safety behavior. This is precisely the kind of side-effect disclosure a mutation tool 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?

Purpose is front-loaded in the first clause, followed by preservation semantics, side effects, failure mode and the dryRun caveat in a logical order. Every sentence carries distinct information with no filler.

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

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

For a mutation tool with no output schema, the description covers behavior, side effects, failure conditions and the dry-run option, and the annotations cover the safety profile. The only minor gap is that it does not describe what the tool reports back (e.g. the shape of the dryRun/commit result), but overall it is complete enough to invoke correctly.

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

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

Schema description coverage is 100%, so nodeKey, newSlug and dryRun are already fully documented in the schema (including slug rules and the uniqueness requirement). The description reinforces the duplicate-slug failure and the dryRun default but adds little syntax or format information beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb (rename/reslug) and resource (one item or section in a bundle), and defines what a bundle is ('an ordered outline of memories for a book or project'). It is clearly distinguishable from siblings like muninn_bundle_node_repoint or muninn_bundle_node_delete, and it explains precisely which attribute is being changed (the slug).

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

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

The description makes the intended use case clear (changing a node's slug) and implicitly differentiates from muninn_bundle_node_repoint by stating 'the memory it points at' stays the same. It also documents the failure condition (duplicate slug) and the dryRun default, giving the agent enough context to call it safely, though it does not explicitly name an alternative tool to use instead.

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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing transactional semantics: all-or-nothing validation (section exists, each slug free and unique within the batch), abort-on-clash that names the failing item, and mid-batch rollback. This is exactly the kind of behavioral context annotations cannot convey.

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

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

Front-loads the core purpose in the first clause, then layers on transaction semantics and the memId format note. Dense but every sentence carries useful information; slightly long for a two-parameter tool, though nothing is filler.

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

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

With no output schema, the description carries return-value opacity, but for a batch attach tool the important call-time concerns (validation order, abort behavior, rollback, id format) are all covered. The only minor gap is not describing what a successful call returns.

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 parentKey and every children field. The description adds marginal value by noting memIds accept full or short-form prefixes and by restating the batch-uniqueness of slugs, but this largely duplicates the schema. 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?

States a specific verb and resource ('Add MANY existing memories to a bundle under ONE section in a single call') and immediately distinguishes itself from the sibling muninn_bundle_node_create by framing itself as the batch alternative. An agent can tell exactly what this does without opening the schema.

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

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

Names the alternative explicitly ('instead of one muninn_bundle_node_create per item'), which gives clear selection context. No explicit when-not condition is stated, but the batch framing makes the intended usage unambiguous.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds valuable context beyond them: only links are removed, items and memories are preserved, and the return value is a count of removed links. It does not cover auth or error behavior, but the added semantics are substantive.

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

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

Three short sentences, front-loaded with the core action and scope, then preservation semantics, then return value. No filler.

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

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

For a two-parameter mutation with rich annotations and no output schema, the description covers purpose, preservation behavior, inverse operation, and return value. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema fully documents parentKey and childKeys. The description implies multiple children from one parent but adds no syntax or format details beyond the schema; 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?

States a specific verb (Unlink) and resource (items from one parent in a bundle), scopes it to several items in one call, and distinguishes it from node deletion by noting only links are removed. The inverse relationship to muninn_bundle_nodes_create further disambiguates it from 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?

Clearly indicates the operation's context: remove multiple child links from a parent without deleting the items or memories. However, it does not explicitly name alternatives such as muninn_bundle_node_delete or state when-not to use it beyond the implied preservation semantics.

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

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

Annotations already declare this is a non-read-only, idempotent, destructive mutation, so the description does not need to restate safety basics. It usefully adds that only title and/or description change and the slug is immutable, but does not explain overwrite behavior, permissions, or return behavior.

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

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

The description is a single tightly written sentence with no waste. The mutation scope is front-loaded, and the parenthetical definition of a bundle is brief and useful.

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

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

For a simple metadata-update tool with full schema coverage and annotations, the description provides enough context to call it correctly. The only minor gap is that it does not state what the operation returns, but no output schema is present and the call is straightforward.

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

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

The schema has 100% parameter coverage and documents all three parameters, including rootKey as the bundle root identifier. The description names the mutable fields and the and/or nature of the update, but adds no syntax or format details 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 gives a clear verb and resource: it changes a bundle's title and/or description, and defines a bundle parenthetically. It also distinguishes this from slug-changing operations by stating the slug never changes here, though it does not name a specific sibling alternative.

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

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

Usage is implied by the stated fields: use this to edit a bundle's title or description, not its slug. However, there are no explicit when-to-use/when-not-to-use instructions or named alternatives such as bundle creation or reslug operations.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description adds useful behavioral context that the response is a complete reference document (potentially large), helping the agent anticipate output size, though it doesn't state format or size explicitly.

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 action and return content, then the invocation condition. Nothing is repeated or wasted.

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

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

For a zero-parameter help tool with no output schema, the description tells the agent what the returned document covers, which is the key decision input. Minor gap: it doesn't note the output format or approximate size, which matters for a "full" reference document.

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; this meets the baseline for a no-param tool. The schema coverage is 100% and the empty schema matches the description's implied no-argument invocation.

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 the full Muninn help document") and enumerates what it contains: what Muninn is, usage, and the full tool and skill reference. This clearly separates it from functional siblings like muninn_onboard or muninn_skill_registry.

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: "Call this whenever the user asks for help or how to use their memory." That is a clear when-to-use rule, though it does not contrast against adjacent discovery tools such as muninn_onboard or muninn_session_boot.

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 only tell the agent this is a non-read-only, non-destructive, non-idempotent write. The description goes well beyond that: it states the exact return shape ({success, memoryId, length}), explains that length is the self-verify signal and the body is never echoed, and documents defaulting behavior and the downstream effect of hideRank on Ranking and boot.

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 return contract are front-loaded in the first two sentences, then parameter rules follow in priority order. Slightly overstuffed with em-dash asides such as "(the full body is never echoed; you just sent it)", but nothing is truly wasted.

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

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

For a six-parameter creation tool with no output schema, the description supplies the return contract and the non-obvious parameter decisions, which is the bulk of what an agent needs. It stops short of situating the call relative to append/update, leaving one ambiguity for a tool with many write siblings.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds operational rules the schema alone doesn't state as a decision rule — the concrete hideRank:true list (session state, checkpoints, carryover, logs) and the occurredAt backfill case. That is meaningful guidance beyond field-level docs.

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?

"Store a new memory with text content and tags" gives a specific verb and resource, and the return-shape sentence reinforces that this is a creation call. It does not, however, distinguish itself from near-siblings like muninn_memory_append or muninn_memory_update, which an agent could plausibly reach for instead.

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

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

There is real conditional guidance: pass occurredAt only when the event happened at a different time than now, and pass hideRank:true for operational memories. What's missing is tool-selection guidance against the other write-path siblings (append, update, anchor_replace).

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 only declare the safety profile (destructive, idempotent, openWorld); the description adds substantial context beyond that: exact-once anchor matching with no guessing, ordering requirement, delete semantics, return value {id, length}, short-form 8-char memoryId, artifact support with automatic public-link refresh, and the optimistic-concurrency behavior of expectedRev (write REJECTED, nothing written). Note a latent tension: the 'rejects if either anchor is missing' rule means a repeat call would fail, which sits awkwardly with idempotentHint=true, but the description itself is accurate and not misleading.

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 operation, then rationale, constraints, delete case, return value, artifact note, and rev guidance. Every clause is informative, though the description is dense and runs long enough that a couple of points (artifact note, expectedRev) could be tightened.

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

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

For a mutation tool with no output schema, the description compensates fully: it documents the return shape ({id, length}), concurrency handling via expectedRev, edge cases (delete, exactly-once anchors, ordering), and artifact-specific side effects. Nothing an agent needs to call this 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 adds real meaning beyond the schema: it clarifies the relationship between the two anchors (ordering, uniqueness) and, most valuably, when to use or omit expectedRev ('the rev from the read you based these anchors on', omit for read-then-immediately-write).

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: replace the span between beginAnchor and endAnchor with newText. It also implicitly distinguishes itself from whole-body editing siblings (muninn_memory_update/muninn_memory_append) by explaining it is 'cheaper than resending the whole body'. An agent can tell what this does and why it exists 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 covers when to use it (editing a large block), how to delete (newText as empty string), and the exact condition for expectedRev ('omit for a read-then-immediately-write'). It also states the failure conditions (anchors missing or appearing more than once) so the agent knows when the call will be rejected.

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?

Adds substantial context beyond annotations: returns {id, length} for self-verification, expectedRev acts as optimistic concurrency (REJECTED with nothing written if the body moved), short-form 8-char prefix accepted, and artifact behavior with automatic public-link refresh. This discloses write semantics and failure modes the annotations alone don't.

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, then layers value (cheaper, use cases, separator, return shape, concurrency, artifacts) with no filler. Dense but every sentence carries actionable information.

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

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

No output schema exists, yet the description states the return value ({id, length}) and describes the concurrency guarantee and artifact side effect. For a 4-param append tool this is complete enough for an agent 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 coverage is 100%, so baseline is 3, but the description adds usage guidance the schema lacks—specifically when to omit expectedRev ('read-then-immediately-write, or when appending blind') and the separator default behavior. This meaningfully augments the expectedRev parameter's semantics.

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

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

States a specific verb ('append') and resource ('a memory's body') with scope ('to the END'), and implicitly distinguishes from full-body update by noting it's 'cheaper than resending the whole body.' An agent can tell exactly what this does versus sibling memory 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 concrete use cases ('growing changelogs, journals, session-state, or any memory that accumulates by accretion') and contrasts cost with resending the whole body, which implies the alternative update path. It doesn't explicitly name muninn_memory_update as the alternative, keeping it just short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds that deletion spans 'all storage layers' and that ambiguous prefixes are refused with a list of matching IDs; that goes beyond what the annotations say.

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 destructive action and scope, followed by the key safety constraint. Every clause earns its place.

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

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

For a single-parameter tool with rich annotations and no output schema, the definition covers scope, permanence, and the ambiguous-ID failure mode. What's missing is minor, e.g. whether deletion cascades to references or tags in bundles.

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 still adds meaning by stating the ambiguous-prefix behavior (refused, with matches listed) and linking the short-form convention to muninn_memory_get and _update.

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?

'Permanently delete a memory by ID from all storage layers' gives a specific verb, resource, and scope, which clearly separates it from muninn_memory_get, _update, and _list.

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

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

It implies usage (delete a memory when you want it gone) and references the get/update siblings only for ID-format conventions, not as alternatives. There is no explicit when-not guidance, e.g. irreversibility or what to do if the memory is referenced elsewhere.

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

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

Annotations already cover readOnly/idempotent/non-destructive/closed-world, and the description adds substantial behavior beyond them: short-form IDs are resolved to a full UUID first, `rev` is null when never indexed, and passing it back makes a later write FAIL rather than clobber a concurrent edit. It also discloses that built-in Muninn skills come back read-only and are marked `builtIn: true`.

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

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

The core action is front-loaded in the first sentence, and every subsequent sentence carries information. It is dense with em-dash asides and the skill paragraph sits last as a related tangent, so it is slightly longer than it needs to be, but nothing is pure 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 single-parameter read tool with annotations and no output schema, the description covers return semantics (`rev` and its null case), ID resolution, and the special skill path. It omits error behavior for unknown or ambiguous prefixes, which is the only notable omission.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds semantics the schema does not: prefix IDs are acceptable and are resolved before use, and a full ID sourced from a <muninn_skills> location behaves differently (opens read-only skill instructions). That is real added meaning over the one-line schema doc.

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

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

States a specific verb (Retrieve) and resource (a single memory) and scopes it by ID, which cleanly separates it from the list/query/search siblings. The short-form ID resolution and the built-in-skill retrieval path are both named explicitly, so an agent knows exactly what this call 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?

Gives concrete conditional guidance for the `rev` value: carry it only when you read now and write later, since a read-then-immediately-write needs nothing. It also explains the one non-obvious usage path (reading a built-in skill's instructions via its <muninn_skills> id). It never states when to prefer this over muninn_memory_search/query/artifact_get when you don't already hold an ID, which is the remaining 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds only the pagination hint, which is already implied by the limit/cursor schema, and says nothing about ordering, default result size, or what the cursor encodes.

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

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

Two sentences, zero filler, with the primary purpose front-loaded before the routing guidance. Every clause earns its place.

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

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

For a read-only list tool with full annotation coverage and 100% schema coverage, the description is essentially complete. The only soft gap is the absence of any note on result ordering or return shape, which matters slightly more given there is no output schema.

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

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

Schema description coverage is 100%, so limit, cursor, and the project filter are all documented in the schema itself, including the global+project-scoped nuance. The description adds no parameter-level meaning beyond what the schema already provides, 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 ('List all memories'), the scope ('for the current user'), and a behavioral modifier ('optional pagination'). It also names the two closest siblings so an agent can distinguish this tool 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?

Explicitly routes to alternatives with the condition that selects each: muninn_memory_list_by_tag for tag filtering, muninn_memory_search for semantic search. This is exactly the when-to-use-this-vs-that guidance the dimension asks for.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety behavior is covered for free. What the description adds is the AND-matching rule, but that is duplicated verbatim in the schema's own tag description ('all must match'), and the 'D1 tag index' reference is an implementation detail rather than agent-relevant behavior. No mention of result ordering or page/limit behavior.

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

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

Three short sentences with the core behavior and the matching rule front-loaded, then use cases. No filler or redundant restatement of the name. The trailing 'etc.' makes the use-case list slightly loose but costs little.

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 filtered list with full annotation coverage and 100% schema coverage, the description supplies what is needed to invoke it correctly. There is no output schema, so the only mild gap is that it says nothing about what a result looks like or how limit/pagination behaves.

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 tags (with examples), limit (max 100, default 100) and project (global + project-scoped). The description adds no parameter detail beyond repeating the AND rule. Baseline 3 is correct when the schema carries the parameter burden.

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

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

States a specific verb and resource ('Find memories by exact tag match') and adds the matching semantics ('All specified tags must be present (AND logic)'), so the agent knows exactly what the tool returns. It does not, however, distinguish itself from closely-named siblings such as muninn_memory_search_tags, muninn_memory_list_tags, or muninn_memory_tag, which is the main ambiguity an agent faces here.

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 closing clause ('Use for session-state, carryover, person profiles, project logs etc.') gives concrete use cases, which implies when the tool is appropriate. It never states when NOT to use it or names an alternative (e.g. the non-tag list/query tools), so the agent must infer the choice from the sibling 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds behavioral detail beyond that: returned counts, most-used-first ordering, and the global+project aggregation semantics of the project parameter.

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; output shape and ordering are front-loaded, then the sibling distinction, then the parameter note. 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?

A single-parameter, read-only listing tool with annotations covering safety and no output schema to explain. Everything an agent needs to call it correctly — including the project/global interaction — is present.

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

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

With 100% schema coverage the baseline is 3, but the description adds real meaning: passing a project scopes counts to that project AND global, and omitting it returns all. That combination rule is worth more than the schema's bare 'Omit for all.'

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

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

States a specific verb and resource ('List every distinct tag'), plus the payload (counts) and ordering (most-used first). It explicitly positions itself against tag search, so an agent can distinguish it from siblings like muninn_memory_search_tags 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?

Clear context for when to use it — tag vocabulary/discovery, resolving near-miss tag names like 'github-mirror vs mirror-github'. It does not name the alternative tools explicitly, so the routing signal is descriptive rather than a direct hand-off.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds behavior those annotations cannot express: result ordering driven by the time field, order:'oldest' for timelines, and that ambiguous/missing ID prefixes surface in errors[] rather than being silently dropped. It stops short of describing pagination or result shape, but the error-reporting and ordering disclosures are genuinely useful.

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 verb and filter list, then progressively adds intersection rules, ordering, and the routing alternative. It is dense and slightly long, but each sentence carries non-obvious information (timestamp independence, error reporting), so little is wasted.

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

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

For a 6-param, 0-required tool with nested tag/time objects and no output schema, the description covers the semantics an agent needs to build valid multi-clause queries plus ordering and error behavior. Remaining gaps (result shape, limit interaction) are minor and partly covered by the schema.

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

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

Schema coverage is 67%, and the description compensates with semantics the schema does not carry: all provided clauses are intersected, a time clause alone is valid and answered from each memory's own timestamp rather than date tags, and IDs accept full UUIDs or unique 8-char prefixes. It does not restate limit bounds or the project fallback, which the schema already documents.

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

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

States a specific verb+resource (query memories) and enumerates the exact filter composition it supports: IDs, OR-tag, AND-tag, exclusion, date range, with intersection semantics. It also distinguishes itself from the sibling muninn_memory_search (topic-inside-range) and from muninn_memory_list_by_tag, so an agent can route 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 names when to use it (bundle content audits, convention checks, any multi-condition fetch) and, more importantly, names the alternative and the condition that selects it: 'For a topic inside a date range, use muninn_memory_search with time.' That is exactly the when/when-not/alternative guidance the dimension asks for.

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

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

Goes well beyond the read-only/idempotent annotations: it explains that the time range is applied before similarity ranking, describes the returned timeRange metadata (exact, method, matched), and warns that exact:false with method nearest-100 means unindexed memories inside a large range were skipped and the range should be narrowed. It also notes the indexing latency ('date-indexed within minutes') and the ownership restriction when time is set.

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

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

Front-loaded with purpose, then scoping, then the subtle time-range behavior. Dense but nearly every sentence carries distinct operational information; the parenthetical example of a natural-language time query earns its place. It is longer than typical 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?

For a 4-parameter search tool with no output schema, the description covers the tricky parts: filter-then-rank order, the timeRange result fields, and the nearest-100 caveat. It leaves the result shape for a memory itself and the limit parameter's effect unaddressed, but nothing that would cause a wrong invocation.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: project scoping excludes global/no-project memories, and the ordering interaction between time filtering and similarity ranking. It does not discuss the limit parameter, so it does not reach the top of the range.

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 ('Semantically search memories using natural language') plus the ranking mechanism ('most relevant memories ranked by similarity'). It is clear what the tool does, but it never names or distinguishes itself from close siblings such as muninn_memory_query or muninn_memory_search_tags, so an agent must infer the boundary from names alone.

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

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

Gives concrete conditional guidance: pass project to search strictly within a project, omit to search everything, and pass time for a date-range search with an example query. It also discloses the important scoping rule that with time set only your own memories are searched, not team-shared ones. It stops short of naming an alternative tool for structured/tag search.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so safety is covered. The description adds genuinely new behavioral context beyond annotations: substring, case-insensitive matching plus OR-within-pattern / AND-across-pattern semantics. It stops short of describing result ordering or pagination, so a 4 rather than 5.

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

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

Front-loads the matching semantics then the usage routing, with an illustrative example. Every sentence earns its place, though the single dense paragraph is slightly heavy for the operation's simplicity.

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?

Purpose, matching semantics, and sibling alternatives are all covered; annotations carry the safety profile and there is no output schema to document. Nothing needed to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning the schema lacks: the cross-pattern AND vs within-pattern OR combinatorics with a worked example. That elevates it above the baseline. The limit/project params remain schema-only.

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

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

States a specific verb and resource ('Find memories by PARTIAL tag match') and immediately defines the matching behavior. It explicitly distinguishes itself from muninn_memory_list_by_tag and muninn_memory_list_tags, so an agent can select it without opening sibling 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?

Gives an explicit when-to-use trigger ('Use when you don't recall the exact tag') with a concrete example, plus named alternatives for the opposite cases (exact tags, vocabulary browsing). The routing logic is fully specified.

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

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

Annotations declare destructive/idempotent/not-readonly, and the description adds non-obvious behavior beyond them: no embedding regeneration, no need to resend body or existing tags, cost comparison against update, and the compact {id, tags} return shape. No contradictions with the annotation profile.

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

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

Dense but zero waste; the core constraint (text untouched, deltas only) is front-loaded, followed by cost rationale, return shape, and the alternative routing. No filler sentences.

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

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

For a 3-parameter mutation tool with no output schema, the description covers what changes, what doesn't, what's returned, and when to pick the sibling instead. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% so baseline is 3, but the description adds real semantics: pass deltas not the full list, add is deduped against existing, remove strips, and memoryId accepts an 8-char prefix. Gaps are minor (no guidance on erroring on non-existent tags).

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 pair (add/remove) and resource (tags on a memory), plus the critical scope constraint 'WITHOUT touching its text'. An agent can distinguish it from muninn_memory_update purely from the 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?

Explicitly routes the agent: use muninn_memory_update only when text/project/decay changes or a wholesale tag replacement is needed. The delta-vs-full-list rule is stated up front, which is the main selection hazard.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false; the description adds the valuable clarification that 'Body and embeddings are untouched' despite the destructive flag, plus dedup behavior against existing tags. It also notes return behavior ('per-id results and any resolution errors'), which is useful given no output schema, though permission and rate-limit behavior remain unstated.

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

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

Four tight sentences, front-loaded with the operation and scope, then constraints, then use cases, then return contract. Minimal waste, though the listing of use cases could be trimmed slightly.

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 batch mutation tool with no output schema, the description covers scope, untouched fields, prefix resolution with error reporting, and dedup behavior, so an agent has enough to call it correctly. Minor gaps around permissions or failure semantics for the whole batch keep it from a 5.

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

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

Schema coverage is 100%, so the schema already documents all three parameters including the prefix format and dedup note. The description merely restates the prefix capability and does not add meaning beyond the schema, making the baseline 3 appropriate.

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

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

The description gives a specific verb ('Apply tag adds and/or removes'), a resource ('memories'), and clear batch scope ('across MANY memories in one call'), which implicitly separates it from the singular muninn_memory_tag sibling. It stops short of naming the single-memory alternative explicitly, so it falls just short of full sibling differentiation.

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

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

It provides concrete use cases ('project renames, bulk re-tagging, or applying a convention to a whole set'), giving clear context for when to reach for it. However, it never states when NOT to use it or points to muninn_memory_tag for the single-memory case, so there are no explicit exclusions.

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

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

Far exceeds the annotations: atomic rejection if any `old` fails to match exactly once, embedding regeneration only when text actually changes, tags replacing the whole list, automatic public-link refresh for published artifacts, and expectedRev conflict rejection instead of silent overwrite. These are the failure modes an agent cannot infer from destructiveHint/idempotentHint 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?

Front-loaded with purpose and the mutually exclusive edit modes, and most sentences carry distinct information. It is long and repeats some schema-level detail (notably hideRank and replacements atomicity), but given 10 parameters with no output schema the density is largely justified.

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?

Since no output schema exists, the description supplies the return contract itself ({id, tags, project, updatedAt, embeddingRegenerated, length}) and explains that length is the self-verify signal because the body is never echoed. Combined with concurrency (expectedRev) and artifact-editing coverage, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond it: the replacements-as-cost-saving device, the embedding-regen condition, the short-form memoryId prefix, and concrete guidance for setting expectedRev. Some content (tags replaces existing, replacements order) is duplicated from the schema, which keeps this 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?

Opens with a specific verb+resource and enumerates exactly which fields are mutable (text, tags, decay score, occurredAt, project). It also distinguishes itself from siblings by naming muninn_memory_tag for tags-only edits and stating there is no separate muninn_artifact_update, which is real disambiguation an agent can act on.

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

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

Explicit routing: 'For a tags-only edit, prefer muninn_memory_tag', two named text-edit strategies with the cost tradeoff between them, and clear when/when-not for expectedRev ('omit it when you read and write in the same breath'). It also covers the non-obvious case of editing an artifact body through 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?

Beyond the annotations, the description discloses that the tool returns a browser URL, requires user approval, belongs to a paid plan, and that 'gdrive' is push-only with copies never coming back. It also warns that 'github' is unavailable and refused, which is important behavioral context.

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

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

The description is front-loaded with the action, followed by the return value, next step, prerequisite, and provider constraints. Every sentence adds operational value with no filler.

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

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

Given the lack of an output schema, the description explains the key return value (a URL) and the required follow-up step. It also covers pricing, provider availability, and push-only semantics, making the definition complete enough for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful meaning beyond the schema by explaining that 'gdrive' is push-only ('copies out of Muninn, never back') and that 'github' is not available yet and is refused, though much of this overlaps with the schema's own parameter description.

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

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

The description uses a specific verb and resource: 'Start the connection flow for a mirror provider.' It clearly distinguishes the tool from its follow-up sibling by stating that after approval the agent should call muninn_mirror_status to confirm.

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, including a prerequisite ('Paid plan') and an explicit follow-up ('After approving, call muninn_mirror_status to confirm'). It also states that 'github' is refused, but it does not explicitly frame when to choose this over other mirror tools such as designate or push.

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?

Goes well beyond the annotations (readOnlyHint=false, idempotent, openWorld): it discloses the tag side effect on the backing memory, the automatic enqueue-on-write behavior after designation, billing implications, and a provider-specific refusal path. These are operationally critical traits annotations cannot convey.

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

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

Five tight sentences, front-loaded with the core action and mechanism, followed by behavior, billing, and provider caveats. Every sentence carries non-redundant information.

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

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

With no output schema, the description covers everything an agent needs: what changes, what happens afterward, cost/policy gating, provider limitations, and the force-push alternative. No material gap remains.

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 useful semantics: enabled=false means stop mirroring and is free, and the github provider value is only usable with enabled=false. It does not elaborate on rootKey beyond the schema wording.

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 — designating/un-designating a bundle for mirroring to a provider — and clarifies the concrete mechanism (tagging the bundle root's backing memory). It is clearly distinguishable from sibling mirror tools (push, connect, status, reconcile).

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 to muninn_mirror_push for forcing a push now, states the Paid-plan gate for enabling versus the always-free disable path, and warns that GitHub enabling is refused while un-designating still works. When-to-use, when-not, and the alternative are all present.

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 declare the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), and the description adds substantial context beyond them: the push is deferred via a dirty flag to a 15-minute cron tick, provider omission queues all connected providers, and a lapsed account pauses mirroring while retaining already-mirrored files. 'files already mirrored stay' is consistent with destructiveHint.

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

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

Dense but front-loaded, with each clause earning its place (timing, provider scope, plan gating, github refusal). Slight deduction because it opens with 'immediate' then immediately corrects to 'next cron tick (every 15 min)', a mild tension in the lead sentence.

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

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

For a mutation tool with no output schema, it covers timing, provider behavior, plan gating, and provider refusal well, and annotations cover the destructive/idempotent profile. It does not describe what the call returns or how to observe the queued state (e.g., via muninn_mirror_status), a minor gap.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description largely restates provider semantics ('omit for all connected providers', github refused) that the schema enum description already conveys, adding little beyond it; baseline 3 applies.

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

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

States a specific verb+resource ('Force an immediate mirror push of one bundle') and scopes it to a single bundle root. It is clearly distinguishable from the other mirror siblings (connect/designate/reconcile/status) which manage setup and state rather than triggering a push.

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 real preconditions (paid plan, lapsed accounts pause, only gdrive works, github refused) but never routes the agent against alternatives such as muninn_mirror_reconcile or muninn_mirror_status, nor says when to trigger a push manually versus waiting for the cron tick. Usage 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?

Goes well beyond the annotations: it discloses that the effect is enqueue-only (actual push waits for the cron tick), that the scan is budget-limited and resumable via the 'complete' flag, that only Paid accounts are reconciled and lapsed mirrors are paused, and that GitHub rows queue but never push. That is exactly the mutation semantics an agent needs given destructiveHint=true and openWorldHint=true.

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 action, then the trigger condition, then return shape and constraints; nearly every clause carries information. It is dense and slightly run-on, packing account tier, provider behavior, and return semantics into a single 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?

There is no output schema, and the description compensates by naming all four return fields and explaining that complete=false means a budget-truncated resumable scan. Account requirements, provider limitations, and side-effect timing are all covered, 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 coverage is 100% and the enum is documented, so the provider parameter is already fully specified. The description adds relevant semantics (gdrive works, github is queued but never pushed, omit for all) but never references the parameter name directly, so this is baseline-level rather than additive.

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 ('manually trigger a mirror reconciliation pass') and explains the mechanism precisely: enqueues unseen memories and re-marks changed ones for the next cron tick. This implicitly separates it from muninn_mirror_push (immediate push) and muninn_mirror_status, but no sibling is named explicitly, so an agent must infer the boundary.

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?

'Useful after a gap or error' gives a clear triggering condition, and the account/paused and GitHub-not-pushed notes tell the agent when this will do nothing. There is no explicit exclusion or named alternative (e.g., 'use muninn_mirror_push for an immediate push'), so usage is well-contextualized but not fully routed.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds substantial behavioral context: github entries never push or pull and their pending count never drains, and on lapsed accounts pushes are paused so pending can grow. These are non-obvious traits an agent cannot derive from annotations or 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 returns, then filtering, then caveats. Every sentence earns its place, though 'Free on every plan' is a mild marketing aside and the passage is longer than strictly necessary for a one-parameter read 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?

No output schema exists, so the description carries the return-shape burden: it enumerates connected, last push time, pending count, and last error. Combined with the github and lapsed-account edge cases, an agent has everything needed to call and interpret 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% and the enum is documented, so baseline is 3. The description adds meaning beyond the schema by explaining the filter intent ('Pass provider to filter to one provider') and warning that a github value is reported but non-functional.

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 (Report) and resource (mirror connection state and push health per provider), and clearly distinguishes itself from mirror_connect/designate/push/reconcile as a read-only status check. An agent can identify it without opening the schema.

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

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

Gives strong contextual guidance: how to filter by provider, that the tool is free on every plan, and how to interpret a github entry. It does not explicitly name alternatives (e.g., mirror_reconcile) or a when-not-to-use condition, so it falls short of a 5.

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

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

Goes well beyond the annotations: it discloses the read-only failure mode (verified:false blocks every save via muninn_memory_add), the gating for starterInstruction, and the effect of hasIdentity. The only friction is that 'set up a brand-new account' implies mutation while the annotations declare readOnlyHint=true and the actual writes are delegated elsewhere — the description never explicitly reconciles that, though the mechanism becomes inferable.

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 trigger, then the return shape, then per-field handling rules — a sensible order with little wasted text. It is dense and run-on in the middle (return-field prose reads as one long sentence), so structure could be tightened, but every clause carries operational information.

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

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

With no output schema, the description fully carries the return-value burden, explaining each of the five fields and the correct agent action for the two error-ish states (unverified account, existing identity). Nothing an agent needs to run the onboarding conversation 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?

Zero input parameters, so the schema baseline is 4. The description instead spends its detail on the return shape (memoryCount, verified, hasIdentity, firstRunScript, starterInstruction), which is the right use of space given no output schema exists.

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 ('Set up a brand-new Muninn account') and immediately distinguishes itself from sibling muninn_session_boot by naming the exact condition where boot delegates here. An agent can pick between onboarding flow and normal session boot 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?

Enumerates concrete invocation triggers (user asks to set up Muninn, just signed up, memory is empty, session_boot returns nothing) and explicit when-not conditions: don't run the interview if verified:false or hasIdentity:true. It also names the alternative tool (muninn_session_boot) and the required follow-on tool (muninn_memory_add).

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 only declare the mutation/safety profile (readOnly=false, idempotent=false, destructive=false). The description adds substantial context beyond them: the external network requirement, the raw POST contract with field names, size/format/count limits (7 photos, 10 MB, JPEG/PNG/WebP, 15-minute expiry), the returned field shape, and the crucial lifecycle note that 'Nothing is a memory until finish runs.'

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 alternative, then the return shape, then the mechanics. Every sentence carries operational detail and none is filler, though the density is high and a couple of clauses could be tightened.

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

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

For a multi-step upload flow with no output schema, the definition compensates by enumerating the returned fields ({memoryId, endpoint, header, how, expiresAt, maxFiles}) and the exact HTTP mechanics an agent must execute. Nothing needed 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% and the single parameter (maxFiles, 1-7, default 7) is fully documented there. The description only echoes the count limit ('Up to 7 photos') without adding syntax or 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 ('Save photos ... as a picture memory') and immediately scopes which photos qualify ('photos YOU can already read ... on your sandbox disk, or files in a working directory'). It explicitly distinguishes itself from the sibling muninn_picture_upload_start, so an agent can route without opening either schema.

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

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

Gives an explicit condition for using the alternative: 'if your code cannot reach it, use muninn_picture_upload_start so the user picks them instead.' It also brackets the workflow by naming the follow-up calls (muninn_picture_view, muninn_picture_upload_finish), leaving nothing about when-to-use to inference.

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

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

Annotations only declare write/non-idempotent/non-destructive, so the description meaningfully adds: the note is session-scoped ('written in this session'), the return shape {success, memoryId, pictures}, and the cascade side effect ('Deleting this memory later deletes its photos'). It does not cover failure modes or what happens if photos have not actually arrived, despite the 'check with muninn_picture_view first' precondition.

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 action and the precondition before the labeling rules, and most sentences carry distinct information. It is dense and slightly run-on in the source-label enumeration, but nothing is padding given 9 parameters.

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

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

With no output schema, the description compensates by disclosing the return payload and the deletion cascade, and it ties the tool into the surrounding flow (view/start/direct, memoryId provenance, 'picture' auto-tag). An agent has everything it needs to finalize a picture memory 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?

Well beyond the 100%-coverage schema: it defines the pragmatic meaning of each whenSource/whereSource enum value, gives the rule for 'upload_time' (capture time equals upload time in-app), and maps the in-chat picker labels directly onto source values. It also adds a constraint ('Never guess a place or a name from the pixels') that the schema cannot express.

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

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

States a specific verb and resource ('Write the picture memory') and situates it in the upload flow ('after the user's photos arrived'). It distinguishes itself from the generic memory siblings via the 'picture' tag and the memoryId lineage from _upload_start/_direct, though it never explicitly contrasts with muninn_memory_add.

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 prerequisite ('check with muninn_picture_view first'), names the flow tools behind memoryId, and maps picker labels onto whenSource/whereSource values. It never states when NOT to use this tool or explicitly routes users to muninn_memory_add for non-picture memories.

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?

Beyond the annotations (which only flag it as a non-idempotent write), the description discloses the picker/widget behavior, that a message is posted for the user, the return shape {memoryId, uploadUrl, expiresAt, maxFiles}, constraints (7 photos, JPEG/PNG/WebP, 10 MB, 15 minutes), metadata preservation, and the crucial state fact that nothing becomes a memory until finish runs.

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 long but front-loads the core action and routing rule, then stacks return values, constraints, and workflow in sequence. Nearly every sentence earns its place, though the return-value and workflow details could be tightened slightly.

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

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

For a tool with no output schema, the description fully covers the return object, the multi-step completion workflow, UI behavior, and hard constraints. An agent has everything needed to call it and guide the user 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?

There is only one optional parameter and the schema already documents it at 100% coverage, including the 'Omit for 7' default. The description's 'Up to 7 photos' reinforces maxFiles but adds no syntax or meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource (upload photos to Muninn) and explains the mechanism (in-chat photo picker). It explicitly distinguishes itself from the sibling muninn_picture_upload_direct based on whether photos are already attached.

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

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

It gives explicit trigger conditions ('whenever the user wants to upload, save, add or keep a photo... and has NOT already attached it'), an explicit exclusion ('Never ask the user to attach a photo instead'), and names the alternative tool plus its selecting condition. It also spells out the surrounding workflow (view, then finish).

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 declare the read-only/idempotent/non-destructive profile, but the description goes well past them: viewUrl expires after 5 minutes and must not be persisted, artifactRef renders for the owner, publishing strips metadata and yields hour-long links, and takenAt/camera provenance depends on upload path. This is unusually rich operational context.

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

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

Purpose and return shape are front-loaded, and most sentences carry unique operational information. It is dense and slightly long, and the artifact-publishing/expiry theme is touched twice, but little is genuinely 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?

With no output schema, the description itself specifies the return JSON fields and adds the constraints (link expiry, artifact embedding rules) an agent needs. Nothing material for correct invocation is missing.

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

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

Schema description coverage is 100% for the single memoryId parameter, and the description mostly restates its origin (upload_start/_direct or a picture memory id) rather than adding new meaning. Baseline 3 is appropriate when the schema carries the parameter documentation.

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 and resource: 'See the photos of a picture memory, or of an upload that has not been finished yet.' It clearly distinguishes itself from the picture_upload_* siblings by covering the post-upload/pre-finish viewing case, so an agent can route to it without opening the schema.

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

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

Gives explicit timing: 'Use after the user uploads, before writing the note, and whenever the user asks to see a picture memory again.' It also states prohibitions ('never save it into a memory', 'Never put viewUrl or image bytes in an artifact'), which function as 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?

Adds real behavioral context beyond the annotations: the Worker subrequest cap, one-batch-per-call semantics with nextCursor chaining, and exactly what repair vs reindexAll mutate. It does not explicitly warn about the destructiveHint=true annotation (what gets overwritten), which is a minor gap given the annotation already flags it.

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

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

Front-loaded with the core purpose, then pagination mechanics, then the reindexAll special case. Every sentence carries information, though the final reindexAll sentence is dense and could be tighter.

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

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

For a complex, no-required-param maintenance tool with no output schema, the description covers invocation modes, batching workflow, migration path, and summarizes the return (a report of found/fixed items plus nextCursor). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: cursor is tied to the previous call's nextCursor, limit is the batch control, and reindexAll's migration purpose plus its 'skips the existence probe' behavior. This goes beyond the schema descriptions rather than restating 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?

States a specific verb (Scan) plus resource and scope: 'all memories for orphan/inconsistency issues across KV, D1 tag index, and Vectorize.' This is precise enough to separate it from sibling tools like muninn_mirror_reconcile, which operates on a different resource.

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 when-to-use guidance for each mode: repair:true to fix vs report-only, limit+cursor for large accounts due to the 1000-subrequest cap, and reindexAll:true specifically for the vector-id format migration. It does not name a sibling alternative or state when not to run it, 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes beyond that by disclosing what each output mode yields and that show_keys embeds keys and memory ids to avoid a second lookup — real behavioral context the annotations cannot express.

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

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

Four sentences with the core action front-loaded and no filler; each sentence maps to a format mode or the show_keys affordance. It is slightly repetitive in enumerating formats that the enum already lists, but nothing is wasted.

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

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

For an 8-parameter, 1-required read tool with no output schema, the description covers what the primary output shapes look like and what the most consequential flag (show_keys) does. The remaining optional md-only knobs are fully specified in the schema, so no critical gap is left, though the sibling overlap with bundle_export_okf is unaddressed.

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

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

Schema description coverage is 100%, so a baseline of 3 would be defensible, but the description adds genuine meaning: it explains that 'tree' is a compact outline of slugs and that show_keys exists specifically to make a follow-up edit possible without an extra bundle_get. That is rationale, not just a restatement of 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 (render) and resource (bundle), and the parenthetical defines the domain object ('an ordered outline of memories for a book or project'), so an agent knows exactly what is being produced. It does not, however, differentiate itself from the sibling muninn_bundle_export_okf, which the 'okf' format appears to overlap with.

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

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

Gives clear context for choosing among the three format modes (md = readable markdown in order, tree = compact slug outline, okf = JSON export), plus a concrete reason to enable show_keys for a follow-up edit. It stops short of naming when-not-to-use-it or routing to alternatives such as bundle_get or bundle_export_okf.

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

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

Annotations already declare read-only/idempotent/non-destructive, yet the description adds material context beyond them: the query text is sent to Muninn's servers and not stored, preview-only entries require muninn_memory_get for full bodies, carryover is returned but not cleared, and taskMemoryErrors reports ambiguous/missing anchor ids. It also explains account scoping (team-shared memories, no cross-user leakage).

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 purpose and usage before the dense payload description, and every section maps to real behavior. It is long and slightly redundant (the DATA SENT sentence duplicates the query parameter's schema description), but given ten returned fields the length is largely earned.

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

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

There is no output schema, and the description fully documents the returned shape (sessionState, identity, coreRules, relevant, mostAccessed, carryover, skills, persona, taskMemories, taskMemoryErrors) including the focus-mode override semantics. Nothing an agent needs to call and interpret this tool 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 largely restates schema content (query authoring, focus mode defaults, include* toggles); its only genuinely additive parameter-adjacent detail is the anchor-error behavior via taskMemoryErrors, which is not enough to clearly exceed the baseline.

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

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

Opens with a specific verb+resource: 'Load the user's saved Muninn context,' which is distinct from sibling tools like muninn_memory_search or muninn_memory_get. It also enumerates the return payload, so an agent can tell this is the session-bootstrap tool rather than a targeted memory fetch.

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 rich trigger list (user asks what you remember, wants to continue earlier work, refers to history-only facts, or instructions say to load at conversation start) and describes the focus-boot alternative when memoryIds is passed. It does not state an explicit when-not or compare against the nearest sibling (muninn_memory_search) for ad-hoc lookups, so it falls just short of 5.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile fully. The description adds only the scoping detail that these are the *current user's* settings (per-user rather than team/global), which is genuinely useful but thin; it says nothing about return format or what settings are included, though no output schema exists to carry that.

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

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

A single nine-word sentence with no filler, front-loading the verb and the scope. Nothing is redundant and nothing is buried.

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

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

For a trivial zero-parameter getter with rich annotations, the description is close to sufficient, but with no output schema it never hints at what the returned settings contain or how an agent should interpret them, leaving a small but real gap.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies no inputs are needed to scope the call, and there is no parameter information it needed to supply.

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

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

States a specific verb (Retrieve) and resource (settings) with a scope qualifier (current user's), making the read-vs-write split from muninn_settings_update obvious. It does not explicitly name the sibling, but the verb alone disambiguates it.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. Usage is only implied by the verb 'Retrieve' in contrast to the sibling muninn_settings_update, which is adequate but minimal for an operation this simple.

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

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

Annotations already declare non-readonly, destructive, idempotent and closed-world, so the safety profile is covered. The description adds genuinely non-structured context — that this is a partial merge where unspecified fields are preserved — which is the key behavior an agent needs before calling it.

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

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

Two short sentences, zero waste, with the merge constraint placed immediately after the purpose so the most important behavioral fact 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 two-optional-parameter settings tool with full annotation coverage and no output schema, this is nearly complete. Minor gaps remain: whether the response returns the resulting settings, and how unknown keys are handled.

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 both optional parameters (language, timezone) are documented with examples in the schema itself. The description's merge statement reinforces that omitted fields are untouched, but adds no format or validation 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?

States a specific verb (update) and resource (user settings), so the agent knows exactly what changes. It does not differentiate itself from the obvious sibling muninn_settings_get, but the mutation intent is unmistakable.

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 'call this to change settings' but the description never says when to prefer it, nor points to muninn_settings_get for reading current values first. No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds genuine behavioral detail beyond that: the three outcome categories (outdated, current, unknown) and the important scoping caveat that unnamed skills are not evaluated. It omits nothing critical but adds no auth or rate-limit context.

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

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

Three short sentences, each load-bearing: purpose first, invocation/input second, output and scope third. No filler or redundancy, and the most decision-relevant information 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?

There is no output schema, so the description correctly compensates by naming the return categories (outdated, current, unknown) and the reporting scope. For a single-parameter, non-destructive read tool this is nearly sufficient; only the absence of guidance on versionless skills (covered in the schema, not the prose) keeps it from a 5.

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

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

Schema description coverage is 100% for the single 'installed' parameter, including per-field docs for name and version. The description restates the same contract ('skills you currently have loaded with their skill-version stamps') without adding format, ordering, or size guidance beyond the schema, so the baseline of 3 applies.

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

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

Specific verb + resource ('Check whether installed Muninn skills are up to date') with an added scope statement ('Only reports on skills you name'). An agent can immediately distinguish this read-only freshness check from muninn_skill_create, muninn_skill_update, and muninn_skill_delete 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?

Sets up the usage context clearly ('Send the skills you currently have loaded with their skill-version stamps') and bounds the scope to named skills, so the agent knows what input scenario triggers it. It stops short of naming an explicit alternative (e.g., muninn_skill_registry) or stating when-not to use it, so it does not reach the top band.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description goes beyond these by disclosing the internal mechanics (stores two memories, wires them by ID) and the deferred effect (available in next session_boot), which is real value the annotations don't carry. It does not address naming collisions or failure behavior for a duplicate name.

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 purpose, then side effects, then return values. No filler; 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?

With no output schema, the description usefully names the return values (entryId and bodyId). Combined with full schema coverage and annotation-provided safety profile, an agent has nearly everything needed. It stops short of explaining duplicate-name handling or what 'wires them by ID' implies for later updates.

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%; each of name, description, and body is documented in the schema with slugs, length limits, and content expectations. The description only restates the parameter names without adding syntax or format meaning, 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+resource: 'Create a new Muninn-native skill from name, description, and body.' It is clearly distinguishable from siblings like muninn_skill_update, muninn_skill_delete, and muninn_skill_check 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?

Usage is implied by the verb (you create when a skill doesn't yet exist), and it notes the skill appears in the next session_boot. However, it never explicitly contrasts with muninn_skill_update or muninn_skill_registry, nor states when-not to use it, so no alternative routing guidance is given.

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