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

Annotations indicate write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). Description adds behavioral details: auto-creation, proposal stacking, newline handling. No contradictions.

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

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

Four concise sentences front-loaded with the main action. Every sentence adds value: core function, creation behavior, proposal interaction, output location. No waste.

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

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

No output schema, but description explains result staging at proposed/<path>. Handles all likely agent questions: what happens if page exists? if not? if proposal exists? How to get final 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?

Schema coverage 100% with descriptions. Description adds 'relative to vault root' for path and 'newline separator added if needed' for content, providing extra clarity beyond 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 'Append content to the end of a page' with specific verb and resource. It also covers edge cases like page creation and proposal stacking, which distinguishes it from sibling tools like propose_edit.

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

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

Explicitly describes when to use: append to end, create if missing, stacks on pending proposals. Also advises reading proposed/<path> for final content instead of inferring. No alternatives named but context is 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?

Annotations already indicate readOnlyHint=true, so the read-only nature is clear. The description adds the return shape but does not disclose error handling, authentication, or performance characteristics. It is adequate but not comprehensive.

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 includes purpose and return fields. It is efficient, though it could be better structured with bullet points for clarity.

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 a simple fetch with one parameter and no output schema, the description provides basic coverage. However, it lacks details on constraints (e.g., path format, accessibility) and does not differentiate from sibling tools, leaving some gaps for an agent.

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 defines 'id' as a string. The description adds meaning by stating it is a 'vault path', which is critical for correct usage. This compensates for the 0% schema description 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 clearly states it fetches a document from a vault path and specifies the returned fields. However, it doesn't explicitly differentiate from sibling tools like read_page or search, which may also retrieve vault 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?

No guidance is provided on when to use this tool versus alternatives (e.g., search, read_page, search_vault). The description merely states what it does without context on selection criteria.

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

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

Annotations already declare readOnlyHint=true, so the description correctly adds behavioral detail beyond annotations by specifying the link matching behavior. It does not contradict annotations and provides useful context about what links are matched, though it could further clarify the output format.

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 consists of two concise sentences with no unnecessary words. It is front-loaded with the core purpose and immediately provides specific details about link types. Every sentence adds value.

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

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

For a simple backlink lookup tool with clear annotations and schema, the description covers the main functionality. However, the lack of an output schema and detailed information about what specifically is returned (e.g., page paths or titles) leaves some minor gaps. Overall, it is fairly complete.

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

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

Schema coverage is 100%, with both parameters described adequately in the schema. The description adds minimal new meaning beyond repeating the schema descriptions ('Default 25.' for limit, and 'Slug or filename without extension' for target). Baseline score 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 explicitly states the verb 'Find' and resource 'vault pages that link to a target slug or filename', and specifies the link types matched ([[wikilinks]] and relative .md links). This clearly distinguishes it from siblings like search_vault or read_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 implies usage for finding backlinks but does not explicitly state when to use this tool versus alternatives, nor does it provide any exclusions or prerequisites. However, the context is clear: it's for backlink discovery.

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

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

Annotations already declare readOnlyHint=true. Description adds valuable behavioral details: cached on vault-mtime, safe to call repeatedly, and exclusion of auto-computed tags. No contradiction.

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

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

Well-structured: opens with main purpose, then specifics, then usage hint, then exclusion detail. Each sentence adds value, though slightly verbose in listing all three context types.

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 one optional parameter and no output schema, the description fully covers what the tool returns, when to use it, caching behavior, and exclusions. No 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?

Only one parameter 'refresh' with boolean type; schema coverage is 100%, so schema already documents it. Description mentions force re-scan but adds no new semantic meaning beyond the schema description.

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

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

Clearly states it reads the vault's wikilinking context and lists three specific outputs: entity slugs, active slugs, and taxonomy. Differentiates from siblings by naming propose_compile_from_raw and explicitly excluding Region/X and vibrance/X 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?

Explicitly instructs to call before propose_compile_from_raw, explaining why (real entity slugs and existing tags). Notes caching behavior and safety for repeated calls.

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 reveals specifics about each entry (path, destination, overwrite status, size, preview) and explains the effect of setting includeDelta to false, which goes beyond the readOnlyHint annotation. This provides useful behavioral context without contradiction.

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

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

