Kalima

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds useful behavioral context: ownership and completion filters, the 20-item cap, returned locations/summaries/destinations/cursors, and the permission context for the follow-up review tool. It does not explain cursor lifecycle or pagination behavior in detail.

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 short and front-loaded: the filtering scope comes first, followed by return contents and the downstream workflow. Every sentence carries useful selection or invocation context without 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?

The annotations and output schema reduce the burden, and the description covers purpose, return categories, and workflow context. However, with four undocumented input parameters and ambiguous cursor parameters, it is not fully complete 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% for four parameters, so the description must compensate. It mentions 'up to 20' for limit and that cursors are returned, but it never explains the semantics of cursor, projectCursor, or workspaceCursor beyond a vague reference to cursors.

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: finds own, finished recordings with no project or workspace, capped at 20. It also distinguishes the result set from the sibling review_recording_assignments by naming it as the downstream consumer.

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 a clear usage scenario ('meine Sitzungen aufräumen') and explicitly says the results are input for review_recording_assignments, including the relevant permission condition. It does not, however, contrast this tool with list_recordings or search_recordings when those might also seem relevant.

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?

Annotations already cover read-only/idempotent safety, but the description adds substantial behavioral detail: polling with resumeCursor returns only new text, provisional segments are re-sent, revised entries correct earlier text by index, and session.isLive/hasMore/found flags signal state. This is exactly the context an agent needs to poll correctly.

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?

Dense but front-loaded: live-reading intent comes first, then response semantics and flags. The three-language example queries are useful for matching user phrasing but make the opening slightly heavier than necessary.

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?

Even with an output schema present, the description explains the practically important response fields (segments/transcript, provisional, revised, resumeCursor, session flags) and the default detail level. Nothing an agent needs in order to poll 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%, so the baseline is 3, but the description adds meaningful semantics: sessionId fallback to the user's own recording, tailSegments versus cursor interaction, and that detail defaults to 'speaker' and behaves like get_transcript. Minor naming drift ('resumeCursor' versus the schema's 'cursor') keeps it from a 5.

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 with scope: 'Reads a recording that is running right now', and the example queries anchor the intent. This cleanly separates it from get_transcript/show_transcript, which handle completed recordings.

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?

