Get library activity

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real behavior: a two-phase summary-then-detail model, revision binding, and the rule that stale detail revisions require a fresh summary. It omits things like result size or cost characteristics, but the stateful workflow disclosure is the important part and it is present.

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 sentences, front-loaded with purpose, then routing, then workflow. Almost every clause earns its place, though 'Returns deterministic metrics and evidence' is somewhat vague filler and the stale-revision sentence partly restates the expected_revision schema description.

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, nested-interval tool with no output schema, the description supplies the summary/detail workflow and revision semantics that would otherwise be missing. It does not describe what the summary payload contains beyond 'deterministic metrics and evidence', so an agent still lacks a concrete picture of the return shape.

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%, so the baseline is 3 and the schema already documents detail, offset, limit, metric_id, expected_revision and the interval object. The description earns above baseline by explaining the dependency chain the schema only hints at: report_revision is obtained from the summary and then reused for detail pages, which is the key cross-parameter relationship.

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 verb ('Report') plus the exact resource set ('saved-library capture activity, shelf churn and standing-source observations') bounded by a time interval. It explicitly distinguishes itself from get_library_brief_input and source_status, so an agent can separate it from the closest siblings without opening any schema.

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?

Names two alternatives with the exact condition that selects each ('daily writing packet' -> get_library_brief_input, 'one source's observations' -> source_status). It also gives the positive usage path: start with the summary, then reuse report_revision for detail pages, and what to do on a revision mismatch.

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