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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context beyond those: it reads from the 'local graph index' and does not recompute semantic classification. This gives the agent a clearer model of what side effects, if any, to expect.

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 with no wasted words. The core purpose is front-loaded, and each sentence earns its place by adding scope, usage guidance, or behavioral caveat.

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-only traversal tool with one well-documented parameter and strong annotations, the description is complete. It explains what is returned, how to invoke it conceptually, what it does not do, and how it relates to its sibling. No output schema exists, but the return concept is clearly stated.

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 the single path parameter already documented as 'Relative path from OBSIDIAN_ROOT'. The description does not add parameter-level detail, but the schema already carries the necessary semantics, so the 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 states the exact operation ('Traverse the hierarchy downward'), the resource ('one note'), and the result ('all direct and transitive child note paths'). It also differentiates itself from the sibling get_parents, so an agent can select it without 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?

It gives an explicit use case ('what does this topic/module contain?') and explicitly routes to get_parents for the opposite direction. It also notes that it does not recompute semantic classification, which helps avoid misuse.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true; the description repeats the read-only fact but also adds new context about result contents (parent entity name and link_type with allowed categories). This helps the agent anticipate the response shape even though there is no output schema. The description does not contradict 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 the primary behavior and then usage/alternative. Every sentence adds information; the only slight redundancy is the read-only statement, which is already in annotations, but it is short and does not bloat. Highly scannable.

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

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

For a single-parameter, read-only lookup with no output schema, the description covers the action, the return fields, and a usage trigger. It does not describe error cases or exact return shape beyond fields, but that is minor. One minor inconsistency: it references 'suggest_parents' while the sibling list contains 'suggest_metadata' – possibly a naming mismatch, but the tool itself is still callable 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 fully describes the only parameter 'path' as 'Relative path from OBSIDIAN_ROOT' with 100% coverage. The description adds no further parameter-specific detail, so it relies on the schema. Baseline 3 is appropriate.

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

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

States a specific verb ('Return'), resource ('parent links of one note from the graph index'), and enumerates the link_type values in the result. This clearly distinguishes it from sibling tools like get_children, which would return the opposite direction. The purpose is unambiguous.

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

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

Explicitly gives a use case ('understand where a note belongs before editing links') and names an alternative (suggest_parents) for the case where a note has no parents. It does not address all siblings, but the one likely-confusing alternative is covered. No exclusions beyond the suggested_difference, so a 4 is appropriate.

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

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

The annotations already signal idempotency and non-destructiveness, and the description confirms those traits with 'safe to run repeatedly.' It adds new behavioral details such as reporting missing parent links and the slower, provider-dependent embedding behavior when with_embeddings is true.

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

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

The description is three sentences, each earning its place: the core action, when to use it, and important behavioral caveats. The main purpose is front-loaded before secondary details.

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 strong annotations, the description covers invocation triggers, safety, side effects, and output hints like missing parent links. It does not describe the full return format, but that is a minor gap given the lack of an output schema.

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

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

The schema already documents with_embeddings well, so the description's added operational context — slower execution, provider requirement, and effect on retrieval/semantic classification — goes beyond the schema. It clarifies tradeoffs but not every environment-specific detail.

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 and resource: scanning the Markdown vault and rebuilding the local SQLite index of files, metadata, and graph links. It also explicitly disambiguates from siblings by stating it indexes data and is not a search tool.

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

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

It gives an explicit trigger, 'Use this after adding, moving, or reorganizing notes outside NOUZ,' and a clear exclusion: this tool is not for searching. This tells an agent when to invoke it and when to look elsewhere.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful behavior beyond annotations: it operates on the local index, returns lightweight records, and does not load full note bodies. It does not discuss error conditions or index staleness, but those are not essential for selection.

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?

Every sentence earns its place: purpose, return characteristics, when to use, a parameter tip, and sibling routing. Information is front-loaded with the core function stated first.

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

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

For a read-only filtered list with no required parameters and full schema coverage, the description covers scope, return shape, use cases, and alternatives. No critical calling information 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 covers 100% of parameters with useful descriptions, so the baseline applies. The description adds only a mild clarification that no_metadata targets Markdown files without YAML frontmatter, not enough to meaningfully surpass the schema.

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

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

States a specific verb and resource: 'List notes already known to the local index.' It explicitly lists returned record fields (path, type, level, sign) and distinguishes itself from graph-traversal siblings by directing agents to get_children or get_parents.

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

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

Gives explicit use cases ('inventory, filtering, and finding files to inspect next'), a specific filter recommendation (no_metadata=true for Markdown files without YAML), and names alternatives for graph traversal. An agent knows exactly when to choose this tool.

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

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

Goes well beyond the annotations by disclosing the SQLite index refresh side effect and explaining why it matters for later classification and parent suggestions. It also explicitly states 'It never changes the file,' clarifying the non-destructive nature despite readOnlyHint being false.

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?