Explains the no-sessionId default (user's own running recording first) and the tailSegments alternative for joining a long recording already in progress. It does not explicitly name get_transcript as the alternative for finished recordings, though the 'running right now' framing implies it.

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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds scope semantics beyond that: sub-projects are excluded from the result and the response includes aggregated stats (recording count, total duration) — useful behavioral context. It does not discuss pagination or limits on 'most recent recordings', which keeps it from 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?

Front-loaded with the verb, key, and returned fields, followed by routing guidance. The two example utterances are helpful but slightly bulk out an otherwise tight two-sentence definition.

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?

An output schema exists, so return values need no prose explanation, and the single parameter is fully documented in the schema. The description covers what an agent needs: scope, exclusions, and the alternative tool for the excluded case.

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 projectId field already documents that it is 'as returned by list_projects.' The description only restates that the tool takes a projectId, adding no format or sourcing detail beyond the schema, so 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 and resource ('Returns one Kalima project by projectId') and enumerates the payload fields: name, description, recording count, total duration, last activity, recent recordings. It also distinguishes itself from list_projects by naming the sibling and the parentProjectId route to sub-projects.

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?

Provides concrete user-intent examples ('show me the Meridian project', 'wie viel haben wir für DKV aufgenommen') that map directly to this tool, plus an explicit exclusion and alternative: sub-projects and their recordings are not included, use list_projects via parentProjectId.

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 readOnlyHint/idempotentHint/non-destructive already declared, the description still adds real value: timestamps are UTC, ids/status/mode are internal, and '"active" means still running' clarifies a term that would otherwise be ambiguous. It stops short of describing error behavior for an unknown sessionId.

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 return contents, then the alternative routing, then the semantic clarifications. The bilingual example queries are slightly unusual but serve a selection purpose; no sentence 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?

An output schema exists, annotations cover the safety profile, and the parameter is documented, so the description only needs to add selection and behavioral context — which it does. Minor gap: nothing about failure modes or how 'last activity' relates to the transcript.

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 single sessionId parameter is already documented with its UUID pattern and provenance (list_recordings/search_recordings). The description adds nothing about the parameter, so 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 and resource ('Returns one recording's...') and enumerates the exact fields returned (title, start time, duration, participant count, last activity/segment, word/audio-file counts). It also names the sibling it is not (get_transcript), so an agent can distinguish it without opening 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?

Explicitly routes the agent to get_transcript 'for what was said', and the example user questions ('how long was that call', 'wie viele Teilnehmer waren dabei') show the query shapes this tool answers. It doesn't state prerequisites or other exclusions, but the primary alternative is covered.

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?

Annotations already declare readOnly, idempotent, non-destructive and non-open-world, so the safety profile is covered. The description adds that the output is aggregate totals over the whole filtered set rather than individual recordings, which is the key behavioral distinction for an agent.

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 core purpose and returned metrics, followed by examples, then a one-line note on filters. It is efficiently sized; the bilingual example is slightly extraneous but doubles as a phrasing hint.

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 an output schema present and full schema coverage, the description needn't explain return values or parameters. It states purpose, aggregate fields, and filter scoping—enough for correct invocation, though a brief pointer to when to prefer it over list_recordings would complete 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?

Schema description coverage is 100% with all 13 parameters individually documented, including enums and patterns, so the schema carries the semantic load. The description only summarizes the filter scopes (project, team, period) without adding format or interaction details beyond the schema, hitting the 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?

It names a specific resource and verb ('Totals over the user's Kalima recordings') and enumerates exactly which aggregates are returned (count, duration, transcribed words, first/last time). It doesn't explicitly contrast with list_recordings or search_recordings, so an agent must infer that this aggregates rather than lists.

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 example questions ("how many hours did I record last month", "wie viele Besprechungen hatte ich") give concrete trigger contexts, and 'The filters scope it to a project, team or period' clarifies the narrowing behavior. No explicit when-not or named alternative (e.g. list_recordings for raw rows) is provided.

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?

Annotations already cover read-only, idempotent and non-destructive; the description adds real context beyond them: no new summary is generated or charged, missing summaries and uncertain freshness are reported in the result, and a separate summary permission is required and only obtainable by reconnecting Kalima. These are exactly the facts that change agent behavior.

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?

A single dense paragraph that front-loads the purpose, then scope limit, then behavioral caveats, then permission need. Every sentence earns its place, though the embedded example quote is slightly awkward mid-sentence.

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?

An output schema exists, so return-shape explanation is correctly omitted, and the permission, staleness and no-charge behaviors are covered. The remaining gap is how to obtain valid sessionIds, which neither schema nor description explains.

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 carry the burden, and it only partially does: the 'up to 20' limit maps to maxItems and hints at batching, but nothing explains that sessionIds are UUIDs of the user's recordings or where to get them (list_recordings). Baseline 3 given one simple parameter with a strong pattern/maxItems constraint in 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?

States a specific verb (reads) and resource (saved AI summaries of the user's own recordings), with a concrete example query that pins down the intent. It explicitly distinguishes itself from get_transcript, so the agent can route between them without opening a 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 the natural-language use case and names get_transcript as the alternative for full text. It lacks an explicit 'do not use this when...' exclusion (e.g., for recordings without a summary or for raw text search), so it stops just 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?

Beyond the readOnly/idempotent annotations, it discloses pagination via nextCursor, the size cap implied by 'a page at a time', the meaning of isLive, and that resumeCursor hands off to get_live_transcript so only subsequent speech is returned. That is exactly the behavioral context annotations cannot carry.

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?

Purpose and scoping come first, then detail modes, then pagination and live state — a sensible front-loaded order with no filler. The example-query list is slightly verbose relative to its value, but each clause still carries information.

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 a full schema and an output schema present, the agent needs only the paging model, the detail trade-off, and the live-recording handoff — all supplied. Nothing required to call 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%, so the baseline is 3, but the description adds intent the schema lacks: which detail mode suits summarising versus citations, and that 'full' is the default. Cursor and limit handling are only loosely described ('continue with nextCursor'), leaving the rest to 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?

States a specific verb and resource ('returns the transcript of one recording by sessionId') plus the scoping unit (one recording, paged). The detail-mode explanation and the pointer to get_live_transcript for live continuation separate it from siblings such as search_all_transcripts and show_transcript.

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 concrete trigger queries in two languages ('what did we discuss', 'fasse die Vorlesung zusammen') and tells the agent when to switch to get_live_transcript with resumeCursor. It stops short of excluding sibling tools such as show_transcript or search_within_recording, so the routing is clear but 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds behavior beyond that: results are restricted to active memberships and each row carries role and organizationId, which tells the agent what it will and won't see.

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 the core purpose front-loaded, followed by example intents and the cross-tool linkage. The bilingual example is arguably slightly longer than necessary but earns its place for intent matching; nothing is 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?

With no input parameters, an output schema present, and rich annotations, the description covers everything an agent needs to select and call it: purpose, membership scope, returned fields, and how the result feeds the recording tools. Only the absence of an explicit alternative comparison keeps it from full marks.

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 and nothing in the description is needed to clarify inputs. The description instead reuses the org id as a downstream filter for the recording tools, which is a useful but separate hint.

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 ('Lists the Kalima organizations') plus the scope qualifier 'the user is an active member of' and the key returned fields (role, organizationId). It implicitly distinguishes itself from list_projects/list_workspaces/list_teams by resource, but never names those siblings to rule them out explicitly.

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?

Provides concrete trigger phrasing ('which organizations am I in', 'zu welcher Organisation gehöre ich') so an agent can match user intent directly. It also adds a forward-pointer that the returned id is the organizationId filter for the recording tools, which is real routing value; it stops short of stating when NOT to use it.

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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: one level of nesting via parentProjectId/path, and that counts are per project rather than rolled up — a detail that would otherwise cause wrong inferences.

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 the identity of the resource, then scope/contents, then the navigation hint. The quoted e.g. phrases earn their place by anchoring real user phrasings to this tool; no sentence is 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?

With an output schema present, return values need not be explained, and annotations cover safety; the description nonetheless fills the important gaps (nesting depth, per-project counts, next-step routing). The one residual gap is guidance on the sort parameter's three modes, which neither schema nor description explains.

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 only 50%: limit and cursor are documented in the schema, but sort and query carry no schema description. The description compensates for query ("find a project by name") and implies paging via the projectId follow-on flow, but adds nothing about sort's recent/oldest/name enum or how limit interacts with paging. Partial compensation, so borderline.

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 ("Lists the user's Kalima projects") and immediately disambiguates what a project is ("folders that group recordings") and its scope (own and shared). The example phrasings plus the note on nesting and non-rolled-up counts let an agent distinguish this from get_project and list_recordings without opening 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?

Offers clear routing: "Use query to find a project by name, then pass its projectId to list_recordings or get_project," which names the follow-on siblings explicitly. It stops short of stating when not to call this (e.g. when you already hold a projectId and should call get_project directly), so it is clear context rather than full when/when-not coverage.

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?

Annotations already cover read-only/idempotent safety, and the description goes further by disclosing the default ordering, the returned fields (title, start time, duration), and the important caveat that no end time exists so callers must derive it from startedAt plus durationMs. Minor gap: it doesn't mention pagination behavior, though the cursor parameter is documented in 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?

Purpose and default ordering are front-loaded, and each sentence carries useful information (examples, return shape, limit/sort advice). The multilingual example strings are slightly indulgent but demonstrate natural query shape, so they mostly earn their 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?

Given 16 optional parameters, a rich schema, and an existing output schema, the description covers what matters most: default ordering, how to size the request, and the missing-end-time caveat. It does not indicate when to route to search_recordings or find_unassigned_recordings instead, which is the main residual 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 94%, so the baseline is 3. The description adds real guidance for limit and for sort ("oldest" finds the first, default newest), but leaves the other sort enum values (longest, shortest, name) and all 13 filter parameters to 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?

States a specific verb and resource ("Lists the recordings in the user's Kalima account") plus the scope of content types covered and the default order (newest first). It does not name sibling tools like search_recordings or find_unassigned_recordings, so the agent gets no explicit differentiation against them.

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?

"Answers questions such as 'my last meeting'..." and "Set limit to what the question needs, e.g. 1 for the latest recording. sort 'oldest' finds the first" give concrete when-to-use guidance tied to limit/sort choices. What's missing is any exclusion or pointer to the alternative tools when a keyword search is actually required.

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?

Annotations already declare readOnly/idempotent/non-destructive, so the description correctly spends its words elsewhere: it discloses the critical aggregation caveat that unnamed speakers collapse into a single 'unnamed' bucket because 'Speaker 1' is a different person per recording. That is exactly the kind of non-obvious behavior an agent would otherwise get wrong; it only lacks notes on ordering or cost of the aggregation.

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 core definition and return shape, then the unnamed-speaker caveat, then the filtering hint — a sensible ordering. Slightly long and the bilingual example query is a nice touch but adds a little bulk; nothing is genuinely wasted though.

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?

An output schema exists, so the description needn't fully spec the return values, and it still summarizes the key ones. With 15 optional parameters and 100% schema coverage, the remaining need is behavioral guidance, which the unnamed-speaker note and filter hint supply. Missing only edge details like default ordering or behavior when no speakers match.

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 every one of the 15 parameters is already documented in the schema, including the enum values and ISO-8601 formats. The description only name-drops projectId and startedAfter as suggested filters, which is usage advice rather than added parameter meaning, so the 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 and resource ('Lists the people in the user's recordings') and goes further by naming exactly what is returned per speaker: recording count, segment count, and last-spoken time. No sibling tool covers speaker aggregation, and the example queries ('who do I meet with most') make the intent 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?

The two example utterances give an agent a concrete trigger pattern, and 'Works well with a filter such as projectId or startedAfter' tells it to scope the call rather than enumerate everything. It stops short of naming an explicit alternative or a when-not-to-use condition, so it falls just short of 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond them by stating the result is scoped to the calling user's memberships and that teamId feeds the recording-filter tools, which is non-obvious cross-tool behavior.

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 compact sentences: scope first, then example intents and the downstream link. The bilingual example phrasing is slightly redundant but earns its place by anchoring natural-language triggers.

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 no parameters, an output schema, and full annotations, very little is left to explain. The description covers scope, filter-linkage, and trigger vocabulary; only an explicit statement of the no-argument / full-list behavior and any auth or pagination nuance is absent.

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 applies and no parameter explanation is required. The mention of teamId is about output/follow-up usage rather than an input, so it does not compensate for anything missing.

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 ("Lists the Kalima teams the user belongs to") and enumerates the returned fields (role, teamId, organizationId), which distinguishes it from list_organizations and list_workspaces. It does not explicitly contrast itself with those siblings, so it stops short of a 5.

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 concrete trigger phrasings ("which teams am I on", "in welchen Teams bin ich") that make the intended usage unambiguous, and notes the resulting id is consumed by the recording tools, which points to the follow-up call. No explicit when-not-to-use or named alternative is provided.

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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value beyond them by explaining that these IDs are valid as move_recordings destinations and as the workspaceId filter — downstream semantics the annotations cannot convey. It does not mention pagination behavior despite limit/cursor existing.

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: identity and return shape first, scope disambiguation second, downstream ID usage last. Every sentence 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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The remaining gap is paging behavior for limit/cursor, which an agent may need to enumerate more than the default 50 workspaces.

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 both parameters (limit with min/max/default, cursor) are undocumented, and the description says nothing about pagination, page size, or how to resume with a cursor. With two params carrying zero schema documentation, the description needed to compensate and does not.

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 ('Lists the user's personal Kalima workspaces') plus what is returned ('with IDs and names'). It also explicitly separates the resource from similar-sounding siblings: 'not organizations or teams', which matters given list_organizations and list_teams exist.

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?

Provides a natural-language trigger example ('welche Arbeitsbereiche habe ich') and rules out the organization/team siblings, so the agent knows which list tool to pick. It stops short of explicit when-not conditions or naming the alternatives directly, but the disambiguation 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?

Annotations only flag destructiveHint/idempotentHint; the description goes far beyond them, disclosing the preview-first safety model, that the preview returns accessChanged warnings, the five-minute token lifetime, and the invalidation conditions (assignments or project access changing). It also reassures that recording content and transcription settings are untouched, which correctly scopes the 'destructive' annotation to organizational metadata.

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?

Five short sentences, front-loaded with scope then the call protocol, with no filler. The embedded German example utterance is the one expendable element, though it may help intent matching.

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 an output schema exists, return-value documentation is unnecessary, and the description still covers the batch cap, permission requirement, token expiry and mutation scope. An agent has everything needed to execute the two-call flow 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% at the top level, so the description carries the burden and largely does: it explains that assignments triggers a dry run, that confirm:true must be paired with confirmationToken and no assignments, and that the token is the sole carrier of the pending change. It does not address edge cases such as confirm:true without a token or mismatched token/assignment combinations.

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, resource and scope: 'Moves up to 20 recordings to projects or personal workspaces.' The two-phase preview/confirm mechanic further pins down what the tool actually does. It does not name the closely related siblings preview_recording_assignments or review_recording_assignments, so an agent must infer the boundary itself.

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 call sequence is spelled out precisely: a call with assignments is a no-op preview, and a call with confirm:true plus the returned confirmationToken applies it. The prerequisite ('Needs the separate organize permission, which the user grants by reconnecting Kalima') is a genuinely useful gating condition. What is missing is explicit routing to the sibling preview/review tools when the agent only wants to inspect assignments.

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?

The annotations already declare read-only, non-destructive, idempotent behavior. The description adds useful context beyond that: it returns an expiring token and cannot apply changes, which is important for understanding the tool's role.

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 short sentences and front-loads the read-only nature. The German example is small and optional; the rest is efficient.

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 one complex required parameter and the presence of closely related siblings, the description is not complete enough. It never clarifies what an 'assignment' is or how the expiring token should be used, leaving important context missing despite the output 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 description coverage is 0% for the sole top-level parameter, and the description does not explain the assignments array structure, required sessionId, null semantics, or the 20-item limit. The description says only 'destinations', which does not compensate for the schema gap.

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 gives a specific verb (preview) but the resource is vague as 'destinations' rather than recording assignments. It also does not differentiate itself from siblings such as review_recording_assignments or move_recordings.

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 example phrase 'meine Auswahl prüfen' hints at a use case, but there is no explicit guidance on when to use this tool versus review_recording_assignments or move_recordings. No exclusions or prerequisites are stated.

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?

Annotations already declare readOnlyHint and destructiveHint=false, and the description goes substantially further: it names the required scope (mcp:read, not mcp:organize) and describes the degraded mode when canOrganize is false (suggestions shown, applying disabled) plus what text clients receive. That is permission and behavior context an agent cannot get from the annotations.

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 permission and capability statements are front-loaded and each sentence carries information. The embedded German example phrase ('welche Zuordnungen passen') is slightly cryptic and does not clearly earn its place, mildly blunting an otherwise tight definition.

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 an output schema present, return values need not be described, and the description covers limits, permissions, degraded behavior, and input sourcing. The remaining gap is the missing contrast with preview_recording_assignments, which is the closest sibling and would normally be addressed here.

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, and it does: it explains that up to 20 sessionIds are accepted, that each may carry an optional suggested destination and a short reason, and where the ids come from. It stops short of explaining the null semantics for projectId/workspaceId, though the schema properties do carry those descriptions.

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: opens an assignment review widget populated with suggestions for recording session assignments. The sourcing of sessionIds from find_unassigned_recordings clarifies the role, but the description never distinguishes it from the near-identical sibling preview_recording_assignments, so an agent must infer the difference.

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 positioning in a workflow by saying the sessionIds come from find_unassigned_recordings, which tells the agent what to call first. It does not state when to prefer this over preview_recording_assignments or move_recordings, so no explicit exclusions or alternatives are offered.

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?

Beyond the read-only annotations it discloses the return shape (quote + recording title, speaker, startMs), ordering (newest first), match semantics (all words of query, or any one term), the 3-quotes-per-recording cap, and pagination behavior via incomplete/nextCursor. These are non-obvious traits an agent could not infer from annotations alone.

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 and return shape, then matching rules and pagination, with no filler sentences. Some parenthetical density and multilingual examples add length, though they do demonstrate legitimate multilingual query support.

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 18 optional parameters, an output schema, and annotations covering safety, the description supplies the essential search semantics, ordering, cap, and pagination that structured fields cannot. It does not clarify how limit interacts with the per-recording 3-quote cap, a minor 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 the baseline is 3, but the description adds real meaning about query semantics — conjunction of words within a query versus disjunction across terms — plus the 3-character minimum. Filter parameters are left entirely to the schema, which is acceptable given full coverage.

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?

Specific verb and resource (search quotes across all recordings) with the exact result shape and ordering stated up front. It explicitly differentiates itself from the sibling search_within_recording, so an agent can pick between them without opening either 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 the alternative (search_within_recording returns all quotes in one recording) and provides example queries that imply typical usage. It does not explicitly route metadata-only lookups to search_recordings or state when not to use this broad scan, so it falls short of a full when/when-not guide.

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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds useful context beyond that: ranked results, matching snippets with UTC start times, and the fact that it spans all recording kinds. Pagination semantics (cursor) are left to the schema, keeping this from 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?

Three sentences, front-loaded with purpose, then examples, then sibling routing and constraints. Multilingual examples are compact and earn their place by illustrating the natural-language matching behavior.

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 17 optional parameters, an output schema, and rich annotations, the description covers what to search, what comes back, and which sibling to use instead. It does not mention paging or how the many filter parameters (team/project/workspace/status) combine, but those are well-documented in the schema, so the remaining gap is minor.

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 every one of the 17 parameters is already documented, including the query/terms interplay and min lengths. The description restates the query and terms semantics but adds no new syntax, format, or filtering guidance beyond what the schema provides, so 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 and resource (finds recordings) with the two retrieval modes (title or spoken content) and examples. It explicitly distinguishes itself from the sibling tools search_all_transcripts and search_within_recording, so an agent can route correctly without opening schemas.

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 when-to-use guidance with named alternatives: search_all_transcripts for cross-recording quotes, search_within_recording inside a known recording. It also explains the query-vs-terms interaction and the 3-character minimum, leaving little to inference.

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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds real behavioral detail beyond that: results are segments in order with speaker and startMs, only matches are returned (no full transcript paging), and the 3-character minimum is surfaced in prose.

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 core purpose and scoping constraint come first, with constraints and the terms/query relationship packed into the second sentence. Every clause carries information an agent needs.

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 6-parameter read-only search with full schema coverage and an output schema, this covers what an agent needs: what it returns, how results are shaped, the minimum query length, and the terms semantics. Return-value documentation is correctly delegated to the output 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 baseline is 3. The description goes further by explaining the OR-match intent of terms ('any of several words, synonyms or spellings in one call') and the interaction where query becomes one more alternative, which helps an agent choose between query and terms rather than duplicating schema text.

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+scope: finds where a topic came up inside one recording identified by sessionId. The two example queries (English and German) make the intended use immediately concrete, and 'inside one recording' implicitly separates it from the sibling search_all_transcripts.

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?

Example phrasings make clear when this is the right tool, and 'without paging the whole transcript' signals it is preferable to pulling a full transcript for a targeted question. It never names an alternative tool explicitly or states when not to use it, 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive behavior, and closed-world scope, but the description adds important behavioral context: the transcript words go to the view only, shownInView is true, and the result carries title and length. This clarifies the side effect and result shape beyond what annotations provide.

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 definition is front-loaded with purpose and scope, then follows with examples, view behavior, and the sibling alternative. Each sentence contributes useful selection or invocation context without bloat.

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 tool is simple, the parameter schema is fully documented, annotations cover safety traits, and an output schema exists. The description still adds the key view-specific behavior and the get_transcript routing guidance, so an agent has enough context to select and invoke it 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?

There is one required parameter, sessionId, and schema description coverage is 100%, so the schema already defines it as the recording id returned by list_recordings or search_recordings. The description confirms the tool operates on one recording, but adds no meaningful syntax or format details beyond the schema baseline.

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 and resource: it shows the full transcript of one recording to the user in a Kalima view with speakers and timestamps. It also distinguishes the display use case from reading/quoting/summarising by naming get_transcript as the sibling alternative.

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 clear usage signals, including example phrases like "show me the transcript" and "zeig mir das Transkript meiner letzten Besprechung." It also explicitly states when not to use this tool: to read, quote or summarise, use get_transcript.

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