Two sentences, no wasted words, the purpose is front-loaded. Every sentence adds necessary detail like the preview feature and pattern usage guidance.

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 4 parameters and no output schema, the description covers purpose, filtering, and parameter behaviors. The limit parameter's schema description already mentions totalMatched and truncated flag, so the description doesn't need to repeat that. It's sufficiently complete for effective 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 coverage is 100%, so baseline is 3. The description adds value by explaining the practical effect of includeDelta (saving file reads) and the purpose of pattern (scoping to folder/file shape), improving understanding beyond 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 clearly states the verb 'list' and the resource 'pending proposals', making the purpose immediately obvious. It distinguishes from sibling tools like 'resolve_proposal' and 'propose_wikilinks' by focusing on listing, not acting on proposals.

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 advises using the pattern filter when the queue is large, which is helpful context. However, it does not explicitly state when not to use this tool or mention alternatives (e.g., 'list_unprocessed' for unprocessed items), leaving some ambiguity for an AI agent.

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

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

Annotations declare readOnlyHint=true, so the description's read-only nature is already signaled. The description adds the temporal constraint (most recently modified) but does not detail pagination or return fields, which is acceptable for a simple 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?

Two sentences, front-loaded with action, no fluff. Perfectly concise for a simple tool.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description is complete: it states what it lists and when to use it, leaving no ambiguity.

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

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

Schema coverage is 100%, and the parameter 'limit' is fully described in the schema (min, max, default). The tool description adds no additional parameter context, so baseline score applies.

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

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

The description clearly states the tool lists recently modified vault files and gives a specific use case ('what did I just ingest / update'), distinguishing it from siblings like list_unprocessed and list_proposals.

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 says when to use it (to answer recent updates), providing clear context. It does not mention alternatives or when not to use, but the context is strong enough.

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

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

Annotations declare readOnlyHint=true, and the description adds context about detection using frontmatter rather than folder placement. It does not describe return format details beyond 'vault-relative path', which could be improved, but overall it 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?

The description is compact and front-loaded with the core purpose, followed by usage context and a practical pointer to a sibling tool. Every sentence adds value.

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

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

Given the tool's simplicity (one optional param, no output schema), the description is complete. It explains what is listed, how detection works, when to use it, and how the output can be used.

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

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

Schema coverage is 100%, so the parameter is described in the schema. The description adds no additional meaning about how limit affects results or the default value is already in 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 uses a specific verb (list) and resource (unprocessed vault files) and clearly states the detection mechanism (raw_file frontmatter). It distinguishes itself from sibling tools like list_proposals by explaining the output can be passed to propose_compile_from_raw.

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

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

Explicitly provides when-to-use scenarios: when the user asks 'what haven't I filed yet?' or before a compile pass. Also mentions that results are directly consumable by propose_compile_from_raw, guiding the agent to the appropriate next step.

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

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

Annotations already set readOnlyHint=true, and the description reinforces 'never modifies the vault.' It adds value by listing the exact types of issues diagnosed, providing behavioral context beyond annotations.

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

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

Two sentences, each serving a purpose: first describes output, second states read-only property and usage hints. No wasted words.

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

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

Given no parameters and no output schema, the description adequately describes the output types and usage scenarios. It is complete for a diagnostic 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?

There are zero parameters, so schema coverage is 100%. The description doesn't need to explain parameters; baseline is 4 for no-parameter 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 clearly states the tool diagnoses vault health and returns a structured report of specific issues: orphan source pages, tracker drift, malformed frontmatter, and large raw files. The verb 'diagnose' and resource 'vault health' are precise, and it distinguishes from siblings like margins_start and margins_reset_proposals.

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 says when to use: when user asks about broken items, checks vault, or before major operations. It doesn't explicitly state when not to use or name alternatives, but the context with siblings implies it's the diagnostic tool.

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

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

Annotations mark it as destructive, but description adds critical detail: never touches vault files, only proposed/. Also explains dry-run behavior with confirm parameter. No contradiction with annotations.

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

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

