Contextli Voice Notes

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety and repeat-safety profile is covered. The description adds only the implicit constraint that the note must already exist; it says nothing about adding an unknown label; so it clears the lower bar but adds little.

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 sentence with the action front-loaded and zero filler. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter mutation with no output schema and rich annotations, the definition is adequate. It leaves only minor gaps, such as whether a nonexistent label is created and what happens when note_id is invalid.

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 both parameters (labels, note_id) are fully documented in the schema, including the non-duplication guarantee. The description's 'one or more labels' merely restates the schema's minItems constraint, adding no new meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (add) and resource (labels on an existing note) plus the intent (organize or triage). It is unambiguous and no sibling tool competes for this action, though it does not explicitly differentiate itself from 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?

It gives a motivation for use ('to organize or triage it') but no when-to-use conditions, no prerequisites, and no routing to alternatives such as contextli_filter_notes_by_label. Usage is only implied.

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 write (readOnlyHint=false), non-destructive, non-idempotent, and closed-world. The description adds that the note originates from the current chat and can be filed under a chosen context, which is useful behavioral context beyond the safety profile. It does not, however, disclose the duplicate-creating consequence of non-idempotency or any auth/rate-limit details, so a 3 fits with annotations covering the basics.

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, front-loaded sentence with zero filler. Every word earns its place for a simple create tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple create tool with full schema coverage and annotations, the description covers the core purpose but omits usage guidance, return behavior (no output schema), and idempotency implications. It is minimally adequate but leaves gaps an agent might need when deciding to call 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%, so the schema fully documents text, labels, and context_id. The description mentions context placement and optional labels, but adds no syntax, format, or constraint details 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 'Create' and resource 'note', plus scope 'from this chat' and placement in a chosen context. It does not explicitly distinguish itself from siblings like contextli_add_label_to_note or the read tools, but the creation intent is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use guidance or alternatives. It implies the action is creating a note, but an agent gets no help on when to choose this over adding a label, searching, or filtering. The schema's context_id description carries a usage hint, but that is outside the description itself.

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, destructiveHint=false and a closed world, so the safety profile is fully covered. The description adds only that scoping is optional, providing little behavioral context such as result ordering or how empty label matches behave.

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 front-loaded sentence that names the resource, the primary filter, and the optional scoping in one pass, with no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only filtered-list tool with no output schema, the description plus the fully documented schema give the agent enough to call it correctly. The only shortfall is the absence of any tie-breaker against closely related sibling tools.

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 labels semantics (OR / any-of, case-insensitive), pagination, and date bounds are already fully documented in the schema. The description merely echoes the existence of context and date-range filters, adding no syntax or format detail beyond the structured fields.

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 ('Get') and resource ('notes') with the distinguishing filter ('one or more specific labels'), so the core operation is unambiguous. It does not, however, explicitly contrast itself with siblings like contextli_search_notes or contextli_get_notes, leaving the agent to 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?

