mureo_history_query

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

No annotations exist, so the description carries the full burden, and it delivers: it discloses that journal holds even denied and failed calls which action_log 'correctly never holds', that daily merges archived and in-document days, and that limit applies per source with each section reporting truncation. This goes well beyond the name and schema. It stops short of covering auth needs or an explicit read-only declaration, but for a local read tool these are minor.

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?

Front-loaded with purpose ('Read the PAST') and concrete examples before any mechanics. It is dense — a long block with parentheticals — but for a 15-parameter, four-source tool nearly every clause carries information; there is no filler. Slightly more paragraphing or bullet structure would push it to 5.

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 read tool with no annotations and no output schema, the description covers the essentials: what the four sources hold, how filters scope per source, per-source limits and truncation reporting, and the division of labor with mureo_state_get. The schema's parameter descriptions fill in the rest (window defaulting, the 20000-line journal scan, cross-parameter requirements). A response-shape overview beyond truncation flags would improve it, but nothing an agent needs to invoke it correctly 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 coverage is 100% with unusually rich per-parameter descriptions, so the baseline is 3. The description adds value the schema lacks by defining what each source contains — curated action_log entries with their full-log index, the journal as every call with outcome, a merged daily series, report versions — which gives meaning to the source-related filters. The per-source limit and truncation semantics are already echoed in the schema's limit description, so the marginal addition is mostly source semantics.

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 action — 'Read the PAST' — and a clear scope: anything STATE.json no longer holds. Concrete examples ('what was changed on a campaign in July', 'daily spend from before the 35-day retention window') anchor the intent, and it distinguishes itself from mureo_state_get by naming it directly. The four sources are enumerated, so the agent knows the resource surface.

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 names the alternative and the decision rule: 'Use mureo_state_get for the CURRENT state of the document; use this for what it no longer holds.' Also frames when the tool applies ('any question that reaches beyond what STATE.json currently holds') and notes cross-source constraints that gate usage (daily requires platform, reports requires kind).

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