Three concise sentences, each essential. First sentence states action, second gives usage context, third explains confirmation behavior and safety.

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 single parameter and no output schema, description fully covers purpose, usage cues, parameter behavior, and safety scope. Agent can correctly decide and invoke.

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 covers both parameter semantics already, but description adds behavioral context for confirm: dry-run vs actual deletion. Reinforces and clarifies beyond 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 clearly states the tool clears pending proposals from a specific directory. It uses a specific verb 'Clear' and resource 'pending proposals from proposed/', distinguishing it from sibling tools like list_proposals or resolve_proposal.

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

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

Explicitly says when to use: after failed Claude sessions or when wanting a clean slate. Implicitly excludes use cases where proposals should be preserved. Does not explicitly list alternatives but context is clear.

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

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

Annotations declare readOnlyHint=true, which aligns with the tool's read-only nature. The description adds valuable behavioral context: explains response structure (mode, guidance, etc.) and expected follow-up actions. However, it doesn't mention idempotency or effects of re-calling, which would be useful.

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

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

The description is detailed and well-structured, breaking down modes with clear instructions. It is slightly verbose but every section adds necessary context. Front-loaded with the primary purpose.

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 response fields (mode, guidance, pendingProposals, etc.) adequately. It guides the agent on subsequent actions. However, it lacks details on repeated calls or fallback 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?

Input schema has zero parameters, so schema coverage is 100%. The description correctly provides no parameter info, as none exist. Baseline score of 4 is appropriate since there is nothing to add 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 explicitly states that this is a 'Conversation-start primer' and must be called once at the start of every vault-relevant conversation. It clearly identifies the tool's role and distinguishes it from sibling tools by being the mandatory first call.

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

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

Provides explicit when-to-use guidance ('Always call this once at the start of every vault-relevant conversation'). Also gives mode-specific instructions for 'pile', 'empty', and 'synthesis' modes, including how to handle each and what actions to prioritize.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) are supplemented by description details: the 'force' parameter can replace existing source pages, split mode stages multiple pages, and tags are auto-computed. This adds valuable behavioral context beyond the annotations.

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

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

The description is well-structured with clear sections for different page types and parameter guidance. While it is somewhat verbose (e.g., listing all file extensions), the length is justified by the tool's complexity and the need to disambiguate usage.

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 26 parameters and no output schema, the description covers file types, page types, parameter usage, prerequisites, and legacy mode comprehensively. It lacks details on return values, but the complexity is high and the description is fairly complete for an agent.

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

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

With 100% schema description coverage, the description further enriches parameter meanings, e.g., providing content-specific heading instructions for meetings, warning against certain tags, and clarifying legacy vs rich paths. This adds significant value beyond 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 clearly states the tool compiles supported source files into wiki source page proposals at 'proposed/<wiki path>', listing many file extensions. It distinguishes from sibling tools like propose_page by emphasizing knowledge artifacts vs topic recaps and providing specific page-type guidance.

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 usage guidance: call get_vault_context first, avoid certain tags, and follow different patterns for meetings, synthesis, and concept pages. It also explains the legacy vs rich path. However, it does not explicitly state when NOT to use this tool versus alternatives like propose_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?

Annotations already indicate non-readonly and non-destructive. The description adds that the edit is staged (not applied directly) and explains uniqueness constraint, providing valuable context beyond annotations.

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

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

Two sentences with no wasted words. Front-loaded purpose and mechanism, followed by essential usage hint. Highly efficient.

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 tool with 3 parameters and no output schema, the description covers the core behavior (staging, uniqueness, deletion). A minor gap is missing what the tool returns (e.g., success indication), but not 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?

With 100% schema coverage, baseline is 3. The description adds contextual guidance: explaining what to do if 'before' is not unique, and that empty 'after' deletes. This improves the agent's ability to use parameters correctly.

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 performs 'exact string replacement' on an 'existing page'. This verb+resource+machine specification distinguishes it from sibling tools like append_to or propose_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 provides clear guidance on when the 'before' text must be unique and advises to add context if needed. However, it does not explicitly contrast with alternatives like propose_page or append_to, which would help the agent decide between siblings.

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

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

