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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the "Read-only" claim is partly redundant. However, the description adds genuinely useful behavioral detail the annotations cannot: the ranking mechanism, the summarisation output shape, and the negative constraint that file bodies are not returned.

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

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

Two tight sentences with no waste: the first front-loads what the tool does and how, the second gives usage guidance and the key exclusion. Nothing is 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?

With no output schema and four parameters, the description still covers enough: it indicates the return shape (ranked files plus summarised key symbols) and what is not returned. It is nearly complete for a read-only query tool, though it does not mention result counts or ordering guarantees beyond max_files.

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

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

Schema description coverage is 100%, so every parameter (root, query, max_files, chat_files) is already documented in the schema. The description adds no syntax, format, or inter-parameter detail beyond that, 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 (rank/summarise) and resource (a local repo's source files) plus the mechanism (tree-sitter symbol graph + PageRank). None of the sibling tools (memory_*, wiki_*) do repo ranking, so the scope is unambiguous.

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

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

"Use to find where code lives" gives clear usage context, and "it does not return file bodies" explicitly rules out a plausible alternative expectation (reading file contents). No sibling tool is named as an alternative, but the sibling set is disjoint so this is a minor 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real behavioral context beyond them: input is lowercased, alias chains are flattened (transitive resolution), and re-adding an alias silently re-points rather than erroring — which is the detail that explains the destructive hint.

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 clauses, front-loaded with the core action and an example, then the behavioral caveats, then the sibling pointer. Nothing is redundant or padding.

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

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

For a 2-parameter mutation tool with annotations covering the safety profile and no output schema, the description covers action, normalization, re-point semantics, and verification via a sibling. Return/confirmation behavior is left implicit but is minor for this 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%, so baseline is 3, but the description adds meaningful semantics the schema lacks: the alias value is normalized to lowercase and alias chains are collapsed. It does not clarify whether the canonical value is normalized the same way, leaving a minor gap.

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

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

States a specific verb+resource (fold a surface form into a canonical entity) with a concrete bilingual example that removes ambiguity. It also names the sibling memory_alias_list, so an agent can separate this write-side tool from the read-side listing tool 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?

"so recall treats them as one" gives the condition that motivates using this tool, and "See memory_alias_list" routes the agent to the complementary sibling for inspection. It stops short of explicit when-not guidance (e.g. alias vs. creating a separate entity), so it is clear context without 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds beyond that by describing the result payload (canonical/alias pairs plus a total) and flagging the duplicate-alias hazard it helps avoid. It does not discuss size limits or ordering, but that is minor against the annotation coverage.

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

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

Two short sentences with zero filler; the output shape is front-loaded and the usage rationale follows immediately. Every clause earns its place.

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

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

With no parameters, no output schema, and read-only annotations, the description is nearly complete: it states what comes back and why to call it. It stops short of noting pagination, ordering, or behavior on an empty alias set, which a caller might still want to know.

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. There is nothing in the schema to explain and the description correctly says nothing about inputs, though it also does not mention any implicit filtering (e.g. scope of 'your memory').

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 (list) plus specific resource (entity aliases), and it even names the return shape: {canonical, alias} pairs plus a total. It explicitly distinguishes itself from sibling memory_alias_add, so an agent can tell them apart without opening either schema.

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

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

Gives an explicit precondition ('Check here before memory_alias_add') and a concrete reason ('so you do not re-point an existing alias by accident'), naming the alternative tool it complements. Nothing about when to reach for this versus memory_alias_add 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 declare readOnlyHint/openWorldHint, and the description adds genuinely new behavior: the return shape {memories, missing_ids} and the partial-failure tolerance that unknown or foreign ids land in missing_ids rather than aborting the call. That is exactly the kind of non-obvious error semantics an agent needs. It stops short of covering ordering or permission expectations, 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?

Three short sentences, zero filler, and the batch scope plus return/error contract are front-loaded before the routing advice. 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?

With no output schema present, the description carries the return-value burden and does so: it names both response fields and the failure mode. Nothing an agent needs to invoke this two-parameter read tool 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 both parameters are already documented, giving a baseline of 3. The description adds meaning beyond the schema by tying the '1 to 100' cap and the unknown/foreign-id behavior to how ids are interpreted, which helps the agent construct a safe batch call.

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

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

States a specific verb and resource ('Fetch ... memory entries by id'), gives the batch cap (up to 100), and names the sibling it replaces ('Use instead of repeated memory_read'), so an agent can distinguish it from memory_read/memory_search 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 the agent: use this instead of repeated memory_read when fetching many entries by id. The single-read alternative and the condition that selects the batch form are both stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: the return is a single fact or found:false, and it is 'Safe with out-of-order ingestion' — an important temporal-ingestion trait an agent cannot infer from annotations.

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

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

Two dense sentences with zero waste. The core behavior and return shape are front-loaded, and the sibling routing is packed into the tail rather than padding the lead.

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, three-parameter lookup, the description is nearly complete: purpose, return shape, temporal semantics, and sibling routing are all present, and annotations plus 100% schema coverage fill the rest. Without an output schema the exact return object could be clearer, but 'or found:false' covers the key ambiguity.

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

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

Schema description coverage is 100%, so all three parameters (subject, predicate, at) are already documented with format examples. The phrase 'by world time' adds light semantic framing for the 'at' parameter, but the description otherwise adds no syntax or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource: retrieving the single (subject, predicate) fact valid at one instant by world time, with a stated return shape ('or found:false'). It distinguishes itself from memory_get_history and memory_search by naming them explicitly, so an agent can tell it apart from siblings without opening any schema.

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

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

Routes clearly to the right alternatives: 'Full change log: memory_get_history; free-text recall: memory_search,' which implies when this point-in-time lookup is the correct choice. It stops short of an explicit when-not statement (e.g. latest-state vs point-in-time), so it is a strong 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds real behavioral detail beyond them: expired rows are included, results are ordered oldest to newest, and the supersession chain between writes is exposed. It does not mention result size limits or pagination for long histories.

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

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

Two sentences, no filler, and the most decision-relevant content (what is returned, including expired rows) is front-loaded before the alternative-tool pointer.

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 a safe read operation, the description does the work of explaining the returned sequence, its ordering and its supersession semantics. Only the absence of any volume/pagination note for potentially long histories keeps it from being fully complete.

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

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

Schema description coverage is 100% and both parameters are documented with examples in the schema, so the description carries no extra parameter burden. It frames the two params as a fact pair but adds no syntax or format meaning 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/resource: it returns the full historical sequence of values for a (subject, predicate) fact. It also explicitly differentiates itself from the sibling memory_get_at, which covers the point-in-time case.

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?

Directly routes the agent: 'For the value at one instant use memory_get_at,' which tells the agent when to pick the sibling over this tool. The condition selecting each tool is stated rather than implied.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, and the description reinforces this with 'Writes nothing itself' and 'Returns candidates only', which is meaningful for an agent that might otherwise assume aggregation also persists. It does not cover rate limits or cost of scanning up to 100 memories, so it adds context but not exhaustively.

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

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

Three short sentences, front-loaded with the action and output, then the workflow constraint, then the safety clarification. No filler or repetition.

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

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

With no output schema, the description is responsible for describing the return, and it does so at a high level ('clustered proposal scaffold', 'candidates only'). Behavior, follow-up path, and read-only nature are all covered; only a slightly richer description of the scaffold shape would make it fully complete.

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

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

Schema description coverage is 100%, so both the topic and limit parameters are already documented in the schema, including the default and cap for limit. The description adds no parameter-level detail beyond 'about a topic', 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 ('reflect over your memories about a topic') and names the concrete output ('clustered proposal scaffold for consolidated rules'). It is clearly distinguishable from read-only siblings like memory_search and the write sibling memory_store.

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 workflow guidance: this returns candidates only, you review, then persist with memory_store. That routes the agent to the correct follow-up tool. It lacks a direct 'use memory_search instead if...' exclusion, so it stops short of full when-not coverage.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds non-trivial behavior beyond that: unknown or foreign ids are refused, and the exact fields returned (content, tags, layer, importance, created_at). It doesn't cover output pagination or error shape, but for a single-id lookup this is solid.

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 with the core action front-loaded, followed by validity rules and the batch alternative. Every clause carries information; no filler.

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

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

With no output schema, the description compensates by listing the returned fields. Combined with the id-validity rule and the batch escape hatch, an agent has everything needed to call this correctly for a simple read tool.

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

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

Schema coverage is 100% and the schema already documents memory_id as a UUID from memory_store or memory_search, so the description's id provenance largely repeats structured data. It does hint at id validity semantics via the foreign-id refusal, which is a small addition 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 ('Read') and resource ('one of your memory entries by id') and enumerates the returned fields. It also distinguishes itself from the sibling memory_fetch_batch by routing multi-id reads there.

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 where valid ids come from (memory_store or memory_search), states the failure condition (unknown or foreign ids refused), and points to memory_fetch_batch for the multi-id case. Both the when-to-use and the alternative are 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 readOnlyHint and openWorldHint=false, so safety is covered. The description adds the search modality (keyword, not semantic), the corpus being searched, and the return shape {results,total}, which is meaningful since no output schema exists. It stops short of describing pagination or how the limit interacts with total.

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

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

Three short clauses, front-loaded with the action and scope, then the return contract, then the disambiguation. 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 low-complexity, fully documented 3-param read tool with no output schema, the description supplies the missing return shape and the routing rule. Only the result-count/limit behavior is left implicit in the schema.

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

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

Schema coverage is 100%, so query, tags, and limit are all documented in the schema with formats and defaults. The description only reinforces that matching is keyword-based; it adds no syntax or filtering detail beyond that, so the baseline 3 applies.

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

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

Specific verb+resource (keyword search over memory) plus an explicit scope statement: notes stored by the user and facts learned from chats. It also distinguishes itself from the closest sibling by naming memory_read for the known-id case.

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

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

Gives both a when-to-use trigger ("before answering from recall") and an explicit alternative with its selecting condition ("for a known id use memory_read"). An agent can route between the two without opening either schema.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description adds real value on top: 'Never overwrites' clarifies the mutation semantics, and 'Returns memory_id' fills in a return value that has no output schema. It doesn't cover anything like rate limits, dedup, or size limits on the note, which leaves a modest gap.

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

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

Four short clauses, front-loaded with the action, and each sentence carries distinct information: what it stores, how it's retrieved, what it returns, and where the sibling use case goes. 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, single-purpose write tool with a fully documented schema and no output schema, the description covers storage semantics, retrieval path, return value, and alternative routing. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so both content and tags are already documented in the schema, including the comma-separated-string fallback. The description adds only the framing that content is a single plain-text note; it says nothing about tags. 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 ('Save one free-text note to your own memory') and pins down scope: one note, one entry, own memory. It explicitly names sibling interactions (memory_search finds it, user_profile_record for preferences), so the agent can distinguish it from neighboring tools without opening schemas.

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

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

Gives both when-to-use and when-not-to-use with named alternatives: use this for free-text notes, and route per-user preferences to user_profile_record instead. It also explains the downstream payoff (memory_search and prompt injection), which tells the agent why to store at all.

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 and openWorldHint=false, so the description's 'Read-only' is redundant and adds nothing. Its real contribution is naming the return contents (typed rules, unresolved conflicts, untyped-row count), which matters because no output schema exists. That is useful but modest, so a 3 sits above the annotation-only baseline without reaching rich behavioral disclosure.

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?

Short, front-loaded, and dense with the component list up front. The one wasted element is the redundant 'Read-only' sentence, which merely echoes the annotation.

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 convey what compiling returns, and it lists the three components reasonably well. It does not describe the shape of the compiled profile or ordering, but for a zero-parameter read-only tool this is close to sufficient.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter information is needed or missing.

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 ('Compile') and resource ('your user-as-code profile from current memory facts') and enumerates the components it produces (typed preference/constraint rules, unresolved conflicts, untyped-row count). It also distinguishes itself from the sibling user_profile_get. The only drag is the slightly opaque 'user-as-code' framing, which assumes prior context.

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 line 'One user's view: user_profile_get' routes the agent to an alternative and implies this tool is the compiled whole-profile view. However, it never states when to use this tool itself, and no other siblings (e.g. user_profile_record, user_profile_get) are contrasted beyond the single hint.

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=true and openWorldHint=false, and the description confirms rather than contradicts that. It adds real behavioral context beyond the annotations: only *currently-valid* facts are returned (superseded ones are excluded) and the rendered block is what gets injected into replies. No auth or rate-limit details, hence not 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 short sentences, front-loaded with the resource and return content, with zero filler. The standalone 'Read-only.' sentence largely duplicates the readOnlyHint annotation, a minor redundancy that keeps it off a 5.

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

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

For a one-parameter read tool with no output schema, the description covers what is returned, how it is scoped, and where the write alternative lives. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, with user_id documented as a 'Stable per-user id from the channel', so the baseline is 3. The description only reinforces single-user scoping ('One user's') and adds no format or sourcing 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 and resource (one user's currently-valid preference facts) and describes precisely what comes back, including the rendered '## About This User' block. It is unmistakably distinct from the sibling write tool user_profile_record, which it names.

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 mutation to the alternative: 'Add or change facts with user_profile_record.' Clear context for a read, but it doesn't spell out the trigger condition (e.g., before composing a reply to that user), leaving when-to-call slightly implied.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false, which already signal a safe non-destructive write), the description discloses genuinely non-obvious behavior: re-recording the same predicate supersedes the prior value rather than duplicating, and history is retained. That supersede-and-keep-history semantics is the key thing an agent must know before writing and is not derivable from the annotations.

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

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

Two compact sentences, zero filler. The core action and its examples are front-loaded, and the sibling routing note is placed last where it does least to interrupt the primary instruction.

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

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

For a write tool with no output schema, the description covers what gets written, what happens on conflict, and where non-user notes belong. It omits what the call returns and does not mention the origin_trust ceiling behavior, which the schema documents but the description never reinforces.

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 predicate/value/user_id are already fully documented with their own examples. The description's examples largely restate the schema, with only the supersede rule adding real semantics to 'predicate'. Baseline 3 is appropriate 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: 'Record one durable preference of a specific end user', with concrete examples (timezone, language, 'prefers tea'). It also distinguishes itself from memory_store ('Notes not tied to a user') and implicitly from user_profile_get, so an agent can separate it from its closest siblings without opening a schema.

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

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

The description names an explicit alternative with its selection condition: notes not tied to a user should go to memory_store. It implies the tool is for per-user preference capture, but does not state when to prefer it over user_profile_get or how it relates to memory_get_history for reading history.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds value: it discloses that the operation is non-destructive ('merges nothing') and what the result contains (pairs with trust and reason). It does not mention cost, scale limits, or performance for a similarity scan, which keeps it short of a 5.

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

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

Two dense sentences with no filler, and the core purpose is front-loaded before the read-only/merge 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?

With no output schema, the description correctly compensates by describing the return content (duplicate pairs with trust and reason). Combined with the safety annotations and the merge hand-off, an agent has everything needed to call and act on this 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?

Only one optional parameter (agent_id) with 100% schema description coverage, so the schema already carries the semantics. The description adds nothing about agent_id or its default behavior, which matches the baseline 3 for fully documented schemas.

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 likely duplicate wiki pages'), the detection mechanism ('by title and tag similarity'), and the return shape ('pairs with each page's trust and the reason'). It also draws a clear boundary with the write sibling, so an agent can distinguish it from wiki_read/wiki_write at a glance.

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

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

