Since.dev

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses important traits: the cursor is durable, acknowledgements are monotonic, and retries are safe. It does not detail error handling or return behavior, but the core mutation semantics are transparent.

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?

Three short sentences, all informative and front-loaded: operation, parameter guidance, and retry semantics. No filler or redundancy.

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 one-parameter tool with no output schema, the description covers the action, precondition, parameter source, and safety semantics. A minor gap is that it does not hint at what response or confirmation the caller should expect after acknowledging.

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 input schema fully documents the single 'cursor' parameter, including its type, minimum, and origin. The description reinforces this by saying 'Pass that response's cursor,' but adds little meaning beyond the schema's existing description.

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 action ('Advance your durable change cursor') and identifies the exact resource and precondition ('after you have processed a complete what_changed_since response'). It clearly distinguishes itself from the sibling what_changed_since as the acknowledgement counterpart.

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 provides clear when-to-use guidance: only after fully processing a what_changed_since response. It also notes that retries are safe, which helps an agent decide to reuse it safely, though it does not explicitly enumerate exclusions or alternative tools.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It explicitly states that attaching does not replay earlier changes, that delivery starts now, and that older history is available through subject_history. This covers key side effects and limits, though it does not detail permissions or reversibility, which are less critical for a read-like attachment operation.

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 two sentences with zero fluff. The primary purpose is stated first, followed by a crucial behavioral caveat (no replay) and a pointer to an alternative for history. Every sentence earns its place and the structure is front-loaded.

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 tool with one parameter, no output schema, and no annotations, the description is complete. It explains the core effect, the non-replay behavior, and where to get older history, giving an agent everything needed to call it correctly without further research.

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 schema already describes the only parameter (setId) with 'From list_sets.' at 100% coverage. The description adds no additional meaning beyond what the schema provides, so the baseline of 3 is appropriate. The description does not elaborate on format or validation, but the schema is sufficient.

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 uses a specific verb 'attach' with a clear resource 'subscription set' and explains the outcome ('changes reach you'). It also differentiates from siblings by specifying how what_changed_since behavior changes and contrasts with subject_history for older data, making its 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?

The description clearly explains the effect of attaching and distinguishes it from replaying history, implying when to use it (when you want live changes from an existing set) versus accessing historical data via subject_history. It does not explicitly name alternatives like subscribe, but the behavioral contrast provides sufficient context for selection.

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

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

With no annotations, the description carries the behavioral burden. It discloses what is returned (coverage level, sources, cadence, canonical key) and adds an important reliability trait: 'Since.dev answers none honestly rather than guessing.' This goes beyond a generic check description, though it does not address potential side effects or auth.

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?

Two sentences with no fluff. The core purpose and usage timing are front-loaded, followed by a compact list of return values and a valuable honesty caveat.

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 description covers the return payload and the relationship to verify_facts, but it omits parameter semantics entirely and there is no output schema or annotations to compensate. An agent can infer parameter values only from enum names, which is insufficient for a 3-required-parameter tool.

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 description coverage is 0%, so the description must compensate for parameter meaning. It does not explain what subjectType, subject, or aspect refer to, nor how to choose values. The enum values are present in the schema, but their semantic significance is left to inference.

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 specific directive: 'Ask whether something can be watched at all, BEFORE building on it.' This clearly identifies the tool as a feasibility check and distinguishes it from siblings like subscribe or verify_facts by stating it returns the canonical key needed for verify_facts.

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 says to use it 'BEFORE building on it,' which is clear timing guidance. It also ties the output to verify_facts, implying the workflow. It does not explicitly state when not to use it or name alternative tools, but the context is strong.

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

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