The description fully discloses the tool's behavior: it creates stub pages with frontmatter, auto-builds a 'Mentioned in' block, skips existing pages, and explains the rejection mechanism. Annotations declare readOnlyHint=false and destructiveHint=false, consistent with creating non-destructive stubs. No contradictions.

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 well-structured: first sentence states core function, followed by details, then workflow context. Every sentence adds value without redundancy. It front-loads the key action and uses clear segmentation.

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 complexity of the tool and its role in a multi-tool workflow, the description covers essential context: the cold-start loop, skip behavior, and rejection handling. No output schema exists, but the description explains what the user gets. Slight gap: does not detail how to interact with stubs after creation (use resolve_proposal), but sibling tools cover that.

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

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

Schema coverage is 100% and both parameters are described. The description adds value by explaining the intent of 'bucket' (thematic grouping) and 'candidates' (forwarding scan payload for rich stubs) beyond the schema's technical descriptions. It also mentions the 200-item limit not present in 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 the tool stages stub entity pages for candidate slugs from scan_entity_candidates, with specific details about destination path, frontmatter, and auto-built blocks. It distinguishes itself from siblings like propose_page by focusing on entity stubs and being part of a defined cold-start loop.

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 when to use the tool: after scan_entity_candidates, and before resolve_proposal. It notes that it skips existing pages, implying not to use for edits. However, it does not explicitly compare to alternatives like propose_page or propose_edit, which slightly reduces clarity. The workflow context is strong.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) indicate mutation but not destruction. The description adds that the page is staged at 'proposed/<path>' and requires user acceptance via resolve_proposal. It mentions error condition. Lacks detail on response or idempotency.

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 concise sentences, front-loaded with purpose. No wasted words. Every sentence adds value: purpose, behavior, error/alternative.

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

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

Given 2 parameters and no output schema, the description covers core functionality, staging, error condition, and alternatives. Minor omission: no mention of return value or confirmation, but acceptable for this tool type.

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% with property descriptions. The description adds that body is 'full markdown (frontmatter optional)' and path is 'relative to vault root'. This is consistent with schema but adds minimal new meaning. 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 clearly states the tool proposes a new page, specifying the verb 'propose' and resource 'new page in vault'. It differentiates from siblings propose_edit and append_to by indicating it fails if page exists and directing to those 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?

Explicitly says to use for new pages and provides guidance on when not to use: 'Errors if a page already exists... use propose_edit or append_to in that case.' This gives clear context and 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?

Beyond annotations (non-destructive, non-read-only), explains that apply mode stages rewritten pages but respects the proposal-review contract (nothing lands until resolve_proposal). Notes that scope mode is faster and uses a shared slug index. No contradictions with annotations.

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

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

Front-loaded with main purpose, then modes, then additional details. Every sentence contributes information. Well-structured and efficient 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?

Describes return format for single-page (ranked list of {phrase, wikilink, occurrences}) and scope (aggregated suggestions). Covers apply mode and proposal workflow. Lacks error handling or edge cases, but sufficient given no output schema and clear parameter descriptions.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning: explains mutual exclusivity of path and scope, details apply behavior (stages one propose_page per scanned page), and caps for maxPages and maxSuggestions. Adds value beyond schema descriptors.

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?

Clearly states it scans vault pages for entity-shaped phrases and proposes wikilinks. Distinguishes two modes (single-page and scope) and mentions target personas (A3/B3). Specific verb+resource and differentiates from sibling tools like propose_page and propose_entity_stubs.

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?

Describes when to use: scanning for entity-shaped phrases to propose wikilinks. Implicitly distinguishes from other propose tools (e.g., propose_page for rewriting). Mentions scenarios (many files, few wikilinks) and that scope mode is faster than repeated calls. Could be explicit about when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint=true. The description adds that it extracts readable text from supported formats, which is consistent and provides context about the read operation. No contradictions.

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, no redundancy, front-loaded with the core purpose. Every word adds value.

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

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

The description is adequate for a simple read tool with one parameter and annotations. However, it lacks details on error handling, supported document formats, or behavior for unsupported files. With no output schema, some additional completeness would help.

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

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