The description explicitly states the limit of the tool ('Read-only, merges nothing') and names the alternative that performs the follow-up action ('merge by hand with wiki_write'). That is an explicit when-not plus a named alternative, which is exactly what routing guidance needs.

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 meaningfully scopes that destructiveness: it explains that the previous export is overwritten while the wiki itself is never touched, which is precisely the risk an agent needs bounded. It also discloses the return value ('returns the path'). It stops short of covering permissions or failure modes, but it adds real context beyond the annotations.

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

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

Two compact sentences, front-loaded with the action and destination, followed by the safety-critical caveat. Every clause earns its place and nothing is repeated.

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, no-required-params tool with no output schema, the description covers destination, format options, defaults, return value, and the destructive side effect. Nothing an agent needs in order to invoke 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 description coverage is 100% and both parameters are fully documented in the schema (format's html/obsidian meanings, agent_id's default). The description restates the same defaults ('yours by default', 'one HTML file (default)') without adding syntax or behavior not already in the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Export a wiki'), names the output location (<home>/exports), both output formats with defaults, and the return value. There is no sibling export tool to confuse it with, so no differentiation is needed, and none of the sibling read/write/lint tools could be mistaken for this.

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: 'yours by default' signals the agent_id parameter lets you target another agent's wiki, and the format defaults are given. However, there is no explicit when-to-use guidance, no mention of prerequisites, and no note on when the Obsidian versus HTML format should be chosen beyond the raw format descriptions.

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 and openWorldHint=false, and the description redundantly restates 'Read-only,' which earns no credit. However, with no output schema, describing the return as a Mermaid diagram with nodes=pages and edges=related links is genuinely valuable behavioral context the annotations do not supply.

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

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

