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

With no annotations to rely on, the description carries the behavioral burden and does well by disclosing the 60-minute auto-fetch cadence and the fact that entries become wiki pages. It covers the side effects of the operation beyond simple 'adds a feed', though it does not mention error cases or prerequisites.

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 compact, front-loaded with the core purpose, and every sentence carries useful information—the verb+resource, the auto-fetch behavior, and concrete user utterances. There is 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, no annotations, and only three simple parameters, the description provides the essential context: the operation, its recurring behavior, and triggering phrases. It does not describe return data or duplicate-feed handling, but for a straightforward subscription tool, the information is sufficient for an agent to act correctly.

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

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

Schema description coverage is 100%, so the parameter semantics are already fully documented in the schema. The description itself adds no extra detail about how tags or project affect the feed, but it doesn't need to given the complete schema 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?

The description clearly states a specific verb ('Subscribe MindBase to a new RSS feed') and resource, immediately distinguishing this from sibling tools that read, search, or ingest content. The mention that entries are compiled into wiki pages further sets it apart as a dedicated feed-subscription tool.

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

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

The description gives explicit, actionable usage cues: 'Use this when the user says things like...' with several concrete example phrasings. It does not list exclusions or alternatives, which keeps it just short of a 5, but the context is clear and sufficient.

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

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

With no annotations provided, the description carries the behavioral burden. It explicitly discloses that the card is rescheduled according to SM-2 after answering, which is an important side-effect. It does not detail additional mutating behavior or prerequisites, but the disclosed rescheduling is a useful behavioral transparency beyond the raw 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?

Two sentences with no filler: the first states the action, the second immediately gives the rating semantics and the scheduling consequence. Every clause contributes useful 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 simple 2-parameter tool, the description covers the core action, rating definition, and behavioral after-effect. There is no output schema, so returning details are not explained, but the essential calling context and purpose are sufficiently specified.

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 parameters are already documented. The description adds semantic value by explaining each rating (forgot, hard, good, easy) in terms of level of recall, which helps the agent map user feedback to the right enum value more accurately than the schema alone.

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

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

The description states a specific verb ('Submit') and resource ('answer to a review card'), and it defines what submitting means via the rating scale. This distinguishes it from sibling tools like list_review_cards or create_card, which do not perform the answer-submission action.

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

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

The description clearly implies the tool is used when the agent has completed a review card and needs to record a self-assessment rating. It does not explicitly exclude alternatives or name sibling tools, but the context of answering a card is strong enough to make the intended use clear.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It surfaces two key behaviors: sections are created when missing, and human-edited pages are protected unless force: true. It doesn't cover output format or permission requirements, but for an unannotated tool this is strong.

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 no filler. The core action leads, the auto-create behavior follows, and the guard condition is the final, distinct clause. Every sentence earns its place.

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

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

The description transmits the most important context: appending behavior, section creation, and the force guard. It does not mention what happens if the page is missing, whether output is returned, or error scenarios, but those are secondary for a mutation-oriented tool.

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

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

Schema description coverage is 50%, with force and section already documented there. The description adds some context by explaining that content is appended and that force bypasses the guard, but it does not clarify the slug or content parameter trade-offs beyond what one would infer from the parameter names.

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

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

The description clearly states the action (append), resource (an existing wiki page), and target (a section), and adds the auto-creation behavior. It doesn't explicitly differentiate itself from siblings like update_note_section or create_note, but the wording is specific enough to avoid confusion.

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

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

There is no guidance on when to choose this tool versus alternatives such as update_note_section or create_note. The force: true clause is a behavioral guardrail, not a usage-selection criterion.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it explains the retrieval pipeline (search → top hits + 1-hop wikilinks), the use of a configured LLM, and the citation-marker rendering convention. This is more than most tool definitions disclose.

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 three sentences with no wasted lines. The first states the core action, the second explains the retrieval behavior, and the third gives the critical citation-rendering instruction. Details are front-loaded and relevant.

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?

Because there is no output schema, the description must explain the return shape, and it does: the cited answer and the citations array, including how to link each [N] marker to mindbase_uri. The description is sufficiently complete for an agent to select and correctly use the 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?