With no annotations, the description carries the full behavioral burden. It transparently discloses read-only semantics, plan differences between free and paid, hosted AI allowances, customer credentials, and that World State verification calls still count against monthly plan limits. The document is helpfully explicit about side effects (none), though the mention of 'Since credit quotas' is awkward and unclear.

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 first sentence is a strong front-loaded summary, and the read-only note is useful. However, the middle sentence about free/paid allowances is grammatically tangled ('without Since credit quotas'), and the World State detail adds complexity without clear benefit for an agent deciding how to call the tool.

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 zero-parameter read-only tool with no output schema, the description provides enough context: what it reads, plan-level nuances, and explicit non-behaviors. It does not describe the output shape, but 'plan and current usage' gives a reasonable expectation of the return content.

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 tool has zero parameters and an empty schema, so there are no parameter semantics to clarify. Baseline 4 applies because the description does not need to compensate for schema 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 specific verb and resource: 'Read this workspace's plan and current usage.' It clearly distinguishes itself from check-running and acknowledgement tools by stating it is read-only and does not run checks or acknowledge changes.

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 gives clear context for when to use the tool: when you need plan/usage information, and explicitly states it does not run checks or acknowledge changes, ruling out those workflows. It does not name a specific alternative tool, but the exclusion is sufficient for routing an agent away from check-related siblings.

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

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

With no annotations, the description carries the burden and does well: it discloses that reads use no credits, that source/code/comment content should be treated as data rather than instructions, and that a draft or passing CI is not proof of production safety. It lacks auth/rate-limit details but provides meaningful behavioral context.

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 with the main purpose front-loaded, followed by parameter guidance and behavioral caveats. Each sentence adds operational value; it is slightly dense but not padded.

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 description provides strong coverage of safety, cost, and content scope for a simple read tool. However, with no output schema and no explanation of the required id parameter, the agent still lacks complete invocation details and return-shape hints.

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 description coverage is 0%, so the description must compensate. It explains includeCurrentPr well ('read the bounded current GitHub PR diff with freshness/completeness metadata'), but it never defines the required id parameter, leaving the agent to infer it is a repair identifier.

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 specific verb, 'Read,' and enumerates precise resources: captured external evidence, affected code, immutable patch versions, individual CI checks, and repair decisions. This clearly identifies the tool as a detail-inspection operation for a repair, distinguishing it from sibling tools like list_repairs.

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 gives clear operational context: set includeCurrentPr to retrieve the bounded GitHub PR diff, and reads consume no model or repair credits. It does not explicitly name alternatives or state when not to use this tool, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden. It discloses read-only semantics, lack of write permissions, and the fact that external changes are not acknowledged (potential staleness). This is meaningful beyond the schema.

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?

Two focused sentences, with the core action first and caveats immediately after. Every clause adds information without padding.

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 parameterless, read-only list tool with no output schema, the description provides sufficient context about authorization and freshness behavior. It does not detail the return shape, but that is not essential given the simple resource type.

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 tool has zero parameters and the schema is trivially fully covered. The description appropriately needs no additional parameter-level detail; the baseline for parameterless tools applies.

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 names a specific verb ('Read') and resource ('repositories explicitly shared with this agent by a workspace owner or admin'), making the tool's purpose unambiguous and distinguishing it from sibling tools that manage changes or sets.

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 second sentence explicitly states what the tool does not do – it grants no write permission and does not acknowledge external changes – which steers an agent away from using it for mutations or for syncing state. However, it does not name a specific alternative tool, so it stops short of explicit routing.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does state that the operation is a read ('Read') and clarifies the semantic boundary between this view and what_changed_since. However, it does not explain pagination behavior, default filtering, or whether results are limited to certain repositories, which are meaningful gaps for an unannotated tool.

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 two concise sentences with no filler. It front-loads the core purpose and then adds a single clarifying contrast with what_changed_since. Every word earns its place.

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 description provides enough to understand the tool's purpose and main distinction from a sibling, but it omits parameter behavior and expected return shape, and there is no output schema to compensate. For a list tool with three optional parameters and no annotations, the definition is adequate but not complete enough for confident invocation without further inference.

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 description coverage is 0%, so the description needed to compensate for the parameters, but it mentions none of them. Offset, review, and repositoryId are left entirely to the schema, whose enum values help somewhat but do not explain semantics like what 'attention' means or how repositoryId interacts with the shared-repository scope. The description adds no parameter-level meaning.

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 uses a specific verb ('Read') with a clear resource ('impact and repair status') and scopes it to 'repositories explicitly shared with this agent.' It also distinguishes itself from what_changed_since, making the tool's role immediately clear. The distinction from 'inspect_repair' is implicitly handled by the word 'list.'

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 gives clear context for when to use this tool: to view proposed fixes and checks rather than original external changes. It explicitly contrasts with what_changed_since, which is the main conceptual alternative. However, it does not mention inspect_repair or list_maintained_repositories as alternatives, so the guidance is not exhaustive.

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

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

