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

With no annotations, the description carries the full burden. It does disclose one important behavior: it appends rather than overwrites. However, it does not explain what happens when the file does not exist, what a null date means, or how the optional heading affects the appended item.

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 sentence with no filler. It front-loads the action and resource, and the non-destructive guarantee is useful and concise.

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 annotations and no parameter documentation, so the description needed to compensate. It leaves meaningful gaps: how the optional date and heading parameters behave, whether the daily note file is auto-created, and what the output schema represents. It is enough for a very basic call but not for confident correct use of all parameters.

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 needed to explain the role of 'content', 'date', and 'heading', but it only refers generically to 'an item'. The parameter names are somewhat self-explanatory, but the default/null behavior and the meaning of 'heading' are left entirely to 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 states a specific verb ('Append'), a specific resource ('Daily/YYYY-MM-DD.md'), and a clear non-destructive behavior ('without overwriting existing text'). This makes the tool's purpose immediately distinguishable from sibling read/lookup 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 implies this is the tool to use for adding to a dated daily note, but it gives no explicit guidance about when to choose it over alternatives or when not to use it. No sibling-specific differentiation or exclusion criteria are provided.

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 disclosing behavior. It reveals that the tool appends a timestamped section, conditionally records Git branch/SHA/dirty state, and never persists secrets or full diffs. It doesn't cover file-creation edge cases or failure behavior, but the core side effects are 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?

Three short sentences with no filler: purpose, mechanics, and safety constraint. The most important behavioral facts are front-loaded, and 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?