All three parameters are already well documented in the input schema (100% coverage), so the description doesn't need to add much. The description provides broader retrieval context but doesn't add parameter-specific semantics beyond the schema, which aligns with the baseline of 3.

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 action ('Ask a natural-language question against the user's wiki') and a concrete resource, plus the distinguishing output (a cited answer). It differentiates from siblings by emphasizing graph-aware retrieval and 'what do I know about X?' questions.

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 positions this as the 'Best tool for "what do I know about X?" questions', which gives clear direction on when to use it. It does not mention alternatives or exclusions, but the use-case framing effectively routes agents toward it.

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

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

The description discloses an important behavioral consequence: 'The card will be scheduled for review immediately.' Since no annotations are provided, the description carries the full burden. However, it omits other behavioral context such as permissions, reversibility, or what happens to the card afterwards. It earns a 3 for adding meaningful side-effect information without full 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?

The description is only two sentences: one clean action statement and one contextual/behavioral note. Every word earns its place, and the most critical 'when to use' trigger is front-loaded. No irrelevant information is included.

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

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

The schema is fully documented, so parameter coverage is strong. The description provides a clear usage trigger and a notable behavioral side effect. A small gap remains because no output schema exists and the description does not explain the response or success indication, but this is a simple operation and the available context is mostly adequate.

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 input schema covers 100% of the parameters, including descriptions for question, answer, tags, and source_slug. The tool description does not add meaning beyond 'Create a new review card', so the schema is doing the heavy lifting. Baseline 3 is appropriate.

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

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

The description states a specific action and resource: 'Create a new review card manually.' The phrase 'when you and the user have just discussed a fact worth remembering long-term' adds useful context and gives an example trigger phrase. It does not explicitly compare against sibling tools like create_note or quick_capture, so it loses a point for 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?

The description gives a clear condition for use: 'Use this when you and the user have just discussed a fact worth remembering long-term, e.g. "add this to my reviews".' This provides strong contextual guidance. It does not explicitly say when not to use it or name alternatives, so it is not a full 5.

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

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

With no annotations, the description carries the full behavioral burden, and it handles this well: it discloses the open-or-create semantics, the auto-linking to yesterday/tomorrow, and the exact behavior of returning an existing page with `created: false`. This is substantive behavioral context rather than just a restatement of the tool's 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?

The description is three focused sentences with no filler. Every sentence adds a distinct piece of useful information: purpose, naming/linking behavior, and return behavior.

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

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

For a single-optional-parameter tool with no output schema, the description covers the important operational details: how the note title is derived, the linking behavior, and the idempotent return. Some details can be inferred, so it's complete enough for a simple, focused tool.

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

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

Schema description coverage is 100%, so the parameter is already fully documented in the schema. The description reinforces the date concept and default but doesn't add new meaning beyond what the schema already provides, so it earns the baseline score of 3.

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 action ('Open or create the daily note') and a clear resource ('daily note'), making the tool's core purpose obvious. The slug pattern and auto-linking constrain scope, but it doesn't explicitly distinguish itself from the sibling create_note, so it stops short of a 5.

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

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

The tool's usage context is implied: it is the tool for daily notes, with today or a specific date, and the schema shows the date parameter is optional. However, it never explicitly says when to prefer this over other creation tools like create_note or when not to use it, leaving the agent to infer the boundaries.

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

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

With no annotations, the description carries the burden of behavior disclosure. It discloses the creation side effect, template expansion behavior, standard template variables, custom variable support, and error behavior for existing slugs. It does not mention return values or any access considerations, but the core behavioral traits are clearly conveyed.

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

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

The description is compact, front-loaded with the action and purpose, then provides behavioral caveats. Every sentence earns its place: when to use, template/variable behavior, and error alternative. No padding 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?

For an 8-parameter creation tool with no output schema, the description covers most of what an agent needs: purpose, template mechanics, at least one accepted input, and the failure mode. It doesn't document return output or some remaining fields, but the core success path and failure behavior are present, so it is reasonably 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 50%, so the description must partially compensate. It adds value by explaining the relationship between title/content and template, and by enumerating the variables injected into a template. However, parameters like kind, tags, and project receive no additional semantic meaning beyond shallow schema names, leaving some parameter intent under-specified.

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

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

The description names a specific action and resource: 'Create a new wiki note.' It then lists concrete use cases (capturing a thought, starting a research page, building a meeting/person/project page) and distinguishes itself from extend-style siblings by warning against existing slugs. This is enough for an agent to tell it apart from related tools like append_to_page.

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

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

The description gives clear when-to-use guidance: capturing thoughts, research pages, and template-based pages. It also provides an explicit when-not-to-use path: 'Existing slugs cause an error — use append_to_page or update_note_section to extend.' This leaves little ambiguity about choosing this tool over 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?

No annotations are present, so the description must carry the behavioral burden. It does indicate the primary behavior: collecting a page and neighbors up to N hops into a markdown bundle. However, it doesn't clarify potential side effects (if any), return delivery mechanism (file vs inline), or operation limits, leaving some ambiguity.

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, focused sentence with no filler or repetition. It front-loads the action ('Export') and clearly packs the core semantics into a compact phrase.

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

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

The tool has no output schema and annotations none, so its complete behavior must be described. The description leaves gaps: the default value/fmax for depth, how the bundle is delivered, and prerequisites (e.g., permissions or an existing graph). Given the tool includes two parameters and is part of a rich sibling set, this description is insufficient for fully correct use.

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

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

Schema description coverage is 0%, and the description does not explicitly map 'slug' or 'depth' to the mentioned page/hopping limits. 'page' hints at 'slug' and 'N hops' hints at 'depth', but the mapping is implicit rather than stated. Since the schema itself provides no additional guidance, this insufficient compensation for the 0% coverage.

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 precise verb ('Export') and a clear resource ('a page + connected neighbors up to N hops'), naming the output format ('self-contained markdown bundle'). This distinguishes it from sibling tools like 'read_wiki_page' (which reads one page) and 'find_related' (which finds related items without exporting).

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 provides no explicit guidance on when to use this tool, when not to use it, or which sibling tools might be preferable for simpler tasks like exporting a single page. The usage context is only implied by the word 'Export' and the 'subgraph' concept.

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

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

With no annotations provided, the description carries the full transparency burden. It explicitly discloses a key behavior: it returns only contradictions and not a full synthesis. This is useful beyond the tool name, although it does not describe edge cases like when no contradictions are found.

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 compact and front-loaded: it states the core action first, then the output constraint, then the use case. Every sentence earns its place and there is no redundant 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 simple one-parameter diagnostic tool with no output schema, the description covers what the tool does, what it returns, and when to use it. It could be more specific about the output shape or empty-result behavior, but these are minor gaps given the tool's low 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 0%, so the description must compensate. It does tie the single parameter topic to the search target ('on a given topic'), which is a basic but sufficient mapping. However, it does not clarify topic format, specificity, or whether exact page names versus general queries are expected.

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: 'Find self-contradictions in the wiki on a given topic.' It also clarifies the result scope — contradictions only, not a full synthesis — which helps distinguish it from tools like synthesize_topic or find_gaps.

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

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

The description gives a clear when-to-use signal: 'Useful when the user wants to reconcile evolving views.' It also implies a limitation ('no full synthesis') that steers agents away from using it for general overviews, though it does not explicitly name alternative tools.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only says it 'returns LLM-suggested missing pieces' but does not say whether it reads wiki content on demand, whether it can call external knowledge, or what side effects or costs exist. The behavioral surface is largely undisclosed.

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 compact and clear, with a well-chosen example that adds meaning without bloating the text. It could be slightly tighter, but the two sentences work well together and there is no wasted 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?

This is a low-complexity tool with one parameter and no output schema, so the description is close to being sufficient for the core task. However, it lacks information such as how the topic is matched against wiki content, what happens when there are no gaps, and whether the operation depends on existing wiki resources.

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 single parameter 'topic' has no schema description (0% coverage), and the tool description does not clarify what format 'topic' should take (e.g., page title, natural language phrase, or filename). The output example implies the topic is user-supplied, but provides no parameter-level guidance.

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 action ('find gaps') on a concrete resource ('the wiki's coverage of a topic') and clarifies the output with a useful example. It is distinguishable from sibling tools like find_orphans or find_contradictions, though it does not explicitly name alternatives.

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 intended use case (identifying missing wiki coverage for a topic) is implied clearly, and the example output helps set expectations. However, the description does not state when not to use it or mention related alternatives such as synthesize_topic or find_contradictions.

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

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

No annotations are provided, so the description carries the behavioral burden. 'List' implies a read-only operation and no modifications, and the meaning of orphans is explained. However, it does not disclose possible scope limits, how the output is shaped, or whether the graph traversal includes only internal links.

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, compact, front-loaded sentence communicates the resource and the filtering condition with no filler, while also defining the domain term 'orphans'.

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 read-only listing tool, the description is nearly sufficient: it states what is returned and why. It could be slightly more useful if it mentioned the exact output fields, such as page IDs or titles, but the current wording remains adequate.

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

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

The tool has zero parameters and the schema documents 100% of them. The description itself defines the core semantic concept, orphans, which compensates for the absence of parameters.

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 the specific verb 'List' with resource 'wiki pages' and clarifies the exact filter condition: 'no incoming links (orphans)'. This clearly differentiates it from sibling tools like read_wiki_page, list_recent, and find_related.

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

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

The description gives clear context: use this tool when you want wiki pages that have no incoming links. It does not explicitly name alternatives or exclusions, but the orphan condition itself is the usage trigger and no sibling offers the same purpose.

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

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

With no annotations, the description must carry the behavioral disclosure and it does meaningfully: it states the result is a ranked list, that each entry comes with a connection reason, and that traversal is based on links, tags, and sources. It does not describe failure behavior or edge cases, but the read-style and output behavior are disclosed clearly.

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 entire definition is one focused sentence that states the action, the conditions, and the output format. No filler or redundant information is present, and the core behavior 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?

Given the low schema coverage for slug and no output schema, the description provides the essential behavior but not details like possible failure cases, limits of the ranked list, or how this differs from sibling graph tools. It is adequate for a basic call, but an agent must infer several edge conditions.

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

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

The schema documents depth with a range and default, while slug is only defined by its type. The description lends some context by referring to 'a given page,' which maps to the slug parameter, but it does not explicitly describe that slug is a page identifier or how depth affects traversal beyond what the schema provides.

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

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

The description names a specific action and target: it finds pages connected to a given page, and it identifies the exact connection mechanisms (wikilinks, shared tags, shared sources). It also distinguishes itself from sibling tools that search, read, or recommend pages by framing a relation-aware lookup with a ranked result.

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 intended use case is implied: use this when needing pages connected to a given page via links, tags, or sources. However, it gives no explicit guidance about when not to use it or which sibling alternatives might fit better, leaving the agent to infer the boundary against tools like semantic_search or get_graph_insights.

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

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

With no annotations, the description carries the behavioral disclosure burden. It adds meaningful behavior beyond the name: no email is sent, the default lookback is 24 hours, and citations are included. It could go further on whether anything is persisted or whether credentials/permissions are needed, but it is reasonably transparent.

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

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

The description is two sentences with no fluff. The core purpose is front-loaded, followed by the most important behavioral caveat and the alternative. Every sentence contributes.

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 generation tool with no output schema and no annotations, the description covers the main things an agent needs: what it produces, the default range, and the critical 'does not email' caveat. It is slightly light on what the response looks like, but this is an acceptable gap given the schema already covers inputs.

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 fully documents both parameters. The description reinforces the 24h default that matches since_hours but adds no new parameter-level meaning beyond what the input schema provides.

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

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

The description names a specific verb ('Generate') and a specific resource ('morning brief' summarizing recent wiki activity). It also cites the lookback default and content type, making the tool's role immediately clear while distinguishing it from generic search or list tools.

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

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

The description explicitly states what the tool does not do ('Does not email') and provides a concrete alternative ('use the web UI Settings → Daily Brief → Send Now'), giving the agent actionable when-to-use versus when-not-to-use 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?

There are no exploreIntents, so the description carries the full burden, but it only lists what it computes. It does not state whether this is a safe read-only analysis, whether it can be expensive on large wikis, or what form the results take. The get_ prefix implies a read, but nothing in the description confirms 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?

A single sentence that front-loads the verb and resource and immediately enumerates the outputs. It earns its place with zero filler, but the terse style also means useful behavioral and usage context is absent.

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

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

For a zero-parameter tool with no output schema, the description is close to sufficient from an invocation standpoint. However, the lack of any note distinguishing it from find_orphans and run_wiki_health, plus no hint about the shape or volume of returned insights, leaves meaningful 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?

The tool takes zero parameters, so there is nothing for the description to explain. Schema coverage is 100% by construction, and the description correctly communicates that this is an analysis over the whole wiki, which is the only relevant semantic content.

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-plus-resource structure ('Compute graph insights for the wiki') and lists concrete outputs: top hubs, orphans, broken links, fragmented tag clusters. It makes the tool's goal clear, though it does not explicitly distinguish it from overlapping siblings like find_orphans or run_wiki_health.

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

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

No guidance is given on when to use this tool versus alternatives. The wiki contains find_orphans, run_wiki_health, and suggest_links that could overlap, but the description neither names them nor explains what makes get_graph_insights the right choice.

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

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

With no annotations provided, the description must carry the behavioral disclosure burden. 'Get' implies a read operation and the returned metric categories are named, but the description does not say what 'refresh' does, whether it recomputes or clears anything, or what the response structure looks like.

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 compact and front-loaded: it states the resource and scope in the first clause, enumerates the output categories, and adds one useful application sentence. There is no redundancy or 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?

The description conveys the tool's basic purpose and output categories, which is enough for basic selection, but because there is no output schema, refresh is undocumented, and no alternative tools are compared, the context is not fully fleshed out.

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 only documents date, and coverage is 50%, so the description should compensate for the undocumented refresh. The description adds some meaning around date ('today or a specific date') but says nothing about what refresh controls, how it behaves, or when to set it.

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

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

The description states a specific verb and resource: getting a wiki pulse for today or a specific date, and lists the included metrics. It does not explicitly contrast this with nearby siblings such as generate_daily_brief or run_wiki_health, so it is clear but not fully differentiated.

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

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

The description explicitly recommends using this tool to provide daily situational awareness of the user's knowledge base. However, it gives no when-not-to-use guidance or mention of alternatives, so it stops short of full usage guidance.

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

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

With no annotations, the description carries the disclosure burden. It explains the potentially surprising default that omitted action ids are approved, indicates that the tool creates/updates data, and describes the return value. It doesn't cover failure modes or reversibility, but the key side-effect behavior is clearly disclosed.

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 deliver all essential information: role, workflow position, approval semantics, and return value. There is no filler, and the description is front-loaded with the most important context.

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 tool with no output schema, the description covers input provenance, the approval semantics, side effects, and result summary. Minor gaps around failure behavior and atomicity prevent a 5, but an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, and the schema already fully documents both planId and approvals, including the omission-default behavior. The description reinforces that behavior but adds no new parameter-level 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?

The description names a concrete verb ('commits') and resource ('a plan returned by ingest_plan'), and positions itself as step 2 of 2 in the conversational ingest flow. This directly distinguishes it from ingest_plan and other ingest-related siblings.

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

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

It clearly signals sequencing: this is step 2, it acts on a plan produced by ingest_plan, and it commits only the user-approved subset. It does not explicitly list exclusions like 'use ingest_plan when creating a plan', but the workflow context is clear enough for an agent to decide correctly.

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

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

With no annotations, the description carries the transparency load. It clearly states the tool reads the source and 'without writing anything yet', which signals a side-effect-free planning pass, and it exposes the user-review/approval gate. It stops short of explaining how/where the plan is stored between the two steps and what exact identifier is 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 cover what the tool does, what it returns, the no-write caveat, and the exact next tool call. Every clause adds information and there is no redundant restatement of parameter names.

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-step flow with no output schema, it covers the main contract: input, narrative takeaways, structured plan, no persistence, and the follow-up execute call. It doesn't describe the exact output shape or how planId is surfaced, which is the only notable 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 the schema already documents all four parameters clearly. The description adds only workflow-level context around planId and approvals, not per-parameter semantics, which is acceptable but not extra value.

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

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

The description names a concrete pipeline stage ('step 1 of 2'), says it reads the source and returns narrative takeaways plus a proposed action plan, and explicitly clarifies that nothing is written yet. This makes the tool distinct from its sibling ingest_execute and other content-creation tools.

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

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

It gives clear usage context: use this tool first when the user wants a reviewable ingest plan, and only after approval call ingest_execute(planId, approvals). It does not explicitly compare itself with ingest_source, so alternative selection is slightly incomplete rather than fully explicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by explicitly stating side effects: saving raw text, running an LLM compile that creates/updates pages, applying cross-linking, and returning a change summary. It does not mention costs, delays, or reversibility, but the core mutation behavior is clearly disclosed.

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

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

One focused sentence with the main action first, followed by the key processing steps and return value. Every clause contributes meaning; there is no filler or redundant restating of the tool name.

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

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

For a mutation tool with no annotations and no output schema, the description covers the key context: what the input represents, what processing happens, and what the agent should expect in response. It could be more explicit about alternatives, but the core information needed to invoke it correctly is present.

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

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

Schema coverage is 67%: title and source_url already have descriptions. The description's phrase 'raw text' adds partial meaning to the undocumented text parameter, clarifying it is the source content to ingest. However, it does not fully compensate for the absence of a text schema description or explain any formatting/size constraints.

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-resource pairing ('Ingest a new source into the wiki') and enumerates concrete effects: saves raw text, runs LLM compile, applies cross-linking, returns summary. It does not explicitly differentiate from sibling tools like ingest_plan or ingest_execute, but the action is clear enough that an agent can identify what it does.

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 the tool is for adding new source material to the wiki and processing it into pages, but it does not explicitly state when to prefer this tool over alternatives such as quick_capture, save_chat_excerpt, or ingest_plan. There is no when/when-not guidance or named 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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It does communicate that the operation lists saved chat sessions and sorts newest first, but it does not clarify whether sessions are read-only, what 'recent' means, how results are limited, or whether any implicit state changes occur.

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 efficient sentence with no filler. It front-loads the core action and sorting behavior, making it easy to parse quickly.

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?

Without annotations, an output schema, or parameter descriptions, the description is too thin to fully support correct invocation. An agent cannot infer default time windows, limit semantics, or the exact contents of the returned chat session list.

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

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

Schema description coverage is 0%, and the description provides no explanation of the 'days' or 'limit' parameters. The parameter names hint at their meaning, but the description adds no value beyond the bare schema.

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

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

The description states a clear action and object: list chat sessions saved in MindBase, ordered newest first. It is specific enough to identify the tool's function, though it does not explicitly distinguish itself from sibling tools like recall_chat or list_recent.

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

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

No guidance is given about when to use this tool versus alternatives such as recall_chat or list_recent. The description implies it is for browsing saved chat sessions, but it does not state exclusions, prerequisites, or preferred context.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It communicates that this is a read-only listing operation and reveals the output contents, including last poll time, items ingested, and errors, which gives the agent a solid expectation of side-effect-free behavior and return information.

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 two tight sentences: the first defines the action and output, the second gives concrete invocation examples. Every part adds useful information with no 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?

For a zero-parameter read-only list tool, the description is complete. It clearly indicates the resource, the user scope, and the contents of the returned data. No output schema exists, but the description provides what is needed for an agent to call and interpret the result.

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 the schema already covers everything. The description adds no parameter-level information, but none is needed. This matches the baseline of 4 for tools with no parameters.

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: 'List all RSS feeds the user is subscribed to.' It also specifies the return scope by listing the included stats, making the tool’s purpose unmistakable and distinguishing it from sibling tools like add_rss_feed and ingest_source.

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 provides when to use the tool with natural language triggers: "what feeds am I subscribed to?" or checking RSS subscriptions. It gives clear context but does not mention when not to use it or name alternatives, so it stops short of including 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?

No annotations are provided, so the description carries the full disclosure burden. It states the ordering but leaves the notion of 'newest' ambiguous—is it creation time or last-update time? It also does not disclose what each returned page entry contains (title, excerpt, just ID?) or how pages updated multiple times within the window are deduplicated. These behavioral gaps are meaningful for an ordering-based time range 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?

Single sentence, zero filler. It front-loads the verb and resource, then adds temporal filtering and ordering. Every word 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 list tool with full schema coverage, this is mostly adequate; however, with no output schema and no annotations, the description should clarify the return shape and the ordering key. Without that, an agent invoking the tool cannot fully anticipate whether subsequent calls are needed (e.g., read_wiki_page for content).

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 input schema already documents both parameters fully (days with default 7, limit with default 20 and max 100), so the baseline is 3. The description does not add parameter-level semantics beyond the schema, which is acceptable at 100% coverage.

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 ('List'), a concrete resource ('wiki pages'), and precise temporal scope ('added or updated within the past N days') with ordering ('newest first'). This clearly distinguishes it from sibling tools like search_wiki, read_wiki_page, and find_related without needing to open 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?

The description establishes clear contextual usage: any time you want recently added/updated wiki pages rather than search or semantic retrieval. It does not explicitly name when-not-to-use alternatives, but the temporal filter and ordering make the intended scenario obvious among the sibling tools.

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

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

With no annotations provided, the description carries the full behavioral burden and handles it well by stating that the tool 'returns cards due now' and explaining the default due_only=true behavior. It does not go into greater detail about return structure or side effects, but for a read-only list-style tool it gives solid behavioral transparency.

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 compact and effective: it nails the purpose, default behavior, and the usage workflow in just two sentences. Every sentence carries functional value and the workflow instruction 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 simple optional-parameter list tool, the description is mostly complete: it specifies the default behavior and the intended interaction pattern. It would be stronger if it explicitly described the shape of the returned cards, especially since there is no output schema, but the description still gives enough context to invoke the tool correctly.

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

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

The input schema already documents both parameters with 100% coverage, so the baseline is 3. The description does not add meaningful new parameter semantics beyond restating the due_only default, which is already present 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?

The description clearly states a specific action ('List spaced-repetition review cards') and resource, making the tool's purpose immediately identifiable. It also clarifies the default behavior (due-only cards), which distinguishes it from generic list/recent tools among the 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 description gives clear situational context: 'Use this to conduct an interactive review session' and outlines the exact workflow from listing to answering cards. It identifies the follow-up tool (answer_card) but does not explicitly mention when not to use it, such as for non-due or non-review card listing.

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 description discloses a side effect: appending a structured entry to a daily log file, and the exact format used. However, with no annotations and no output schema, it does not say whether the file is created if missing, what the return behavior is, or how projectId affects which log file is used.

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 concise and front-loaded: one clear sentence states the action and target, followed immediately by the required entry format. No content 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 simple append operation, the path and format give enough to make a basic call successfully. Still, the lack of return information, explicit side-effect description, and usage distinction from nearby write/log tools leaves meaningful 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?

The schema already documents operation, details, and projectId meaning. The description adds value by showing how parameters map into the final log line, but it does not fully explain topic semantics or the interaction of projectId with the file path.

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

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

The description clearly states the verb ('append') and the target resource ('logs/<today>.md'), and it gives a concrete entry format. This makes the tool's purpose easy to grasp and distinguishes it from write tools like append_to_page or create_daily_note.

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

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

The description does not say when this tool should be used, nor when to prefer another tool such as save_chat_excerpt, create_daily_note, or mindbase_contribute. The format implies operational logging, but no explicit context, prerequisites, or exclusions are given.

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

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

Since no annotations are provided, the description carries the full burden, and it does well by disclosing that the tool appends to README.md, seeds context.md sections, and is idempotent. This gives an agent critical side-effect and repeat-safety information, although the exact no-op marker mechanism is not specified.

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 two sentences and each sentence carries substantive value: purpose, file-side effects, and idempotence. It is front-loaded with the core action and contains 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 simple two-parameter mutation tool with no output schema and no annotations, the description covers the essential details: what it acts on, the files it changes, and repeated-run behavior. It could be stronger with explicit return-value or failure-mode information, but those are not critical for invoking the tool correctly.

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

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

The schema documents projectId but leaves templateId completely undocumented. The description adds meaning by referring to 'template prose' and the 'same template', which implicitly explains templateId's role, but it does not fully compensate for the missing parameter-level schema 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?

The description clearly states a specific action and resource: 'Overlay a schema template onto an existing project.' It further clarifies the mechanics by naming the files affected (README.md and context.md), making the tool easy to distinguish from the other mindbase_* operations, though it does not explicitly name a sibling.

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 when to use it: when a schema template needs to be applied to an existing project. The idempotence note also gives re-run guidance. It does not, however, state when to prefer this over alternatives like mindbase_atomic_write_context or explicitly list 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?

No annotations are provided, so the description carries the full disclosure burden. It does so thoroughly by disclosing the snapshot path, the tmpwrite+rename mechanism, the appended log entry, and the 400-line cap with overflow routing to an auto-generated file.

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 compact: three sentences cover the core action, the atomic write steps, and the truncation behavior. Every sentence contributes useful information and there is no 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?

The description is complete enough for a mutation tool with no annotations and no output schema. It covers the destructive replacement, the backup snapshot, the transactional mechanism, the log side effect, and the line-limit boundary condition.

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 input schema already documents both parameters fully, with 100% schema description coverage. The description adds no extra semantics about the parameters; it focuses on the write process, which is appropriate given the schema already explains content and projectId.

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 ('Write'), a specific target ('context.md'), and a defining trait ('atomically'). This is clearly distinguishable from sibling tools that append, update sections, or contribute content, and the resource path makes the purpose 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?

The description clearly implies the tool should be used whenever an agent needs to replace or write the full context.md body with atomic safety. It doesn't mention explicit alternatives or exclusions, but none are strictly necessary given the targeted nature of the operation.

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 description explicitly states side effects: writing append-only to sources/contributors/<user>/<YYYY-MM-DD>.md and adding a log entry, plus optional routing behavior for concepts. This is valuable given no annotations were provided. It does not cover return values, errors, or permissions, but the core behavior is clearly disclosed.

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 two sentences, front-loaded with the key action and target, and then covers route-mode semantics. There is no filler, credential repetition of schema information, or unnecessary elaboration.

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

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

For a write tool with no annotations and no output schema, the description is fairly complete: it names the destination, the append-only behavior, the log side effect, and route-mode meanings. It does not describe return values or error conditions, and the phrase 'current project' could be more precise when projectId is optional, but the essential call context is present.

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

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

Schema coverage is 100%, giving baseline 3. The description adds real value for the mode parameter by explaining the meaning of each mode, which the schema only lists as a bare string. The other parameters are already described well enough 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?

The description begins with a clear active verb 'Append' and a specific resource: a contributor entry in the current project, with a concrete file path. It is unambiguous about what the tool does, but it does not explicitly differentiate from sibling tools such as mindbase_append_log or quick_capture, so the 'vs siblings' aspect is not fully addressed.

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 internal route modes (auto, daily, concept, daily+concept) but gives no guidance about when to choose this tool over alternatives or when not to use it. With many sibling save/append tools present, an agent has no explicit selection context.

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

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

With no annotations present, the description carries the burden of disclosure. It clearly states that the tool copies the project tree to artifacts/exports/<projectId>-<timestamp>/ and that zip-archive behavior additionally requires the external `zip` command if available. This gives the agent a good sense of side effects and external dependency, though failure behavior when zip is unavailable is not stated.

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 compact and front-loaded with the core purpose, followed by a terse breakdown of the two modes. Every sentence contributes meaningful information without 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?

The description covers input semantics and destination paths well, but there is no output schema and no mention of what the tool returns on success or failure. It also does not explain the behavior when `zip` is unavailable, which is a notable edge case for an otherwise simple 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?

The schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds meaning by explaining what each target value actually does and revealing that projectId is used in the output path. This goes beyond simply restating 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 clearly opens with the action and object: 'Export a project to a portable artifact.' It then differentiates the two target types by describing exact output locations. It does not explicitly distinguish itself from sibling tools like export_subgraph, but the core purpose is clear and specific.

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

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

The description explains what each target mode does but never says when a user should choose this tool over alternatives such as export_subgraph or other export-related tools. There is no explicit when-to-use or when-not-to-use guidance.

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

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

With no annotations, the description must carry behavioral disclosure. It discloses that the tool returns paths, sizes, and mtimes, which is useful, and 'List' implies a read-only operation. However, it does not explicitly state that no modifications occur, whether there are limits, or how 'last build' is tracked.

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 important scoping rule ('modified since the last build') appears up front. It compactly states the resource, filter, return fields, and intended caller.

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

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

The description satisfies mostly all the agent needs for a simple list tool even without an output schema and annotations: it names inputs, expected outputs, and a clear use case. It does not mention edge cases like empty results, ordering, or pagination, but the simple return shape makes those less critical.

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 parameters are already documented and the description does not need to add much. The phrase 'modified since the last build (or since a given ISO date)' loosely echoes the since parameter, but it adds no concrete syntax or edge-case semantics 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 clearly identifies the action ('List') and the resource ('contributor + research files') plus the modification-time filter. However, it does not explicitly differentiate itself from siblings like list_recent or list_review_cards, so the distinction is inferred rather than stated.

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

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

The phrase 'Used by /mb:build to know what to synthesize' provides a clear intended use context. It does not mention exclusions or when alternatives like list_recent should be preferred, but the /mb:build tie-in gives an agent enough situational guidance.

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

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

No annotations exist, so the description carries the full burden of behavior disclosure. It does this well by stating that it archives the original into sources/raw/<date>/, uses pdfjs locally with no API call, writes an .extracted.md sidecar for PDFs, returns the text, and downloads URLs first.

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 of dense, high-value content. No filler, the main behavior appears first, and follow-up instructions are appended at the end in a natural order.

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 without an output schema, the description tells the caller that the text is returned. It documents postconditions, input types, sidecar creation, and the recommended follow-up. For a file ingestion tool, this is 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?

Input schema covers 100% of parameters with descriptions, so the baseline is high. The description adds important semantics for the required path parameter: it can be an absolute local path or direct http(s) URL, and describes the download-first behavior. Title and projectId semantics are already adequately documented 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?

Description uses specific verb 'Ingest' with clear resource types ('file into a project'), enumerates supported types and formats (PDF, .md, .txt), and describes the concrete workflow: archive, extract, sidecar, return text. It is easily distinguishable from sibling tool names like ingest_source or ingest_plan.

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 is provided for when to use this tool: you can pass a local absolute path or a direct http(s) URL pointing to a PDF/.md/.txt file. It also prescribes the follow-up workflow (discuss takeaways and use mindbase_contribute), but it does not explicitly state when to prefer this over sibling tools such as ingest_source. No exclusions are stated but they are not needed for basic usage.

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

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

With no annotations providing safety/behavior details, the description carries the full burden and does a good job. It discloses idempotency ('Idempotent'), a refusal behavior ('refuses to overwrite existing project'), and the exact artifacts that will be created. This goes beyond the minimal 'create project' statement by describing the concrete output structure and a key behavioral guardrail.

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, high-value sentences. The first states the core purpose and the exact layout; the second communicates an important behavioral constraint. No filler or redundant phrasing, and the critical non-overwrite behavior is placed right at the end for emphasis.

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 scaffolding tool with 100% parameter-documented schema and no output schema, this description is complete. It tells the agent what happens, what is created, and the failure condition if the project already exists. Missing details like return values or template effects are not necessary here because the schema covers parameters and the tool's surface area is small.

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 itself does not add any parameter-specific meaning beyond the schema, but no extra explanation is needed because the schema already documents name, mission, and template well.

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 ('Scaffold'), a precise resource ('a new MindBase project'), and enumerates the exact v2 layout it creates. The word 'new' and the listed file/directory structure clearly distinguish this initializer from sibling tools that operate on existing projects (e.g., mindbase_load_project, mindbase_contribute). This is a strong purpose statement with no ambiguity.

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 clearly implies when to use this tool: when creating a brand-new project. It includes a strong when-not signal by stating it 'refuses to overwrite existing project,' so an agent can infer this is inappropriate for re-initializing or updating an existing project. It does not explicitly name alternative tools, but the context and wording give enough 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?

Even though annotations are absent, the description discloses the key behavioral trait: read-only by default, with a mutation path via persist=true that updates config.json currentProjectId. It also identifies what is returned—three file bodies—making side effects and return behavior reasonably transparent.

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

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

Two tight sentences capture the core behavior, default behavior, return value, and the optional side-effect switch. Every clause earns its place and the primary intent 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?

Given no output schema, the description covers what the tool returns and when it mutates state. It could add failure/edge-case behavior, but for a read-oriented project loader with 100% schema coverage it 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% and both parameters are already well explained in the input schema. The tool description mostly restates that behavior rather than adding new parameter-level meaning, so a baseline 3 is appropriate.

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

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

The description states a specific action and resource: 'Load the README + context + index.yaml for a project'. It also clarifies the default project resolution and the returned artifact, making the tool's purpose distinct from wiki-reading and search 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 description explains the default read-only usage and when to use persist=true, saying it should be used only when the caller intends to switch the active project. It does not explicitly contrast with sibling alternatives, but the context-injection intent is clear enough to guide selection.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It usefully discloses that a snapshot is written to archive/<projectId>-<unixTs>/ before migration and that the operation is idempotent. This gives an agent a meaningful safety mental model for a mutation tool, even though it does not fully detail the transformation or failure 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?

Two compact sentences state the core action, scope, a key safety behavior (snapshotting), and idempotence. There is no filler, repeated schema content, or ambiguity introduced by unnecessary prose. Every sentence carries useful 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?

The description is complete enough for a simple invocation, but there are gaps: no explanation of what happens when 'all' and 'projectId' are both supplied, no description of the outcome/status of migration, and no post-conditions beyond idempotence. Because this is a migration tool without annotations or output schema, slightly more direction would improve context.

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

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

Schema description coverage is 75%, so three of the four parameters are already explained by the schema. The description adds only the phrase 'one or all projects,' which partially helps explain the 'all' boolean. It does not add semantics for user, dryRun, or projectId beyond what the schema already provides, but it does not need to heavily compensate at 75% coverage.

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 ('Migrate'), a specific target ('projects'), and a clear transformation ('from legacy wiki/ layout to v2 layout'). It also communicates the scope parameter by saying 'one or all projects,' which distinguishes this migration operation from the surrounding read/write/wiki sibling tools.

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

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

The intended usage is implied well: use this to convert legacy-layout projects to v2 layout. However, there is no explicit when-to-use or when-not-to-use guidance, no mention of alternatives, and no prerequisite conditions like 'must be in legacy layout' or 'run only after verification.' It is adequate but not clearly explanatory.

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

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

With no annotations provided, the description carries the full behavioral burden. It clearly discloses the most important side effect: 'Always overwrites; never partial-merges.' It also previews the output shape, which helps an agent anticipate the result. It does not mention permissions or failure modes, but the core behavior is transparent.

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

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

Two sentences with no filler. The primary action and the critical overwrite caveat are front-loaded, followed by a compact and useful output-shape hint.

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

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

For a one-parameter, no-required-parameter tool, the description provides the operation, the crucial overwrite behavior, and the return shape. The input schema covers the remaining parameter detail, so essentially nothing needed to invoke the 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 description coverage is 100%, so the single optional projectId parameter is already fully documented by the input schema. The description adds no parameter-level details beyond that, so it meets the baseline for full schema coverage without exceeding it.

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

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

The description states a clear action: 'Regenerate index.yaml by scanning the project tree.' It identifies the concrete resource and output, which is specific enough to stand alone. It does not explicitly differentiate from sibling tools, but the resource and verb are 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?

There is no explicit guidance about when to use this tool versus alternatives. 'Regenerate' implies a stale or missing index, but the description never states a trigger condition, prerequisite, or which sibling tools should be considered 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?

With no annotations provided, the description carries the full load and does so well: it discloses creation vs append semantics and the automatic log entry. It stops short of describing return behavior or side effects on existing content besides appending, but the critical mutation behavior is clear.

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 very compact and front-loaded: it states the action and destination first, then the append/create behavior, then the logging side effect. Every sentence adds useful 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 write operation with no annotations and no output schema, the description is largely sufficient: it specifies destination, overwrite semantics, and log behavior. It does not describe expected return/confirmation behavior, but the schema covers parameters well and no nested or complex output is involved.

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 input schema already documents all four parameters at 100% coverage, including topic slugification and the projectId default. The description adds the file destination but does not materially extend the parameter meanings beyond what the schema provides.

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

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

The description states a clear verb (Save), a specific resource (research findings), and a precise destination path (sources/research/<slug>.md). It also clarifies the append-vs-create behavior, which distinguishes it from general write tools among the 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 intended use case is implied: use when saving research findings as markdown to the research directory. However, it does not explicitly compare itself to sibling tools like append_to_page, save_chat_excerpt, or mindbase_append_log, so an agent may need to infer when this tool is the preferred choice.

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 description explicitly states 'Read-only', which is helpful because no annotations are provided. However, it does not disclose return structure, whether the tool may read configuration files, caching behavior, or possible failure modes. It carries some of the burden but not the full 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 a single concise sentence that front-loads the resource type and immediately lists the key data points. There is no redundancy or extraneous 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?

Given the low-complexity tool with one optional parameter and no output schema, the description presents enough detail for an agent to understand what data the tool returns and that it is read-only. It could mention whether a projectId is required or how errors behave, but the core usage context is adequate.

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 already provides 100% coverage for the single projectId parameter, including a default to the current project. The description adds no additional parameter semantics, which is acceptable given the schema's clarity.

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 identifies the tool as a 'Project dashboard' and lists the specific data it reports (build time, line counts, contributor stats, operations, file counts), clearly distinguishing it from query/search tools among its siblings. It lacks an explicit action verb like 'retrieve' or 'get', but the resource and scope are 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?

No guidance is given about when to use this tool instead of alternatives such as get_pulse, list_recent, or list_review_cards. The 'read-only' note hints at safe usage but does not clarify which scenarios call for a project dashboard.

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

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

With no annotations provided, the description carries the full burden. It clearly communicates that the tool validates layout and returns a list of missing files/dirs, which implies a non-mutating check. It could more explicitly state that it makes no changes to the project, but the term 'Validate' and 'precondition guard' provide strong 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?

Two sentences, no fluff. The core behavior is front-loaded, the return value is specified, and an important usage context is included. 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 validation tool with one optional parameter, the description is complete enough. It states the purpose, the exact output, and key usage context. The lack of an output schema is mitigated by describing what is returned. It could go slightly deeper into what happens when the project doesn't conform, but it is not necessary.

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 already documents the only parameter, projectId, with a description and default behavior. The tool description adds no additional meaning about the parameter, but the schema coverage is 100%, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Validate'), a resource ('a project'), and a precise criterion ('conforms to the v2 layout'). It additionally specifies the return value ('list of missing required files/dirs'), which clearly distinguishes it from sibling tools like mindbase_migrate or run_wiki_health.

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 that the tool is used as a precondition guard by /mb:build and /mb:migrate, giving clear context for when it is appropriate. It does not explicitly mention when not to use it or name an alternative, but the context is sufficiently clear.

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

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

With no annotations provided, the description carries the full burden. It discloses that content is placed in an inbox, is not immediately turned into a wiki note, and will be processed later in the MindBase UI. While it does not mention return values or side effects, the core behavioral intent is clearly and honestly described.

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

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

The description is two sentences, starts with the core action, uses natural phrasing, and contains no filler. It even embeds the alternative tool name without unnecessary length.

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

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

For a simple two-parameter tool with no output schema, the description fully covers the essential context: what the tool does, how it should be used, and when to choose another tool. An agent would be able to invoke it correctly without further clarification.

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 input schema has 0% description coverage, and the description does not explain the 'tags' parameter at all. However, 'content' is made meaningful through the phrase 'Save content to the inbox,' and 'tags' is a self-evident optional array. The description only partially compensates for the missing schema detail, so the baseline is modest.

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

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

The description clearly states the verb ('Save'), resource ('inbox'), and purpose ('later batch processing'), and explicitly distinguishes this from creating a direct wiki note. It is unambiguous and easily differentiates from the sibling tool create_note.

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 provides explicit when-to-use guidance ('save this for later, I will categorize it myself in the MindBase UI') and names the exact alternative (create_note) for when a direct wiki note is needed. This gives the agent a clear decision rule.

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

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

With no annotations provided, the description carries the behavioral burden. It does disclose exactly what content is included in the response (body, frontmatter, incoming/outgoing wikilinks), which is useful. It does not mention behavior for missing/invalid slugs or note that this is a read-only operation, though 'Read' strongly implies it.

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

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

The description is one concise, front-loaded sentence. The main action and resource appear immediately, with the content breakdown in parentheses adding value without bloat.

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

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

For a simple read-by-identifier tool with one required parameter, the description covers the input, the operation, and the returned content. The absence of an output schema is partially compensated by the explicit content list, though error behavior and page-not-found handling are not mentioned.

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 input schema already fully describes the single slug parameter with an example, so the description adds no additional parameter-level meaning. Per the baseline for high schema coverage, a 3 is appropriate.

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

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

The description uses a specific verb ('Read') and resource ('wiki page by slug') and explicitly enumerates what content is returned: markdown body, frontmatter, and wikilinks. This clearly distinguishes it from sibling tools like search_wiki or find_related, which do not retrieve full page content.

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

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

The description implies the correct use case: when you already know a page's slug and want its full content. However, it does not explicitly tell the agent when to prefer this over search_wiki or find_related, leaving the decision partially to inference.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It conveys that the operation is a read-only style search and that previews will be returned, which is useful, but it does not disclose ordering, truncation, pagination, or how matches are determined.

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 concise and front-loaded: two short sentences that define the operation and the return behavior. It wastes no words, though it could have used the available space to clarify the 'limit' parameter.

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 search tool the description is minimally viable, but with no output schema and no annotations, the description should more fully clarify result behavior and the optional 'limit' parameter. It is also missing guidance that distinguishes recall_chat from semantically similar sibling tools.

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

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

Schema description coverage is 0%, so the description must compensate for the bare 'query' and 'limit' fields. The description clarifies that 'query' is a content-search term, but it says nothing about 'limit', which remains an unexplained number. This is only partial compensation.

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

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

The description clearly states the tool's function: searching saved chat conversations by content and returning matching chats with previews. It is specific about the resource ('saved chat conversations') and distinguishes itself from general wiki/project search tools in the sibling list, though it does not name a specific sibling to contrast 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?

There is no guidance on when to use this tool versus alternatives such as list_chats, semantic_search, or search_in_project. The description implies a content-search use case, but an agent is left to infer the boundary between searching past chats and searching other resources.

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

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

With no annotations provided, the description carries the full behavioral burden. It explicitly discloses that the tool writes a file and applies improvements, which is good, but it leaves the actual scope of 'applies improvements' and potential side effects of auto cross-linking unspecified.

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

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

One dense, well-structured sentence front-loads the action and then compactly lists the pipeline steps. There is no empty phrasing or repetition of obvious 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 zero-parameter mutating tool, the description covers the full pipeline and the primary artifact (_insights.md). It does not describe a return value, and no output schema exists to fill that gap, but the main outcome is clearly the file and the applied improvements.

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 input schema has zero parameters, so there is no parameter detail to add. This matches the baseline for parameterless tools.

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 ('Run the full Wiki Health pipeline') and enumerates the distinct stages it executes. Producing _insights.md and applying improvements clearly sets it apart from smaller sibling tools like get_graph_insights or suggest_links.

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 this is the go-to tool when a complete wiki health run is requested, but it never explicitly says when to use it instead of one of the more focused sibling tools. No regard to exclusions or alternative selection is given.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does so reasonably well by revealing that the LLM auto-titles the page when no suggested_title is provided and that a created_via: mcp marker is added for audit. It does not dwell on failure modes or permission effects, but the most relevant behavior is exposed.

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 compact, front-loads the central write action, and adds two substantive behaviors in a second short sentence. Nothing feels wasted, though additional structured routing or an explicit alternative could make it slightly more 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 3-parameter create-style tool with no output schema, this description covers the main purpose, the auto-title edge case, and the audit stamp. It does not explain return/confirmation behavior or the exact semantics of source_chat_id, but the agent can still invoke the tool correctly in the common content-only case.

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 input schema has 0% description coverage, so the tool description must compensate. It gives meaning to content via 'fragment of the current AI conversation' and explains the fallback when suggested_title is absent. However, source_chat_id is never explicitly described, leaving one of three parameters only inferable from its name.

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

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

The description names a concrete action and resource: saving a fragment of the current AI conversation as a wiki page. It also adds distinguishing behaviors such as auto-titling and the created_via audit marker. It does not explicitly contrast itself with sibling creation tools like create_note or quick_capture, so it is clear but not fully differentiated.

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

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

The description implies usage context: you use this when you want to preserve a fragment of the current AI conversation in the wiki. It does not state when to prefer this over alternatives, nor does it give exclusions or conditions for choosing a sibling tool among the many creation/capture tools.

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

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

With no annotations, the description carries the full burden of explaining behavior. It satisfactorily conveys that the tool performs a global search, returns ranked matches with owning IDs, and is suited for generating wikilink citations. It does not explicitly describe side effects or state that it is read-only, but for a search operation the behavior is sufficiently clear.

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 three short sentences with every sentence carrying meaningful information: the first sets the scope, the second defines the output, and the third gives concrete usage cases. There is no filler or redundant repetition.

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

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

For a tool with no output schema, the description provides a useful picture of the return format (project id and slug for wikilinks). It doesn't enumerate the full JSON result structure or clarify behavior for extreme cases, but it is enough for an agent to decide to use the tool and know what to expect.

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 parameters already have accurate descriptions in the schema. The tool description adds contextual value for the project scope (esp. crossProjectOnly) but does not provide additional detail beyond what the schema already documents, so it stays at the baseline for fully covered 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?

The description uses a specific verb ('Search'), names the precise resource ('the user's wiki'), and emphasizes the scope ('across EVERY project, not just the current one'), which strongly differentiates it from project-scoped siblings like search_in_project or search_wiki. It also explains the main output (ranked matches with project id) and the intended wikilink format, leaving no doubt about what the tool does.

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 tells the agent when to use this tool: for 'have I seen this' queries and for proposing cross-project bridges during ingest. The contrast with the current project is implicit through 'not just the current one', but it does not name an explicit alternative or provide 'when not to use' guidance, so it falls 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?

Without annotations, the description carries the behavioral burden; it does disclose a key behavior by explaining the dependency on the 'project' frontmatter field. It does not state whether the operation is read-only, what return structure to expect, or how the search matching behaves.

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

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

One compact sentence, no filler, and the key scoping behavior is front-loaded. Every word contributes to the tool's meaning.

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 search tool, the core mechanics are captured. But with multiple search-related siblings and no output schema, an agent would benefit from explicit alternative-selection guidance and a clearer statement of return 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 description coverage is 0%, so the description must compensate. It meaningfully clarifies the 'project' parameter by tying it to the frontmatter field, but 'query' and 'limit' are left to name-based inference.

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

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

The description names a specific action ('Search'), a resource ('the wiki'), and a clear scope ('restricted to pages tagged with a specific project'). This distinguishes it from a general wiki search, though it does not explicitly name sibling tools.

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

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

The intended use case is implied: use it when you need a search restricted to a specific project tag. However, there is no explicit comparison to search_wiki, search_all_projects, semantic_search, or other 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?

With no annotations, the description carries the full burden. It discloses what content is matched (titles, one-liners, slugs), the full-text nature, and the return format (ranked list, snippets). It does not discuss rate limits or auth, but for a read-only search tool the main behavioral attributes are clearly articulated.

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 succinct, information-dense sentences. The scope and output are presented immediately with no filler, making it easy for an agent to scan and understand the core behavior quickly.

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

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

For a simple two-parameter search tool with complete schema documentation, the description is largely adequate. However, the lack of any filtering guidance or mention of what it searches (project, whole wiki, etc.) and the absence of sibling differentiation mean that in the large tool collection, an agent may not be able to confidently pick this tool over other search tools.

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 input schema already fully documents both 'query' and 'limit' with types, constraints, and defaults. The description adds minimal parameter-specific meaning; it focuses on behavior rather than adding semantic value to the parameters themselves.

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

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

The description clearly identifies a specific verb ('search'), a resource ('user's MindBase wiki'), and the matching target fields ('page titles, one-liners, and slugs'). It communicates that this is a full-text search tool, which helps separate it from semantic_search and other smarter search siblings, though it does not explicitly name any sibling.

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

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

No guidance is provided about when to use this tool instead of the many nearby search-related alternatives like 'search_in_project', 'search_all_projects', 'semantic_search', or 'ask_question'. The agent must infer usage from the name and broad resource scope.

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?

There are no annotations, so the description must carry the behavioral disclosure burden. It usefully reveals the fallback from embeddings to keyword search, which is genuine behavioral context, but it does not describe the result shape, ranking behavior, or what happens when the search returns no matches.

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 carry the core function and an important fallback behavior with no filler. The primary purpose is front-loaded and the secondary behavior follows naturally.

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

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

The description is adequate for a simple search tool but leaves gaps: no annotations exist, no output schema is provided, and the description does not describe return values, the role of limit, or the relationship to sibling search tools. The fallback mention adds useful context but does not fully round out the calling picture.

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

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

Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. It provides minimal context for 'query' by describing semantic search, but 'limit' is completely unexplained, including its effect or default behavior.

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

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

The description clearly identifies the tool as semantic search over the wiki, which is a specific verb and resource. It does not explicitly differentiate itself from sibling search tools like search_wiki or search_in_project, 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?

The description implies the tool should be used when embedding-based semantic matching is needed, and mentions fallback behavior when embeddings are unavailable. However, it does not explicitly state when to prefer this over search_wiki or when keyword search would be a better choice.

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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It does disclose an important behavioral trait: 'internal' and 'pii' pages are excluded from semantic search and Q&A by default. However, it does not cover permissions, reversibility, response behavior, or whether existing search indexes are updated.

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 two sentences with no wasted words. The action is front-loaded, and the second sentence adds materially useful behavior. It avoids repeating schema 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 mutation tool with no annotations and no output schema, this description is acceptable but not complete. It explains the main effect of visibility on search behavior but does not explain what happens to already-indexed pages, whether public pages are indexed by default, or what the caller should expect after performing the operation.

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

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

The schema has 0% description coverage, so the description must compensate for the parameters. It adds meaningful semantics to the 'level' enum by explaining the behavior of 'internal' and 'pii'. The 'slug' parameter is not explicitly described, though 'wiki page' makes its purpose reasonably inferable.

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 ('set') and a clear resource ('visibility level of a wiki page'). It also specifies the three levels without naming a sibling, so the function's purpose is clear. It does not explicitly contrast it with sibling tools, but the visibility-specific scope is distinctive enough.

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 provides no explicit when-to-use or when-not-to-use guidance. The statement that 'internal' and 'pii' pages are excluded from semantic search and Q&A implies a relevant consequence, but it does not tell an agent when to choose this tool over related tools like 'tag_note', 'update_note_section', or 'append_to_page'.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and explicitly discloses the most critical behavioral trait: the tool does NOT modify the page. It does not describe what kind of suggestions are returned or whether errors occur for missing pages, but the primary side-effect boundary is clearly stated.

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 one short, front-loaded sentence with the essential behavior first and the important non-mutating clarification in a parenthetical. Every word contributes meaning; no filler or repeated references to already-structured data.

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

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

For a simple single-parameter review-type tool without annotations or an output schema, the description covers the core behavior, the target page, and the non-modification guarantee. The only minor omission is an explicit statement about the form of returned suggestions, but 'suggest' sufficiently implies the result is a list of wikilinks.

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

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

Schema description coverage is 0% and the description does not directly explain 'slug', but the phrase 'a specific page' clarifies that slug identifies the target page. Naming conventions or required format for slug are not supplied, though the single-parameter simplicity reduces risk.

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 ('suggest'), a clear resource domain ('wikilinks'), and a target ('a specific page'), while the parenthetical 'review mode — does NOT modify the page' distinguishes it from write-oriented sibling tools like append_to_page or update_note_section. This removes ambiguity about what the tool does.

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 indicates this is a review-mode operation and should not to be used when a mutation is desired, but it never names alternatives such as find_related or read_wiki_page or states explicit conditions for choosing this tool over them. The usage context is implied rather than stated.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It adequately discloses caching behavior, how to regenerate via force_refresh, and the output structure. It stops short of explicitly stating whether the operation is read-only, how stale cached results may be, or any side effects, leaving some ambiguity.

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 compact, purposeful sentences. The primary action comes first, the output content is stated in the second sentence, and the caching/refresh behavior is cleanly tucked into the third. No filler or duplicated schema content.

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

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

Given no output schema, the description sensibly names the core return elements: threads, row-level citations, contradictions, and gaps. It also covers caching and refresh behavior. It could say a little more about the thread structure itself, but the essentials for selecting and calling the tool 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?

The schema only documents topic ('slug or free text') and leaves force_refresh without a description. The tool description compensates by explaining force_refresh: 'pass force_refresh: true to regenerate.' This adds useful semantic meaning beyond the raw schema, and topic's semantics are already reasonably covered by 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 ('synthesize'), a clear resource (the user's wiki collectively), and a distinguishable deliverable: structured threads with row-level citations, contradictions, and gaps. This naturally contrasts with sibling tools like search_wiki or read_wiki_page, making the purpose obvious.

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 when to use it: when collective synthesis, not simple retrieval or search, is desired. It also gives a concrete usage tip for force_refresh. However, it does not explicitly name alternatives or state when not to use this tool, so the routing guidance is implied rather than explicit.

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

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

No annotations are provided, so the description must carry the behavioral burden. It does so by disclosing the side-effect differences between the modes, especially that replace overwrites existing tags. However, it does not address whether the page must already exist or whether the operation is reversible.

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 two efficient sentences. The main operation is front-loaded and the mode semantics are packed into a compact, unambiguous note.

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 three-parameter tool with no output schema, the description covers the essential behavior and mode semantics. It does not include details like error handling or expected preconditions, but those are less critical given the straightforward scope.

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 no parameter descriptions, so the description must compensate. It usefully explains the mode parameter and its default, but it does not explicitly define slug as the wiki page identifier or what format tags and slug should take beyond vague hints in the operation statement.

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

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

The description clearly states a specific operation: add or replace tags on a wiki page. This distinguishes it from sibling tools like search_wiki, read_wiki_page, create_note, and update_note_section, none of which directly manage tags.

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 two usage modes and their semantics: add merges with existing tags and is the default, while replace overwrites. This gives an agent enough context to pick the right mode, though it does not explicitly discuss exclusions or how to decide between this and other tools.

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

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

Since no annotations are provided, the description must carry the full behavioral burden. It does so substantially by disclosing the refusal behavior for human-edited pages unless force:true is set – a non-obvious and important guard. It does not describe destruction/overwrite details or error responses, but the core guard is transparent.

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

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

Two concise sentences, no filler. The action is front-loaded, and the critical guard condition is stated immediately in the second sentence, making it easy for an agent to scan and understand.

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 mutation tool with no annotations and no output schema, the description is somewhat thin: it does not state what happens when the tool declines (e.g., error vs. no-op), does not explain how to identify a human-edited page, and doesn't clarify interpretation of the failure. It is adequate for basic invocation but not complete for all reasonable queries.

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

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

Schema description coverage is 0%, so the text must compensate for the schema's bare parameter definitions. The description meaningfully clarifies section, new_content, and force (indirectly), but slug is left unexplained, no value formats are given, and no example shows the full call signature.

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 ('Replace') and states precisely what is replaced (content under a section heading on an existing page). The phrase 'on an existing page' clearly differentiates it from create/append operations, including such sibling tools as append_to_page and create_note.

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 usage guidance is implied rather than explicit: it tells how the operation behaves, but does not explicitly state when to choose this over append_to_page, create_note, or other editing tools, and does not give exclusion cases. The safety guard is a behavioral clue, not full when-to-use guidance.

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