suggest_frontmatter

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

The description discloses the return structure ({existing, suggestions, conflicts}), the sorting of suggestions by confidence, and the meaning of conflicts. While no annotations are provided, the description provides sufficient behavioral insight for a suggestion tool without claiming any destructive actions.

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, using only a few sentences to convey the tool's purpose, modes, return values, and sorting. It is front-loaded with the primary function and structured logically.

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 absence of annotations and output schema, the description provides a good understanding of input modes and output structure. It could mention potential error states or the implicit read-only nature, but it is largely complete for an agent to use 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?

With 0% schema description coverage, the description compensates by explaining that 'path' is for an existing note, while 'content', 'folder_hint', and 'title' are for a draft. It clarifies that at least one of path/content is required. The 'vault' parameter is not explained, but it is a common container parameter.

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: suggesting frontmatter fields for a note, using specific heuristics. It distinguishes itself from sibling tools like 'query_frontmatter' and 'update_frontmatter' by focusing on suggestion rather than querying or updating.

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 outlines two input modes (existing note vs. draft) and the required parameters for each. It states that at least one of path or content is required, providing clear usage context. However, it does not mention when to avoid this tool or suggest alternatives among siblings.

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