get_archive_metadata

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

With no annotations, the description carries the full burden and does so well: it discloses the path-dependent behaviour (live path applies a 30-day default plus a 'note' field; the SQLite-cached path actually taken returns an empty result with no note when dates are omitted) and frames it as deliberate rather than a bug. It omits error conditions, permissions, and result shape, but the gotcha disclosure is genuinely valuable.

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 core content is front-loaded, but the body is padded with a versioned changelog entry and internal call-path references (mcp_map.get_archive_metadata(), metadata_map.py, mcp_sql.get_metadata_range(), _route_query()) that belong in code comments, not a tool docstring. The actual invocation-relevant rule is buried inside that machinery discussion.

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 3-parameter read tool with no output schema, it covers parameter semantics, defaults, and a non-obvious empty-result edge case, which is most of what an agent needs. Residual gaps are the unexplained non-stats kind return values, which are not inferable from the schema or 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 coverage is 0%, so the description is the only source of parameter meaning and it delivers: it lists every legal `kind` value (none present in the schema) and fully specifies date_from/date_to as inclusive ISO YYYY-MM-DD, including per-kind applicability and default behaviour. It does not explain what the less obvious kinds (e.g. 'capability_config', 'token_log') actually return.

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 resource ('archive-state metadata') and enumerates the artefact kinds selectable via `kind`, with an explicit gloss on the most common one ('stats' = coverage/quality overview for size/health questions). It does not differentiate itself from siblings like query_raw or query_health, which is the main gap.

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 real usage guidance for one kind ('use this for "how big/healthy is my archive" questions') and states which kinds date_from/date_to applies to versus which four ignore it. However it never says when to prefer this tool over the sibling query_* tools, so routing guidance is only partial.

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