A single front-loaded sentence that conveys purpose, output format, the optional focused mode, and the read-only nature with no wasted words.

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 render tool with no output schema and fully documented parameters, the description covers purpose, output shape, and the optional narrowing mode adequately. It stops short of describing diagram size limits or a concrete output sample, 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 all three parameters (depth, center, agent_id) are already documented in the schema with defaults, caps, and the 'ignored without center' caveat. The description only lightly restates the depth/center relationship, adding no 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?

States a specific verb (Render) and resource (the wiki link graph) plus the output format (Mermaid diagram) and the node/edge semantics. An agent can distinguish it from wiki_ls, wiki_search, or code_map 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?

The description implies two usage modes — full graph vs. a focused view around `center` within `depth` hops — which is useful implied guidance. But it names no alternatives and gives no explicit when-to-use/when-not criteria versus sibling tools like wiki_ls or code_map.

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 and openWorldHint=false, so 'changes nothing' mostly restates structured data. The description does add value beyond that: it discloses the return form ('returns a report') and that shared-scope auditing also validates the frontmatter schema. Minor gaps remain about report contents or any cost/size limits.

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

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

Three short sentences, front-loaded with the audit action and its defect categories, followed by scope behavior and the sibling pointer. No filler or hedging; every clause carries information.

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

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

