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

With no annotations, the description carries the full burden and does well: it discloses case/accent-insensitive matching, the first-name shortcut, and — critically — that ambiguous multi-matches yield {contact: null} rather than an error. Missing is any note on auth/prerequisites or the phone-number format returned, which keeps it off a 5.

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, front-loaded with the action, then matching rules, then return contract. Every clause carries information; nothing is restated from the schema or title.

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?

There is no output schema, and the description compensates by sketching the return object and the null case, which is what an agent needs to branch on the result. Only the number's format and any auth assumptions are left implicit for a mutation-free single-parameter lookup.

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, but the description adds real semantics the schema lacks: the value may be a name or alias, case and accents are ignored, and a unique first-name match is accepted. That directly informs what to pass.

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 and resource ("Find a phone number by name") plus the consumer (RoxyBot calls and messages). No sibling tool does contact resolution, so the agent can route here unambiguously; the matching rules and return shape further pin down scope.

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?

Gives clear context for use (resolving a contact for RoxyBot calls/messages) and, implicitly, that this is the lookup path when only a name is known. It does not name exclusions or alternatives, but no sibling provides overlapping functionality, so little is left ambiguous.

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 must carry the behavioral burden; 'aggregate counts' implies a read-only, side-effect-free operation, which is helpful. It does not state that explicitly, nor does it hint at cost or result-size characteristics beyond what the schema's limit default conveys.

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: the capability and its grouping axes first, then usage examples and the optional scope. Every clause earns its place with no restatement of the title.

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?

All four parameters are optional and fully described in the schema, and 'aggregate counts grouped by' implicitly conveys the row-and-count return shape. Since there is no output schema, a brief statement of the result form would have closed the remaining gap.

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 range, group_by, limit, and source_app are already documented in the schema, giving a baseline of 3. The description adds only the framing that source_app is an optional scoping filter; no extra syntax or defaulting nuance beyond the schema.

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 (aggregate counts) over a specific resource (clips and transcriptions) and enumerates the grouping dimensions, which lets an agent distinguish it from list-style siblings like eve_recent. It stops short of differentiating from eve_app_stats, which plausibly overlaps on per-app counts.

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?

Two concrete example questions ('what apps did I work in today', 'when am I most active this week') map directly onto the group_by choices, and 'Optionally scope to one app' signals the source_app use case. No explicit when-not or named alternative among the many siblings is given.

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 exist, so the description carries the full burden; it does disclose the exact return metrics, which is genuinely useful given there is no output schema. It says nothing about behavior for an unknown bundle id (empty stats vs error), whether it is purely read-only, or performance over long time windows.

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, zero filler: the metric list comes first and the illustrative use case second. Everything is front-loaded and each phrase maps to a dimension the agent cares about (content and usage).

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 with no output schema, enumerating the returned metrics plus a usage example is close to sufficient. The remaining gap is edge-case behavior (missing/unknown bundle) which the description does not address.

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% and both parameters (bundle, since) are fully documented with examples and the default window. The description reinforces that stats are scoped to a single app and a time window, but adds no syntax or format detail beyond the schema — baseline 3 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?

States a specific verb+resource ('statistics for a single source app') and enumerates the metrics returned (total clips, content-type breakdown, first/last seen, favorites, copies). It does not explicitly contrast with siblings such as eve_categories or eve_activity, so scope-vs-alternative is left partly implicit.

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 quoted example ('how much did I copy from Safari this month') gives a concrete scenario that maps both parameters to a real question. There are no exclusions or explicit alternatives, so the agent must infer when a different sibling (e.g. eve_activity) is the better call.

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, and it does disclose the return payload shape (names, entry counts, purpose text) and the read-only listing nature. It omits ordering, whether categories with zero entries appear, and whether the list is complete or truncated, which are minor but real gaps for a no-parameter enumerator.

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, zero filler. The returned-content summary comes first and the downstream-usage pointer second, which is the correct front-loading order.

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 list tool with no annotations and no output schema, the description supplies enough: what comes back and how to use it. It stops short of describing ordering or empty-state behavior, which an agent might want, but nothing critical is missing 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 tool takes zero parameters, so the baseline is 4; there is nothing about inputs the description needs to explain. The description instead spends its words on output semantics, which is the right allocation.

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 (all user-defined categories) and enumerates exactly what each returned item contains (entry counts, purpose descriptions). It also clarifies the domain concept — categories group mixed history entry types (clips, transcriptions, recordings, live talks) into projects — so an agent can distinguish this from entry-level siblings like eve_get or eve_recent.

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 explicitly routes the agent forward ('Use the names with eve_recent/eve_search category filters or eve_categorize'), which is the primary reason to call this tool. However, it offers no exclusion criteria — e.g. it never says not to use this when you only need a single category or when eve_activity would suffice.

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 the full burden; it does add one genuinely behavioral fact — that the running app refreshes automatically after the call — plus the implicit create-if-new on add. However it never says whether add and remove can be combined in one call, whether removal is destructive/reversible, or what permissions are needed, which are the key unknowns for a mutation 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?