For a 7-parameter tool with no annotations and an existing output schema, the description covers purpose, key behavior, Git-related handling, and a safety boundary. The main gap is that it never explains when to use this tool versus the similar sibling append_daily_note, or versus record_decision.

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 clarify repository_path behavior and constrains 'changes' via the no-full-diffs rule, but it leaves project, summary, decisions, next_steps, and open_questions to be inferred from their 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 verb ('capture') and resource ('that day's session note'), and adds concrete behavioral details like timestamped appending and Git metadata. It doesn't explicitly distinguish itself from the sibling 'append_daily_note', whose name suggests a similar append-to-note operation.

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 context: use this to capture meaningful work performed during a coding session. It also implicitly discourages submitting secrets or full diffs. However, it does not state when-not-to-use or name alternatives like append_daily_note or record_decision.

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 full transparency burden, and it discloses key behaviors: it reads three named sources, returns empty sections for new projects, and never returns the entire vault. The guarantee about new projects prevents the agent from misinterpreting missing output as an error. The only gap is what happens when the project argument is invalid or the files are absent, but that is not critical.

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

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

Four short sentences present the outcome first, then sources, then edge-case behavior, then a boundary—all relevant and no filler. The line 'Never returns the entire vault' is especially compact and valuable.

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 explains the read behavior and edge case effectively, and an output schema exists so return-structure details are not needed here. However, with three parameters and no schema descriptions, the complete absence of parameter documentation leaves the tool partially underspecified. An agent could call it correctly via defaults, but it would have to guess at the influence of recent_sessions and recent_decisions.

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 explain the three parameters. It mentions 'Project State.md' and 'newest session and decision notes,' which loosely maps to project and the count parameters, but never states that recent_sessions and recent_decisions control how many notes are read, nor what format project takes. The parameter names are partially self-explanatory, but the description adds no meaningful parameter 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 opens with 'Retrieve concise durable memory before substantial work,' a specific verb/object pair with a clear trigger condition. It goes on to name the exact sources (Project State.md, newest session and decision notes) and states what it will not do ('Never returns the entire vault'), which separates it from read_note and search_memory.

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 'before substantial work' supplies an explicit when-to-use signal, positioning the tool as the starting point for context gathering. It does not explicitly name alternatives or exclusions, but the boundary 'Never returns the entire vault' gives agents a cue that this is not a vault-wide read. A stronger definition would name search_memory or read_note as alternatives for broader or note-specific reads.

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 adds meaningful behavior by stating that paths must stay inside OBSIDIAN_VAULT_PATH and that absolute paths or ../ traversal are rejected. This is more transparent than typical read-tool descriptions, though it does not disclose error behavior or file-not-found handling.

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 short, purposeful segments: the operation sentence is front-loaded, and the path constraint follows in a compact separate statement. Every sentence earns its place; 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?

For a one-parameter read tool, the description plus the existing output schema is largely complete: it states what the tool does and the key input constraint. It leaves minor gaps around expected path format and error handling, but an agent can safely select and invoke the tool based on the provided information.

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 'path' as a required string with no description, so the description is the sole source of parameter meaning. It adds essential semantics: the path must stay within OBSIDIAN_VAULT_PATH, and absolute or traversal paths are rejected. It could further specify whether a .md extension or relative-to-root syntax is required, but it covers the critical safety 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 opens with a specific verb and resource: 'Read one Markdown note inside the configured Obsidian vault.' This clearly identifies the operation and the object, and it distinguishes the tool from the sibling tools, which are write/search/update 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 verb 'read' implies this is the tool to use for retrieving a note's content, but the description never states when to prefer it over siblings like search_memory or append_daily_note. There is no explicit when-not-to-use or alternative guidance, so usage is only implied.

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

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

With no annotations, the description carries the behavioral burden. It clearly discloses that the tool creates a dated markdown file and that existing files are not overwritten but instead get a numeric suffix. This is meaningful side-effect information, even though permissions and exact file location are not mentioned.

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 short, front-loaded sentences. The first states the purpose and the second explains the exact file behavior and collision handling. 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 tool with eight parameters, four required, no annotations, and no parameter descriptions, the definition is too minimal. It covers file creation and overwrite avoidance but leaves unclear how the parameters map to the generated document, when to choose this over sibling tools, and what a valid call should look like.

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 needed to explain the eight parameters, but it only implies a slug derived from the title. It does not clarify project, context, decision, rationale, alternatives, consequences, or related_files. The parameter names are self-explanatory enough to avoid a 1, but the description fails to compensate for the missing 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 opens with a specific verb and resource: 'Store a durable architecture or engineering decision.' It then specifies the concrete artifact, YYYY-MM-DD-<decision-slug>.md, which makes the tool clearly distinct from siblings like capture_work_session, append_daily_note, and search_memory.

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 record_decision versus the listed alternative tools. The phrase 'durable architecture or engineering decision' implies a use case, but the description does not state exclusions, prerequisites, or how this differs from session capture or daily note appending.

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. 'Local text matching' is a genuine behavioral trait, indicating that search is text-based rather than semantic or remote, but the description does not mention result ordering, read-only behavior, or limitations.

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, front-loaded sentence with no filler. It communicates the core action, scope, and mechanism efficiently in nine words.

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

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

For a straightforward search tool, the core purpose and mechanism are present, and an output schema exists to cover return values. However, the lack of usage guidance and parameter semantics leaves the definition minimally viable rather than complete, especially given the absence of annotations.

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 needed to explain the roles of query, limit, and project. It does not; the tool purpose only loosely implies the query parameter, while limit and project remain entirely undocumented in the description.

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

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

The description clearly states the action ('Search') and the resource scope ('project state, sessions, and decisions'), which is specific enough to distinguish it from generic memory tools. It also adds the mechanism 'local text matching' for extra clarity, though it does not explicitly compare against sibling tools like read_note or get_project_context.

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

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

There is no guidance about when to use this tool versus its siblings, such as get_project_context or read_note, and no exclusions or alternative recommendations. The intended use is only implied by the name and description, leaving the agent to infer the appropriate 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 behavioral disclosure burden and it does real work: 'Replace' signals a destructive overwrite of the project state, and 'Omit empty sections' is a concrete behavioral rule for formatting the state. It does not cover permissions or additional side effects, but the key destructive trait is communicated.

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

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

Two short sentences with the core action first and the clarifying constraints second. There is no fluff and no repetition of information already present in the input schema.

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 ten-parameter tool with no schema descriptions and no annotations; the output schema covers only return shape, not usage. The description does not explain how to populate each state section, how to reference the project, or when to choose this over read-only siblings, so the agent is left with significant gaps.

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

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

Schema description coverage is 0%, so the description needed to compensate, but it adds only a generic 'Omit empty sections' rule and no field-level guidance. The project identifier and the intended content of notes/blocked/completed/architecture/etc. are left entirely to inference from parameter titles.

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

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

The description opens with a concrete verb ('Replace') and a concrete resource ('Project State.md'), making the tool's action and target unambiguous. Adding 'current state, not a session log' separates it from session-oriented siblings such as capture_work_session.

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 frames the tool as maintaining current durable state and explicitly rules out session logging, which is the closest alternative behavior among the sibling tools. It does not list every alternative, but the when-to-use signal is clear.

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