obsidian_backend_status

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

Annotations already establish readOnlyHint=true and idempotentHint=true, so the bar for description transparency is met by adding context beyond those. The description explains the port collision issue and the verify behavior ('Costs an extra listing per vault' is also in schema, but the description elaborates on the collision and cross-check intent). It also clarifies that response_format is unused ('JSON is always returned'), which is a behavioral trait not declared in annotations. No contradiction exists.

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 a one-line summary, a usage paragraph, a parameter list, and a return shape block. The most important usage guidance ('Call this first...') is front-loaded. Every sentence adds information—no fluff. It is appropriately verbose given the tool's complexity (multiple vaults, verify flag, detailed return). Length is justified.

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 is moderately complex due to optional vault targeting and a verification flag, yet the description covers all aspects: purpose, when to use, parameter behavior, side-effect cost (extra listing), and even the exact JSON response shape. The output schema exists but the description provides the full payload structure, ensuring an agent knows exactly what to expect. No missing context 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?

The description enriches the schema even though the schema already provides descriptions for vault and verify. It reinforces vault semantics ('omit to check all') and verify ('cross-check REST endpoint against vault path'), and critically reveals response_format is non-functional ('unused; JSON is always returned'), which the schema's enum does not imply. It also provides a full return JSON structure, giving concrete meaning to the output. This fully compensates for any perceived schema coverage gaps.

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 clear, specific verb-resource pair: 'Report, per vault, which backend is live and which capabilities are usable.' It immediately distinguishes this tool from siblings like obsidian_get_active_note or obsidian_list_vaults by focusing on backend status and capability probing. It also answers 'what' directly with a detailed return shape, making the tool's purpose unambiguous.

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

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

Explicitly states when to invoke: 'Call this first when a tool fails with a connectivity error, or when you need to know whether backlinks, the active note, and commands work right now.' It also provides a concrete trigger for the verify flag: 'Worth doing after adding a vault or changing ports.' This gives both a general when-to-use and a specific condition for an optional flag, fully covering usage guidance.

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