The phrase 'optionally scoped to a context or date range' hints at when the extra filters apply, but there is no explicit when-to-use guidance versus search_notes or get_notes, and no exclusions. Usage is only implied.

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 safety is covered. The description adds genuinely new behavior: images (max 3) are returned as image content after the text, and list results expose only short-lived signed URLs. It stops short of describing pagination, size limits, or failure modes.

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, each doing distinct work: what it returns, how images are delivered, and why the sibling tools' URLs are insufficient. Front-loaded with the primary purpose and no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does explain text, metadata, and image content ordering. Metadata is mentioned but never itemized, which is a minor gap for a tool whose whole job is retrieval.

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 are documented, including the default for include_images, so the baseline is 3. The description adds value beyond the schema by capping images at 3 and specifying they arrive after the text, but note_id format/source detail is left 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 precise verb and resource ('Fetch a single note's full text and metadata by its id'), and the singular scoping implicitly separates it from the plural list/search siblings. The image-handling sentence further pins down what the tool uniquely does.

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 routing rule: results from the other tools surface images as short-lived signed URLs, so 'call this tool to view them.' That is a real when-to-use condition tied to a sibling behavior, though it doesn't state exclusions or prerequisites (e.g., what happens for a nonexistent id).

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 burden is covered. The description goes further by disclosing result ordering (newest first), that full text is returned, that images surface under an `images` key with a pointer to contextli_get_note, and that label filtering is ANY-match and case-insensitive. Missing only rate-limit/authorization context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core behavior in the first sentence and lays out filters, pagination, the sibling alternative, and the image caveat in order. Slight redundancy with the schema on label semantics keeps it just below 5, but there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still conveys return shape (full text notes, newest-first, `images` field, next_offset pagination) and covers every filter and its interaction. An agent has everything needed to call this tool correctly without follow-up questions.

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 all six parameters are already documented, and much of the description's parameter text (ANY-label matching, case-insensitivity, list_contexts for ids, next_offset for pagination) duplicates the schema. It adds mild workflow framing but no syntax or format detail beyond structured fields, making the baseline 3 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 user's Contextli voice notes and transcriptions'), plus the ordering and payload ('newest first, with their full text'). It explicitly contrasts itself with the sibling contextli_search_notes, so an agent can disambiguate without reading 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?

Gives concrete when-to-use cases ('browse recent notes or pull all notes within a date range, context, or label set') and an explicit when-not/alternative rule ('When the user is searching for a specific keyword or phrase, use contextli_search_notes instead'). It also routes to contextli_list_contexts for valid context ids.

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/non-destructive annotations, the description discloses a real behavioral caveat: 'many notes are not tagged with a context,' warning the agent that context filtering is unreliable. It also enumerates the returned content (contexts plus counts, active context ids, earliest/latest dates), which is exactly the kind of 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?

Front-loaded with the discovery purpose, then the return payload, then the calling rule and the caveat—every sentence earns its place with no filler or repetition. It stays compact despite covering return shape and usage guidance.

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 output schema, the description fills the gap by detailing what the call returns and when to use it, so an agent needs nothing further to call it correctly. The data-sparsity note closes the remaining risk of over-relying on context filters.

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 no input parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description does not need to compensate for any 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?

Names a specific verb+resource ('List Contexts and Filters') and defines what 'contexts' actually are (modes with id, prompt, icon, color) plus the filter facets returned. It is clearly distinguishable from siblings like list_labels and filter_notes_by_label because it explicitly describes the discovery role.

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 ordering rule ('Call this FIRST when the user asks to filter notes by a context or by date') and states the payoff ('so you use valid ids and a valid date range'). It also steers away from the wrong approach by recommending text search and dates as primary filters.

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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the scope note that results are the user's own labels; it says nothing about ordering, empty results, or whether labels are account- vs workspace-scoped.

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 front-loaded sentence with the verb and scope first and the downstream rationale second. Every clause earns its place and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, fully annotated read-only listing tool with no output schema, the description is sufficient to call it correctly. It could briefly characterize the returned list (shape/ordering), but the annotations already carry the behavioral essentials.

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, which is the baseline-4 case; there is nothing for the description to disambiguate. The '(tags)' gloss mildly reinforces what the parameter-less call yields.

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 ('List all of the user's labels') and clarifies the domain term with '(tags)', so the agent knows exactly what comes back. It does not name a sibling, but the mention of filtering/applying implicitly separates it from contextli_filter_notes_by_label and contextli_add_label_to_note.

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 clause 'so you know what's available to filter or apply' gives a clear reason to call it, i.e. discovery before filter_notes_by_label or add_label_to_note. No explicit exclusions or named alternatives, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavior beyond them: case-insensitive matching, newest-first ordering, a short snippet around the match, and ANY-of-label semantics. It does not mention auth requirements or rate limits, so not a full 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 core purpose and usage, then narrowing filters, then pagination, then the alternative. Every sentence carries information, though it runs somewhat long across five sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-param search tool with no output schema, the description covers matching semantics, result ordering, snippet return, filter narrowing, and pagination, leaving nothing an agent needs to call it correctly unstated.

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 meaning beyond the schema by explaining that labels match ANY of the given labels case-insensitively, that date params are narrowing bounds, and that limit/offset drive pagination. This is additive context rather than restatement.

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 (search) and resource (the user's Contextli voice notes/transcriptions) with scope (keyword or phrase, case-insensitive, across note text). It clearly distinguishes itself from contextli_get_notes (browsing) and contextli_filter_notes_by_label, so an agent can pick it without opening other 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?

Explicit when-to-use ('when the user is looking for notes about a topic, person, or phrase they remember saying') and names the alternative for the no-keyword case ('For browsing without a keyword, use contextli_get_notes'). It also routes the agent to contextli_list_contexts to obtain valid context ids.

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