For a side-effect-free audit tool with no output schema, an agent knows what it checks, what it does not change, and which scope to pick. The only real omission is the shape of the returned report (sections, severity fields), which would help an agent parse results, but that is a modest gap given annotations cover the safety profile.

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 (scope, agent_id) are already fully documented, including the namespace SoT caveat. The description's scope="shared" sentence largely duplicates the schema text and says nothing about agent_id, so this is the baseline-3 case where 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 (Audit) and resource (the wiki) plus the exact defect classes checked: orphan pages, broken links and stale pages. It also disambiguates from the closest sibling by noting 'Totals only: wiki_stats', so an agent can separate auditing from aggregate counting 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 a clear condition for the scope parameter's non-default path (scope="shared" audits the shared wiki and its frontmatter schema) and routes totals-seeking callers to wiki_stats. It stops short of saying when an agent should lint versus rebuild (wiki_rebuild_fts) or dedup (wiki_dedup), so the alternative mapping is partial rather than exhaustive.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description needn't restate safety. It adds the scope="shared" cross-agent meaning, which is useful, but says nothing about pagination, result limits, or truncation behavior for large wikis. Adequate but not rich against annotations that already carry the safety 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?

Three short sentences, front-loaded with the action and return format, then the scope nuance, then the routing hint. Every sentence earns its place with no filler.

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

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