Schema description coverage is 100% with a clear description for the single required parameter 'path'. The description adds example paths but no additional semantic meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states it reads a vault file by relative path and extracts text, specifying the verb 'read' and the resource 'vault file'. It distinguishes from siblings like 'search_vault' or 'list_recent' that handle different operations.

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 for reading a single file but does not explicitly state when to use it over alternatives or provide exclusions. No guidance on when not to use or prerequisites 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?

The description adds context beyond the readOnlyHint annotation by specifying the file path, return content (durable rules from user or record_preference), and its relation to propose tools. No contradiction.

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

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

Three efficient sentences, no wasted words. First sentence states action and resource, second explains return, third gives usage instruction.

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

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

Given zero parameters and no output schema, the description covers all necessary aspects: purpose, return content, and usage context. It ties into sibling tools appropriately.

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?

No parameters exist, so the description cannot add meaning beyond schema. Baseline score of 4 applies for 0-parameter 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 clearly states the tool reads a specific file (.margins/preferences.md) and returns durable rules. It distinguishes from siblings by mentioning record_preference and propose_* tools, making its unique role clear.

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 instructs to call this before any propose_* tool, providing a clear when-to-use directive. It lacks explicit when-not-to-use but the positive guidance is strong.

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

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

Annotations indicate a non-read-only, non-destructive operation, which aligns with the description 'Append' and 'durable'. The description adds context about the target (preferences file) and the nature of data (one-line rules), but doesn't elaborate on file creation or duplicate handling. Still, it sufficiently discloses behavior beyond annotations.

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

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

Three sentences front-loaded with purpose, then usage guidelines, then negative guidance. Every sentence adds essential information with 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?

Given the tool's simplicity (2 params, no output schema, no enums), the description fully covers purpose, when to use, and parameter semantics. No gaps remain 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 has 100% coverage with descriptions for both `observation` and `category`. The description reinforces the expected format with examples ('One-line rule...', 'Optional category tag... Examples: filing, naming...') and provides a concrete example for observation, clarifying usage beyond 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 clearly states the action: 'Append a durable user preference, convention, or correction to the vault's preferences file.' It also gives specific examples of when to use (user corrects a proposal on filing path, naming pattern, etc.), distinguishing it from one-off feedback.

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

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

Explicitly says 'Call this when the user corrects a proposal...' and provides a clear negative: 'Do NOT record one-off disagreements or transient feedback.' This helps the agent decide when to invoke this tool vs. alternative feedback mechanisms.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) indicate mutation without destruction. Description adds that 'The choice persists in ~/.margins/consent.json and applies to all future Margins sessions,' clarifying long-term effects. No contradiction.

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

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

Four sentences with no waste: states purpose, gives exclusive usage condition, maps user response to parameter, and explains persistence. Front-loaded and efficient.

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 mutation tool with no output schema, the description covers invocation trigger, parameter mapping, and side effects. Complete given the tool's complexity.

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

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

Single parameter 'enabled' with schema description 'True if the user opted in, false if they declined.' The description repeats this exactly, adding no new semantic information beyond the schema. Schema coverage is 100%, so 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 clearly states 'Record the user's choice on anonymous telemetry' with a specific verb and resource. It differentiates from siblings like record_preference by focusing on telemetry consent and providing exact conditions for invocation.

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

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

Explicitly states 'Call this exactly once, only when the margins_start response had telemetryConsentNeeded=true AND the user has answered the in-chat opt-in question.' Also maps user answer to parameter value ('Pass enabled=true if they said yes, enabled=false if they said no').

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

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

Annotations only indicate destructive (destructiveHint=true) but not read-only. The description adds atomicity of accept (overwriting), reject behavior (deletes proposal without touching vault), per-destination lock for concurrency, and dryRun preview. This far exceeds annotations.

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

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

Three sentences, front-loaded with purpose. Each sentence adds value: purpose, modes details, behavioral notes. No waste.

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

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

Given 5 parameters, 1 required, no output schema, the description fully explains tool behavior, modes, edge cases, and concurrency. DryRun output is mentioned. Complete for 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 coverage is 100%, baseline 3. Description adds significant meaning: explains mutually exclusive path/pattern, dryRun function, maxCount capping, and that path can include 'proposed/' prefix. Adds clarity beyond 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 clearly 'Accept or reject pending proposals' and distinguishes two modes (single and bulk). It uses specific verbs and resource, making it distinct from sibling tools like list_proposals or propose_*.

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

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