Every sentence earns its place: the action and return value are front-loaded, the write_file use case is stated, and the side effect is disclosed without redundancy. The description is compact yet information-dense.

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

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

For a one-parameter read operation with no output schema, the description is complete: it lists all returned content fields, states the side effect, and confirms file immutability. An agent has enough information to invoke the tool correctly and interpret its 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 schema already provides a complete description of the single path parameter with an example, so schema coverage is 100%. The description adds context about Markdown notes and the local knowledge base, but no additional parameter-level semantics are needed.

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

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

States a specific verb and resource: 'Read one Markdown note from the local knowledge base.' It also enumerates the returned components (note body, YAML frontmatter, hierarchy metadata, parent links, tags, warnings), making the tool's function concrete and distinct from siblings like list_files or write_file.

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 this tool 'before write_file when you need to preserve existing content or inspect current metadata,' giving clear situational guidance. It does not cover alternatives like get_parents or suggest_metadata, but the primary routing to write_file is well defined.

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 states 'It is read-only and never edits YAML,' but the annotations declare readOnlyHint: false, indicating the operation may not be read-only. This is a direct annotation contradiction. Per the rubric, behavioral_transparency must be scored 1 when the description contradicts 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 structured with purpose first, then output details, then usage, then behavioral notes, then context semantics. Every sentence adds meaningful information and there is no filler. Despite being moderately long, the detail is mostly essential for correctly invoking the 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?

For a tool with no output schema, the description generously enumerates return fields, explains the read-only nature, notes embedding-dependent fields, and describes the optional context object's purpose. This gives an agent enough to decide and call the tool correctly, aside from the read-only contradiction flagged above.

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 both parameters. The description adds useful context about the context object ('test metadata overrides without changing the note') and mentions semantic fields requiring embeddings, but it does not substantially improve parameter-level understanding beyond the schema.

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

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

The description states a specific verb+resource: 'Analyze one note and propose knowledge-graph metadata for review.' It also enumerates the exact outputs (domain sign, material type, hierarchy level, tags, etc.), which goes well beyond a vague purpose statement. This clearly distinguishes it from siblings like write_file and update_metadata.

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: 'Use this before write_file when you want classification help, or to audit an existing note.' It also clarifies the tool is read-only and never edits YAML, which implicitly routes agents away from using it for mutations. This is strong 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?

Annotations already mark destructiveHint=true, and the description adds useful behavioral context: only YAML frontmatter is written, the Markdown body is preserved exactly, and specific fields are scoped. It does not clarify whether the metadata object replaces or merges with existing frontmatter, which is a minor gap given the destructive hint.

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

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

Two sentences contain all the essential information with no filler. The first sentence front-loads the core guarantee, and the second provides the usage context and allowed fields.

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

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

For a two-parameter mutation tool with no output schema, the description covers when to use it, what changes, and what is preserved. The main omission is the merge-vs-replace behavior of the metadata object, which could affect how an agent constructs the call.

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

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

Schema description coverage is 100% for both path and metadata, so the baseline is 3. The description adds value by enumerating the allowed metadata fields (type, level, sign, artifact_sign, tags, parents, parents_meta) and clarifying that metadata only applies to frontmatter, not the body.

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 states a specific verb ('Update'), a precise resource ('YAML frontmatter for an existing note'), and an explicit preservation guarantee ('preserve the Markdown body exactly'). It also names the exact metadata fields, making it clearly distinguishable from write_file and other 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?

Explicitly states when to use this tool: 'Use this for safe changes to type, level, sign, artifact_sign, tags, parents, and parents_meta when the note content must not be touched.' It does not explicitly name an alternative like write_file for body edits, but the 'only frontmatter / preserve body exactly' language strongly implies the boundary.

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 clearly discloses the destructive nature ('replaces the complete file'), explains the content_lock exception, and describes server-side side effects (cycle validation, parent syncing, index refresh). This adds significant behavioral context beyond the destructiveHint annotation.

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 filler: purpose first, then usage condition, then behavioral warnings and prerequites. Every sentence adds operational value.

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

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

For a complex write tool with nested objects and no output schema, the description covers the critical operational facts: destructive behavior, content_lock preservation, validation and sync side effects, and recommended sibling tools. The rich schema handles parameter details, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well. The description adds useful high-level context about content_lock behavior and destructive replacement, but it does not add per-parameter detail beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Create or replace one Markdown note with YAML metadata.' It also identifies a distinguishing capability (content_lock preserves body while updating metadata) and implicitly separates it from sibling tools like update_metadata and suggest_metadata.

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 the tool: 'when an agent has an explicit final content body and metadata to save.' It also names alternatives: 'Use read_file first for existing notes and suggest_metadata first when you want classification hints.' This gives clear selection guidance.

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