With no output schema, the description usefully sketches the return shape (tree with titles and dates). For a zero-required-parameter browse tool with fully documented params, this is close to complete; only pagination/limit expectations for very large wikis are 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 both parameters (scope, agent_id) are already fully documented in the schema, including the namespace SoT policy. The description's mention of scope="shared" duplicates rather than extends 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 ('List wiki pages') plus the return shape ('directory tree with titles and last-updated dates'), and names the sibling it is not (wiki_search). An agent can distinguish it from wiki_read and wiki_search 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?

'Use to browse; to find pages by content use wiki_search' gives an explicit condition and names the primary alternative. It does not mention wiki_read (to open a specific page), leaving one routing decision to inference, but the core browse-vs-search split is unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful fact that the return is frontmatter plus body, but the shared-scope/namespace behavior it hints at is already detailed in the schema, so it adds only modest 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, front-loaded with the core action and return shape, followed by prerequisite routing and the shared-scope tip. No filler or redundancy.

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

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

It is a read-only tool with no output schema, and the description covers the action, the returned content type, and how to obtain the required page_path. Nothing essential is missing, though a note on behavior when a page is absent would complete it.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including scope's agent/shared semantics and agent_id's ignore rule for shared writes. The description's mention of scope="shared" merely echoes the schema rather than adding new syntax or constraints; 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 ('Read a wiki page') and even specifies the return payload ('frontmatter + body'). It contrasts with the discovery-oriented siblings wiki_ls/wiki_search, so an agent can distinguish it 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 the agent to wiki_ls or wiki_search to obtain a page path first, which is exactly the prerequisite an agent needs. It also explains the shared-scope usage, though it gives no explicit 'when not to use this' beyond that 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 idempotentHint=true, so 'Safe to repeat' largely restates structured data, but the description adds real context: the index is derived from on-disk pages, and the call returns a page count. It does not disclose rebuild cost/duration or any auth requirements, which keeps it below a 5.

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

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