Explicitly explains when to use single mode (pass path) vs bulk mode (pass pattern), with exactly one required. Mentions dryRun for preview. While it doesn't explicitly say when not to use it, the context is clear given sibling tools. Slight lack of explicit 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?

Discloses read-only nature ('Read-only — never stages') beyond the annotation. Explains the ranking algorithm (file-spread × mention-count), layered filtering (global stoplist, domain pack, user rejections), and that existing slugs are excluded automatically. No contradiction with annotations.

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

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

Well-structured with clear paragraphs. Front-loads the main purpose and draws contrast with sibling. A bit long with multiple paragraphs, but each sentence earns its place. Could be slightly shorter but still effective.

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 7 parameters (all documented in schema) and no output schema, the description covers return values (candidates ranked with snippets and file list), companion tool, filtering layers, and best-use timing. Provides enough context for a correct invocation.

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

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

Schema coverage is 100%, so baseline 3. The description adds value by explaining the interaction of parameters (e.g., 'layered filtering', trade-offs like 'Lower to surface more; raise for high-confidence'). Gives context for minPhraseWords (single-word noise, acronym bypass). This adds 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 clearly states the tool's purpose: finding capitalized phrases that recur without a matching slug. It distinguishes itself from the sibling propose_wikilinks by explaining the inverse query nature. The verb 'find' and resource 'entities' are 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?

Explicitly states when to use: 'Best used right after a fresh import or split-mode compile.' Contrasts with propose_wikilinks, clarifying the decision boundary. Also mentions companion tool propose_entity_stubs for next steps.

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 `readOnlyHint` annotation already indicates this is a safe read operation, and the description does not contradict it. The description adds that the tool returns search results and pairs with fetch, but does not disclose other behavioral aspects (e.g., rate limits, sorting, or pagination). With annotations covering the safety profile, a 3 is appropriate as the description adds some but limited value.

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 concise: two sentences and a short phrase. It front-loads the tool's purpose ('ChatGPT Deep Research search') and provides essential return format details. Every sentence contributes value. Minor improvement could restructure to first state purpose then return and usage hint.

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

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

For a simple tool with one parameter and no output schema, the description adequately covers the return value and suggests a pairing with 'fetch'. However, it lacks information about result limits, error conditions, or how to interpret the 'id' as a vault path. Given the low complexity, a 3 reflects adequate but not thorough completeness.

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

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

Schema description coverage is 0%, so the description must compensate. However, the description only mentions the return format and does not explain the 'query' parameter's expected format, constraints, or examples. It adds no meaning beyond the schema, which simply defines 'query' as a string. This is a significant gap for a single-parameter tool.

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

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

The description clearly states it performs a 'ChatGPT Deep Research search' and returns a list with specific fields (id, title, url). It also explains that 'id is the vault path', making the resource clear. However, it does not differentiate from the sibling tool 'search_vault', which may cause 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 includes a usage hint: 'Pair with fetch', implying a workflow. However, it does not provide explicit guidance on when to use this tool versus alternatives like 'search_vault', nor does it state when not to use it. The context is implied but not comprehensive.

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

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

Annotations already declare readOnlyHint=true. Description adds that results include path and snippet, but lacks details on pagination, ordering, or edge cases. With annotations covering safety, this is minimally adequate.

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 efficiently conveys purpose and return value. No redundant information, perfectly 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?

No output schema exists; description mentions 'top hits with path and snippet' but lacks detail on structure (e.g., fields per hit). For a simple search tool this is acceptable but not comprehensive.

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% with clear descriptions for both parameters. The description adds no extra meaning beyond what the schema provides, 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?

Description clearly states the tool performs 'Full-text + filename search across the Margins vault' and specifies return of 'top hits with path and snippet.' This is a specific verb-resource pair, distinguishing it from generic siblings like 'search'.

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

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

No guidance on when to use this tool versus alternatives such as 'search' or 'scan_entity_candidates'. The description only states what it does without context for selection.

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