With no annotations, the description carries the transparency burden and does a good job: it states exactly what the call returns (sets plus attachment status) and explains the behavioral consequence that subscription visibility depends on attachment. The 'List' verb reasonably implies a read-only operation, though it never states that explicitly.

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?

Three short sentences with no filler: the first states the tool's purpose, the second defines the domain term, and the third gives a useful next step. Every sentence earns its place and the core purpose is front-loaded.

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 zero-parameter, no-output-schema tool, the description is complete enough: it covers what is returned, the meaning of the returned data, and the downstream workflow. It doesn't provide an exact output shape, but an agent can invoke this correctly without it.

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 tool has zero parameters and 100% schema description coverage, so there are no parameter details left to document. The description's mention of unattached set ids is aimed at the next tool (attach_to_set), not unresolved parameter semantics here.

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 names a specific operation — listing the organization's subscription sets — and adds the valuable extra of showing whether the agent is attached to each set. It also defines what a 'set' is, eliminating ambiguity and distinguishing this tool from siblings like list_maintained_repositories.

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 gives actionable workflow guidance: list sets to find unattached ones, then use those ids with attach_to_set, noting that attachment is what makes subscriptions visible. It doesn't explicitly contrast list_sets with sibling listing tools, but the intended use case is clear.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does convey that the tool is observational ('observed change timeline') and implies a read-only operation by saying it 'Returns' data. However, it leaves ordering, time range, and limit semantics unspecified.

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?

Two short sentences with no filler. The rhetorical opener makes the purpose memorable, and the usage example earns its place by illustrating how the tool should inform decisions.

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 simple two-parameter read tool, this is adequate but has gaps: it never explains what limit controls, what time window is covered, or how 'totals' are computed. With no output schema, those details would materially help an agent call the tool 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?

Schema description coverage is 0%, and the description only weakly hints at subjectKey through the phrase 'for a subject.' The limit parameter is never mentioned at all, so the description does not compensate for the missing schema documentation.

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 what the tool does: it returns an observed change timeline and totals for a subject. The purpose is specific enough to be usable, though it does not explicitly differentiate itself from the sibling what_changed_since.

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 gives clear context for when to use the tool: to set your own re-check cadence based on volatility. It provides a concrete example of the reasoning, but it does not mention when not to use it or compare it with alternatives.

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

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

With no annotations, the description carries the behavioral burden and does it well: it discloses partial-failure semantics ('keep successful siblings when another is refused'), ordered per-watch results, and clarification instead of guessed subscriptions. It does not mention notification delivery, auth needs, or how to end a watch, but the core side effects are clear.

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?