Three short sentences, front-loaded with the add/remove duality and the write-path framing before the audience line. The phrase 'from the agent side' is slightly vague, but no sentence is wasted.

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?

With three fully documented parameters, no nested objects, and no output schema, the essentials are covered. It is still thin on the interaction between the two optional mutation parameters and on failure semantics (removing a category that isn't applied), which matter more here because no annotations declare the safety profile.

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 schema already documents the <type>:<id> format and valid types, giving a baseline of 3. The description earns above baseline by adding provenance — where to obtain valid targets (eve_recent/eve_search/eve_get_selection) — which the schema does not say.

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 pair (add/remove), the resource (categories on history entries), and explicitly positions itself as 'the write path' versus the read siblings eve_recent/eve_search/eve_get_selection. An agent can distinguish it from eve_categories or eve_search 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?

Gives clear context for invocation: it is the agent-side write path for organizing entries into projects, and targets come from eve_recent/eve_search/eve_get_selection results. It stops short of naming exclusions or pointing to eve_categories for discovering existing category names, so it is clear but not fully 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 and does well: it discloses that the master video is never modified, that output lands in a clips/ folder beside it, that a new row appears in the Aufnahmen tab, and that a remapped transcript is generated. It omits any indication of processing time/cost for transcoding or permission requirements, which matters for a media-writing 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?

Front-loaded with the operation, followed by a compact workflow and side-effects sentence; every sentence carries information an agent needs. The final sentence is densely packed with three facts, mildly reducing scanability, but nothing is 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?

For a mutation tool with no annotations and no output schema, the description covers the important ground: preconditions, non-destructiveness, and where the artifact lands. The remaining gap is what the tool returns (clip id, path, status object), which the agent must infer since no output schema exists.

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 baseline is 3; the description adds real meaning by explaining that multiple ranges are stitched into ONE clip in order and that positions are millisecond word positions from the transcript, clarifying what 'segments' actually means operationally. It does not touch title/format/quality, but the schema already covers those with defaults and bitrate details.

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 and resource ('Cut a shareable mini-clip out of a screen recording') with a precision qualifier ('second-exact'). No sibling tool in the list exports clips, so the distinction is implicit but unambiguous from the operation described.

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?

Gives an explicit three-step workflow: call eve_get with type 'recording' to read transcript_segments, pick cut ranges from millisecond word positions, then call this tool. That is a concrete prerequisite chain naming the sibling to use first, leaving nothing to inference about ordering.

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 well: it explains that content is full and untruncated, describes per-type return content, and explains how to resolve screenshot blob hashes. It does not explicitly mention permissions or error behavior, but 'fetch' adequately signals a read 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 dense but well-structured: it front-loads the core purpose, then organizes details by entity type. Every sentence carries useful selection or interpretation information for a polymorphic retrieval 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?

Without an output schema or annotations, the description compensates by explaining return content for each entity type and how to resolve blob hashes. An agent should be able to call this correctly and interpret the results from the description plus schema.

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 schema already documents all three parameters. The description adds value beyond the schema by clarifying type-specific behavior, especially what recording transcript_segments provide and that include_context applies to clips.

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 verb and resource: fetch one clip, recording, screenshot, or transcription by id with full content. It clearly distinguishes this full-detail retrieval from search/recent by saying to use it after those tools return an id.

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 explicitly routes the agent: use after eve_search/eve_recent returns an id. It also names the downstream relationship to eve_export_clip for recordings, making the workflow position 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?

No annotations are provided, so the description carries the burden, and it does disclose the return shape (each selected item with a snippet/title), a freshness field with its exact semantics, and empty-result behavior. It does not state side effects or access requirements, but 'get' plus a read-shaped return makes read-only intent 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, front-loaded with what the tool returns, then the staleness caveat, then the empty case. Every sentence contributes a distinct operational fact with no 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?

For a zero-parameter, read-only lookup with no output schema, the description covers what is returned, the key freshness signal, and the empty case — everything an agent needs to call and interpret it. No essential gap remains.

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 takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly spends no words on parameter explanation.

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 resource and scope: the entries currently selected by the user in eve's history board, described as the live focus context. This is clearly distinguishable from sibling retrieval tools like eve_recent, eve_search, or eve_get, which fetch raw history rather than current selection state.

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?

Gives a concrete interpretive rule — check updated_at, and treat an old value as possibly stale and worth confirming — plus the meaning of an empty items list. It does not, however, name when to prefer a sibling tool such as eve_recent or eve_search instead, so the alternatives dimension is absent.

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, and it does disclose that this is a mutating operation with three distinct side effects: copying the file, writing a history row, and popping a UI element. It does not cover overwrite/idempotency behavior or what happens if the persona does not exist, which is the remaining gap for a write 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?

Three short sentences, front-loaded with the action and its effects before the usage note and the input constraint. The path requirement is slightly redundant with the schema description, a minor bit of waste.

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 no-annotation, no-output-schema mutation tool with 4 params (3 required), the description covers effects, prerequisite, and input format well. The gaps are edge-case behavior (duplicate file, unknown persona) and any hint of what the call returns or throws.

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%, so the schema already explains path, title, persona, and transcript_file; the description's only parameter content ('absolute path to a local mp4/mov') restates the path description. It adds no semantics for persona or title beyond what the schema provides — baseline 3.

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 and resource — 'Deliver a finished persona answer video into eve' — and then enumerates the concrete effects (file copy, history row, persona bubble). No sibling tool on the list performs ingestion, so an agent can place it uniquely without inspecting the 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?

'Use after generating a talking-head video for the user' gives a clear triggering condition, and 'Requires an absolute path to a local mp4/mov file' states the precondition. It stops short of naming when-not to use it or what to do if the file is already ingested, so it falls 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 and does: it discloses the side effect (the app speaks and stores the reply), the ~50s blocking timeout, and the complete set of terminal/continuation statuses. Nothing about the blocking, mutating nature of the call is left to guess.

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-loads what the tool is and the core loop before the rules, and every clause carries information. It is a single dense paragraph, though, mixing mechanics and edge-case rules that would read faster as separated lines.

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?

There is no output schema, and the description compensates fully by enumerating the return statuses and what each implies. For a blocking, stateful conversational tool with three optional params, an agent has everything needed to drive the loop 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 coverage is 100%, so the baseline is 3; the description adds operational meaning with `reply` as the answer to the previous utterance and the rule to pass `talk_id` verbatim or omit it and send `agent_label` once. It stops short of adding format or length guidance for `agent_label` beyond the schema example.

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 and resource: a voice-conversation turn loop that speaks the agent's reply and returns the user's next utterance. No sibling tool touches voice/live conversation, and the description makes the loop role unmistakable.

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?

Gives explicit branch-by-branch rules keyed to the returned status: answer and re-call on `utterance`, re-call immediately with no reply on `silence`, stop on `paused`/`ended`/`busy`. It also states the `talk_id` vs `agent_label` condition for start-instruction versus session-initiated starts.

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 real work: it declares newest-first default ordering, the sort options per entity type, and keyset pagination via meta.next_cursor. It stops short of stating read-only safety, result caps, or what a cursor mismatch does, which the schema only partly covers.

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, front-loaded with the verb and ordering, followed by quotable intent examples and a compact enumeration of supported features. No filler and no 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 an 18-parameter list tool with no output schema and no annotations, the description covers purpose, filters, sorting and pagination, and helpfully names meta.next_cursor. It omits the deleted-flag-to-eve_restore linkage and clipping defaults, but the schema fills those gaps.

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% and five of the parameters are enums, so the schema already documents every parameter. The description only restates the sort mode mapping and the meta.next_cursor format, adding little beyond the structured fields; baseline 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?

States a specific verb and resource ("List the most recent clips or transcriptions") with an explicit ordering scope ("newest first"), which is enough to distinguish a recency browse from a query search. It never names the sibling eve_search, so the differentiation from search is implied rather than stated.

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?

Concrete user-intent examples ("what did I copy/dictate recently", "recent links from Safari", "my longest dictations") show exactly when to reach for this tool. It does not state when to use eve_search instead, so the when-not/alternative half of the guidance is absent.

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 usefully discloses the state change ('clears their deleted flag') and a side effect ('The running app refreshes automatically'), which tells the agent no restart is needed. However, it omits permission requirements, whether restore is idempotent, and what happens on partial failure across multiple targets.

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, each earning its place: what it does, how to find inputs, and the observable side effect. The core action is front-loaded with zero 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?

For a single-parameter batch mutation with no output schema, the essential context is present: the effect, the discovery path, and the user-visible consequence. The remaining gap is feedback-related — it doesn't say what is returned (e.g., a restored count) or how invalid/unknown target IDs are reported, which matters for a batch operation.

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% — the `targets` array is fully documented with the `<type>:<id>` format and the five allowed types. The description adds nothing about the parameter beyond the discovery hint, so baseline 3 applies: the schema does the work and the description does not need to compensate.

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 and resource ('Brings soft-deleted history entries back') and parenthetically explains the mechanism ('clears their deleted flag'). This clearly distinguishes it from siblings like eve_recent (listing), eve_get (fetching), and eve_search.

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 routes the agent to the right discovery path: 'Find candidates with eve_recent's deleted option.' That tells the agent the prerequisite step before calling this tool. It stops short of stating exclusions, such as what to do if the entry was never deleted or hard-deleted, but the core when-to-use 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?

No annotations are provided, so the description carries the full behavioral burden, and it satisfies most of it: return shape (clips[] and transcriptions[] with match snippets), default ordering, top-N behavior, the single-source constraint on non-relevance sorts, cursor paging, and FTS5 query semantics. It stops short of stating that the operation is read-only/side-effect free or discussing result limits or performance, which keeps it under 5.

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, each doing distinct work: what it searches, when to use it with examples, what it returns, and how to page. The paging constraint is front-loaded with the default-sort behavior instead of buried at the end.

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 an 18-parameter tool with no output schema, the description covers the essential shape of results, the top-level meta.next_cursor, and the sort/paging contract. Remaining gaps for a complex tool are the multiple source values (recordings, screenshots OCR) and how relevance scores behave, which the schema mentions only in passing.

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 baseline is 3; the description earns above that by explaining the interaction between sort, source, and cursor for paging, and by spelling out that plain words get prefix-matched while FTS5 syntax is honored. It does not add much for the many filter parameters (category, engine, origin, content_type), which the schema already documents well.

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-plus-resource statement: FTS5 full-text search across copied clips and voice transcriptions on this Mac. The two concrete examples ('the URL I copied from Slack', 'what I dictated about the budget') make the retrieval intent unambiguous and separate it from sibling tools like eve_recent or eve_get that retrieve without a query.

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 says explicitly when to use this tool (locating a specific item by remembered words) and how to switch modes, contrasting default relevance/top-N against chronological paging with sort=recency/created plus a single source and cursor. That is a clear use-case/alternative split rather than an implied one.

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 must carry the full behavioral burden. It discloses that data is written to log.jsonl on this Mac only and that the return value is {ack: true}, but it does not cover failure modes, permissions, concurrency, or idempotency.

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 tightly written sentences, front-loads the main action, and packs parameter and return details without unnecessary 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?

For a simple append-log tool with no annotations or output schema, the description covers the core action, local storage location, and return shape. However, missing semantics for doel and status, plus absent failure-mode details, leave meaningful gaps 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?

Schema description coverage is 0%, so the description must compensate. It names all five parameters and adds useful detail for type (call, sms, whatsapp, …), ts (epoch ms), and optional inhoud, but leaves doel and status unexplained.

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 verb and resource: record one call or message line from the RoxyBot phone. It clearly identifies the tool as a logging operation, though it does not explicitly distinguish it from any sibling tool.

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 implies that this is used to log a call or message line, but gives no explicit guidance on when to use it versus alternatives or when not to use it. No sibling tool is referenced as an alternative.

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 it does disclose the return shape and the null-when-unknown semantics, which is genuinely useful. It does not cover the set of valid keys, whether keys are case-sensitive, or any permission/scoping considerations.

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 zero filler; the purpose comes first and the return contract second, so the agent gets the essential facts immediately.

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 read tool with no output schema, the description supplies the missing return structure, so an agent knows exactly what to expect. Only the domain of valid keys and any failure modes are left unspecified.

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% and the single 'sleutel' parameter is already documented with the same 'thuis'/'werk' examples used in the description. The description therefore adds little beyond the schema, which is the expected baseline for a fully documented parameter.

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 and resource ('Read a saved personal value') and grounds it with concrete examples ('thuis' or 'werk' address). It is clearly distinct from the unrelated sibling set (eve_*, contacts_resolve), though that separation comes from topic, not from any explicit differentiation.

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 phrase 'Read a saved personal value' implies the usage context, but there is no statement of when to prefer this tool, what happens if the key was never set, or what a companion write path would be. Usage is inferable but not guided.

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