Three tight clauses with zero filler; the purpose and return value are front-loaded and the usage restriction follows. Nothing can be trimmed without losing signal.

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, low-complexity maintenance tool with no output schema, the description covers purpose, return value, safety, and triggering conditions. Only minor gaps remain (no mention of rebuild cost or failure modes), so it is essentially complete.

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

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

Schema coverage is 100% and the single agent_id parameter is fully documented in the schema, so the description adds no parameter-level information. Baseline 3 applies when the schema carries the full 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 ('rebuild') and resource ('the wiki full-text index from the pages on disk'), plus the return value. It is clearly distinguishable from siblings like wiki_search, wiki_lint, or wiki_dedup, which act on different aspects of the wiki.

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 scopes when to use it ('only when wiki_search misses pages you know exist') and gives a concrete trigger ('after files were edited directly'). It even names the alternative tool (wiki_search) and the condition under which that alternative fails.

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 and openWorldHint=false, but the description adds real behavioral detail beyond them: results are trust-weighted, and the expand hop is ignored when scope="shared". It does not discuss ranking order or result shape, which keeps it out of 5 territory.

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 clauses, front-loaded with the core action and followed immediately by the routing constraint. Every sentence earns its place, including the memory_search pointer.

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

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

For a 7-parameter read-only search tool with no output schema, the description covers scope semantics, the expand caveat, filter availability, and the sibling routing. It is complete enough to select and invoke correctly, though it says nothing about result ordering or empty-result behavior.

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

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