Three sentences pack purpose, input-mode syntax, and result semantics with almost no wasted words. The second sentence is slightly dense and missing an 'or' before 'a natural-language statement', but it still communicates the two mutually exclusive paths efficiently.

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 tool's moderate complexity and the absence of an output schema, the description covers the essential call patterns and the response shape for both single and multiple watches. It also handles the ambiguous-subject case, making it sufficient for an agent to invoke the tool correctly without guessing.

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 67%, so the schema already documents subject, statement, threshold, and canonicalKey. The description adds value by prescribing the required combination ('subjectType + aspect + one of subject or canonicalKey') and by explaining the natural-language alternative's limits (up to ten watches). This compensates for the undocumented enum params.

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 opening sentence states a specific verb ('Register'), a concrete resource ('standing interests'), and the trigger ('notified when they change instead of polling'). This clearly distinguishes it from siblings like check_coverage or subject_history, none of which create notification watches.

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 gives clear context by positioning the tool as the alternative to polling, and it explains the two request modes (typed vs. natural-language statement). It does not name sibling alternatives or state explicit when-not-to-use conditions, but the use case is unambiguous enough.

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

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

With no annotations provided, the description fully discloses the tool's behavior: it returns per-fact statuses (valid, changed, unknown), and meaningfully clarifies the critical caveat that 'unknown' is not confirmation of unchanged. This is a behavioral trait that an agent must know to interpret results correctly, and the description delivers it clearly.

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?

Well-structured: the critical call-to-action is front-loaded in caps, followed by a concise definition of the return statuses, a crucial caveat about 'unknown', and an efficiency tip. Every sentence carries operational value; no filler.

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 tool's simplicity (single parameter, but with complex semantics around the 'unknown' status), the description is complete. It explains the return values (valid/changed/unknown), the interpretation pitfall, the batching limit, and points to how to obtain valid subject keys. The absence of an output schema is adequately compensated by the description's explanation of return value meanings.

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 partially compensates by explaining the 'facts' parameter's purpose (batch of assertions) and the expected outcome semantics. It does not detail individual fields like subjectKey or aspect, but the 'subjectKey' reference to check_coverage provides useful cross-tool guidance, and the overall parameter meaning is clear enough for the agent to construct a valid call.

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: batch-checking cached assertions against current observed state, with a specific verb ('verify') and resource (cached facts). It explicitly distinguishes itself from sibling tools like check_coverage and what_changed_since by focusing on fact verification rather than coverage or change detection.

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 gives explicit when-to-use guidance ('CALL THIS BEFORE ACTING ON ANYTHING YOU REMEMBER'), and explains the key semantic distinction of 'unknown' vs 'unchanged'. It also provides usage efficiency advice (batch up to 100 facts) and sets expectations about speed ('Cheap and fast').

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

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

With no annotations, the description carries the full behavioral burden and mostly succeeds. It discloses that results are ordered, deduplicated, structured as diffs (from → to), include change and context blocks, and that low-relevance changes are not filtered. It also describes the lost-response retry behavior. It does not explicitly state read-only/side-effect status or auth/rate-limit expectations, but the acknowledgment-separate flow strongly implies no mutation occurs.

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?

Every sentence earns its place: it front-loads the critical directive, explains when to call, what the output looks like, what filtering behavior exists, and what to do next. There is no filler or repetition.

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 no output schema and no annotations, the description provides enough for an agent to call and consume the tool correctly: response shape, ordering/dedup behavior, next-step acknowledgment, and retry behavior on lost responses. Both parameters are fully documented in the schema, and no required parameters exist.

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 description coverage is 100%, and the schema already documents `limit` (default/max) and `since` (cursor position semantics). The description reinforces the acknowledgment/cursor relationship but does not add new parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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 operation: it returns every change to watched things since the last acknowledged cursor, ordered and deduplicated. It also distinguishes itself from the follow-up sibling `acknowledge_changes` by clarifying that this call does not acknowledge changes, so an agent cannot confuse the two.

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?

Usage timing is explicit: 'THE FIRST CALL WHEN RESUMING' and 'Call this before continuing any plan you formed in an earlier run.' It also tells the agent to call `acknowledge_changes` afterward. However, it does not explicitly name an alternative tool for filtered or per-subject queries, so there is clear context but no explicit when-not-to-use guidance.

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