Schema coverage is 100% and each parameter already carries a rich description, so the schema does the heavy lifting. The description restates layer/min_trust/expand in passing and adds the shared-scope quirk, which is marginal added value 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 ('Full-text search of wiki pages') plus its distinguishing traits: trust-weighted ranking, layer/min_trust filters, and optional 1-hop expand. It also separates itself from the memory_* siblings by noting that notes outside the wiki belong to memory_search.

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

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

Names the alternative explicitly ('Notes outside the wiki: memory_search') and explains the scope="shared" routing condition. It stops short of an explicit when-not-to-use against wiki_ls/wiki_read, so it is strong but not exhaustive.

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 behavior beyond the annotations: re-sharing overwrites the existing file (explaining the destructiveHint=true), content is secret-scanned, and attribution is added. These are meaningful operational facts an agent cannot infer from readOnlyHint=false/destructiveHint=true alone.

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

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

Three terse clauses, front-loaded with the action and destination; no filler. Every clause carries distinct information (destination, overwrite, scan, alternative).

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 publish tool with no output schema, the description covers destination, overwrite semantics, the secret scan, and the full-page alternative. Minor gaps remain (e.g., whether the published page is editable/removable afterward), but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented (including the summary default of the first 500 characters). The description adds only the destination filename pattern, so 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 (Publish) and resource (a summary of one of your wiki pages), plus the exact destination path template sources/<you>--<name>.md. It is clearly distinguishable from the sibling wiki_write, which handles full pages.

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: this tool publishes a summary, while full shared pages should use wiki_write scope=shared. That names the alternative and the condition that selects it, though it does not spell out when-not to share at all.

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 and openWorldHint=false, so the 'Read-only' statement is largely redundant. The description does add one genuine behavioral detail not in annotations: shared scope adds per-contributor counts, which changes the return shape. No mention of cost, auth, or caching, so it is adequate but not rich.

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

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

Three short sentences, zero filler, and the metric list is front-loaded ahead of the sibling routing. 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?

There is no output schema, so the description carries the burden of describing returns, and it does so by enumerating the four metric categories plus the shared-scope variation. Combined with full schema coverage and read-only annotations, an agent has enough to call it correctly; only exact output shapes remain unstated.

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

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

Schema description coverage is 100%, so the schema already documents scope and agent_id fully, including the default and the ignore rule. The description adds only the per-contributor-counts effect of shared scope, which is marginal beyond 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?

The description names the resource (wiki) and enumerates exactly what the tool returns: pages, index entries, recent activity, health score. It also explicitly distinguishes itself from the sibling wiki_lint, which computes the underlying problems. A specific verb is implied rather than stated, but an agent can identify this as a read-only stats tool 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?

It explicitly names an alternative and the condition that selects it: 'To see the problems behind the score use wiki_lint.' That routing is clear. It lacks any when-not to use this tool or prerequisites, but for a simple read-only stats call that is a minor 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 flag destructiveHint=true, so the safety profile is known. The description adds genuinely non-obvious behavior on top: the write is atomic and has side effects on _index.md and _log.md, and shared writes are governed by the namespace policy. Auth/error behavior is still unstated, keeping it below a 5.

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

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

Front-loaded with the create/overwrite verb and packed into three short clauses with no filler. It is slightly dense with semicolons, but every clause (side effects, scope policy, edit prerequisite) 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 destructive write tool with no output schema, the description covers atomicity, side effects, scope policy, and the read-before-edit prerequisite, while annotations carry the safety signal. Remaining gaps (permissions, failure modes) are minor.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters (scope, content, agent_id, page_path, update_index). The description reiterates content-is-full-page and the namespace constraint on scope but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb pair (create/overwrite) and resource (wiki page), and clarifies the unit is the whole page including YAML frontmatter. It also names the sibling wiki_read for the editing path, so an agent can distinguish the write from the read 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 an explicit rule for the edit case ('To edit, wiki_read the page first') and a conditional behavior for scope="shared". It stops short of routing the agent among the other write-adjacent siblings (wiki_share, wiki_dedup), which is why it isn't a 5.

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