Caddie

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

With no annotations, the description carries the full burden. It usefully discloses the Caddie constraint that select-column options must be requested from the user, which is real behavioral context. However, it omits permissions, reversibility, duplicate-name handling, and what the call returns 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?

Two compact sentences, front-loaded with the core operation and the column structure, followed by the caveat. No wasted prose.

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 a nested object and no annotations or output schema, the description covers structure and one key behavioral edge case but leaves gaps: return value, error/duplicate behavior, and whether existing rows are affected when adding a column.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, and the description adds value beyond it by spelling out the column object shape ({ name, type, options?, unique? }) and clarifying that options applies to select columns. The 'as in create_data_table' cross-reference helps an agent construct valid nested input.

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: 'Add a column to a data table', and clarifies the column shape by referencing create_data_table. This distinguishes it from siblings like add_rows or create_data_table, though it doesn't explicitly contrast when to extend an existing table vs. create a new one.

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 meaningful constraint: for select columns, if a needed value isn't an option, ask the user rather than creating a near-duplicate. But there's no explicit guidance on when to use this vs. create_data_table or other column-related operations; usage is largely 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?

With no annotations, the description carries the full behavioral burden and does disclose real constraints: a 50-item batch ceiling, a 40-character per-item limit, and skip-on-duplicate semantics. It omits permissions requirements and whether the response reports skipped vs added items, which is the remaining gap for an unannotated 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?

Two sentences, front-loaded with the purpose and the destination, followed by the limits and dedupe behavior. Every clause carries information an agent would otherwise have to guess.

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, unannotated, no-output-schema write tool, the description covers purpose, limits, and idempotency. It stops short of describing what the call returns or how partial failures are reported, which would fully close the loop.

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 0% — the single `words` array param has no description at all — so the description must compensate, and it does: it explains the array holds names/terms, its batch limit of 50, and the 40-character constraint per item. Only the item format (plain strings vs phrases) is left implicit.

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 — add names and terms to the user's dictation dictionary — and even names the exact settings location (Settings › Dictation). No sibling tool covers dictation vocabulary, and the description makes the scope 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 concrete examples of what belongs in the dictionary (people, companies, products, jargon), which tells an agent when this tool is the right call. There are no exclusions or stated alternatives, but none exist among the siblings, so the gap is minor.

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 so: it discloses atomic all-or-nothing behavior, that the error identifies the failing row and reason, and that unique-column collisions are rejected. These are exactly the behavioral traits an agent needs before attempting a bulk write.

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 action and batch limit, then value formats, then atomicity, then the redirect to upsert_rows. Every sentence adds distinct operational information with 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?

There is no output schema, and the description only covers the failure path (which row failed and why), not what a successful call returns such as a count of inserted rows. Everything else needed to invoke it correctly is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, and the description more than compensates by defining the rows payload as {column name: value} and specifying per-type value formats (YYYY-MM-DD dates, true/false checkboxes, option names for select/status, lists for multi-select). The table and workspace parameters are left to the schema, which documents them adequately.

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 ("Add rows to a data table") with an explicit batch bound and the row object shape. It also names the sibling it is not (upsert_rows), so an agent can distinguish it from update_rows/upsert_rows 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 an explicit exclusion with the routing condition: values already in the unique column are rejected, and upsert_rows is named as the tool to use instead. The 500-row-per-call limit also sets a practical usage boundary.

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 load and does disclose one valuable behavioral trait: the answer is consumed once and won't be re-sent. However, it doesn't say whether the call blocks until an answer exists or returns immediately with a pending status, nor what subsequent calls return -- critical for a polling 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?

Two short sentences with no filler, front-loading the retrieval purpose before the consumption caveat. The second sentence's phrasing ('it isn't sent to this task again') is slightly awkward but 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?

With no annotations and no output schema, the description should clarify return semantics and blocking behavior, but leaves both underspecified and never defines the sole parameter. It is adequate to know what the tool is for, but not fully sufficient to call 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?

The single required parameter 'request' has 0% schema description coverage, and the description never explains what it represents (a task/request id? the original question?). With low coverage the description is expected to compensate, and it 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?

The description clearly states this retrieves (a) whether an agent previously asked via ask_agent has answered, and (b) its answer, which distinguishes it from the ask_agent sibling that initiates the question. It lacks an explicit verb of its own (the name 'agent_reply' could read as a send action), but the text resolves that ambiguity.

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 ties itself to ask_agent, establishing the usage sequence (ask, then check here), and adds the important caveat that a retrieved answer is not delivered to the task again. It doesn't address polling cadence or how it relates to alternatives like task_wait/task_status for task-style replies, so guidance 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?

With no annotations, the description carries the full burden and does disclose meaningful behavior: the exact return shape ({agent, agent_id, tasks}), a 20-task cap per agent, and the degraded 'partial: true' response when some agents cannot be read. It omits permission/auth requirements and whether include_done defaults to false, which keeps it short of 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 scoping condition and the resource, then params, then return shape, then the sibling pointer. Dense but every clause carries information; the long parenthetical state list is the only mildly heavy element and it removes the need for a separate state reference.

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?

Covers return structure, the 20-task limit, and the partial-read failure mode despite there being no output schema and no annotations, and defines both parameters. Only default values and any auth/rate context are missing, which is minor for a read-only listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate, and it does: 'agent' is defined as a name or id, and 'include_done' is defined as including done tasks. It does not state the default value for include_done or whether 'agent' accepts multiple values, which is the remaining 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?

States a specific verb (list) plus resource (the user's agents' tasks), enumerates the possible states, and explicitly scopes it to clients outside Caddie (T3 Code, Claude Code, Codex). It also names the sibling that covers the other case ('Caddie's own agents: use list_agents'), so it is unambiguously distinguishable from list_agents and task_status.

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 when-to-use condition (clients outside Caddie acting for the user) and names the alternative tool for the complementary case (list_agents for Caddie's own agents). An agent can route correctly without opening either schema.

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. It reveals the mutation direction (appended to the end, not replacing) but says nothing about permissions, formatting handling, behavior when the id is not found, or what the response contains.

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?

One front-loaded sentence with zero filler; the mutation target and append semantics come first. It is efficient but so terse that it leaves no room for the behavioral context a no-annotation mutation tool 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?

With no annotations, no output schema, and only 33% schema coverage, the description should explain return value, error behavior on a missing note, and whether a separator is inserted. None of that is present.

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 33%: only 'workspace' is documented in the schema, and it is described well. The description adds real meaning for 'content' by specifying Markdown, and 'existing note' implies id is a note identifier, partially compensating for the undocumented id 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?

A specific verb ('Add') plus resource ('Markdown content ... existing note') with the append-to-end semantics made explicit, which distinguishes it from update_note or create_note. It stops short of naming those siblings directly, so it is clear but not fully differentiated.

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?

'existing note' implies the precondition that the note must already exist and that this is additive rather than replacing content, which is enough to choose it over create_note. However, it never states when to prefer this over update_note, nor any exclusions or prerequisites.

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 well: it discloses that archival is reversible ('a message to it brings it back'), that open tasks move with it, and — critically — that routines keep running, which is a non-obvious side effect. It omits permissions/auth needs and whether the call is idempotent or errors on an already-archived 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-loads the core action, which is good, but the UI analogue is stated twice ('as Archive agent on the Agents page does' and 'as in the app'), and the middle clause 'open tasks and all' is loose where precision is needed. Trimmed of redundancy it would be two tight 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?

No output schema and no annotations, yet the description covers the state change, reversibility, side effects on tasks and routines, and the unarchive override — enough to call it correctly. The remaining hole is return/error behavior and the identifier format for 'agent'.

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 0%, so the description must compensate. It handles 'unarchive' well ('puts it back in the list'), but gives no format guidance for the required 'agent' parameter — whether it takes an ID, a name, or a slug. That is the single most likely invocation error for this tool.

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?

Clear verb+resource pairing ('Archive one of the user's agents') with an explicit anchor to the equivalent UI action, so the agent knows exactly what operation this represents. It implicitly distinguishes itself from siblings like organize_agents, update_agent, and list_agents by being about archiving rather than listing/editing, though it never names 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?

The description implies usage ('as Archive agent on the Agents page does') and names one alternative path weakly — pause_routine is referenced as the way to stop routines. But there is no explicit 'use this when…/do not use this when…' guidance versus siblings such as organize_agents or update_agent, and no preconditions 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?

With no annotations, the description carries the full burden and does so well: it discloses that the ask runs as a new task on the target's Mac, how the answer returns (as a new message with from; via agent_reply without from), that task_status follows by task_id, the wait_seconds wait behavior, and a 4-asks-per-hour rate limit.

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 is front-loaded, but the middle is a dense run-on ('without it (a client outside Caddie), it's a message to it marked as asked from outside Caddie via this client') that is hard to parse. Every clause carries information, so it's not padded, but structure and readability suffer.

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 4-param tool with no output schema and no annotations, the description explains direction of the call, return path, and limits well enough to invoke correctly. It could be slightly clearer on what the returned answer message looks like, but the essential mechanics are covered.

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 50%, and the description compensates by explaining the semantics of from (your own agent:task:key, triggers automatic reply) and wait_seconds (up to 50, waits here for a quick answer). agent is covered by the schema's list_agents hint; message is self-evident.

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: asking another agent for something it's set up for, with scope ('its tools, files, sign-ins or what it knows'). This distinguishes it from agent_reply (which retrieves answers) and list_agents, though it doesn't name those siblings 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?

Gives clear context: use it to get something only another agent can provide, and 'Don't ask it to do what you can do yourself.' It also explains the from vs no-from scenarios and the rate limit. However, it doesn't explicitly contrast with agent_reply as a retrieval alternative beyond mentioning it in passing.

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 load, and it discloses the security-relevant traits: the link is public ("anyone with it can book"), the permission model (agent-initiated calls are refused; ask the user), and the return value (its URL). It omits idempotency, name-collision behavior, and any confirmation/rate-limit expectations.

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 short sentences: purpose and URL, the usage constraint, the refusal fallback, and the return value. Nothing repeats the schema, and the most decision-relevant facts come first.

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 22-parameter tool with nested objects and no output schema, the description covers the two things the schema cannot: who may call it and what it returns. The dense per-parameter schema text carries the rest, so no critical gap remains, though a hint about which params are typical for a first link would have helped.

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 91% across 22 parameters, so the schema already explains slug, tz, ranges, hosts, reminders, etc. in detail. The description only lightly mirrors this ("in the hours given", the URL/handle/slug path), adding no new parameter meaning beyond what the schema states.

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 ("Make a public booking link") plus the resulting URL shape and what the link enables. It is clearly distinct from update_booking_link / delete_booking_link / list_booking_links by virtue of the verb, though it never names a sibling 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?

"Only when the user asked for one" is an explicit when-to-use constraint, and the refusal clause ("from an agent's own turn inside Caddie it's refused: ask the user") tells the agent what to do instead in that case. No alternative tool is named, 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. It discloses only that the collection is created empty. It says nothing about behavior when a collection of that name already exists, whether the call is idempotent, permission requirements, or what is returned.

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, purpose front-loaded, with the sibling carve-out in a parenthetical. 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 two-parameter creation tool with no annotations and no output schema, the description covers intent but omits duplicate-name behavior and return information. The workspace parameter is rescued by the schema, leaving the definition only marginally complete.

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 only 50%: 'workspace' is well documented in the schema (including the personal-workspace default), but 'name' is undocumented in both the schema and the description. The description adds no meaning to any parameter, so it fails to compensate for the uncovered 'name' argument.

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 ('Make an empty collection (folder) for notes') and clarifies that it creates a container with no notes inside. The parenthetical names sibling paths (create_note, move_note) that also produce collections, which helps an agent differentiate, though it doesn't distinguish from list_collections/rename_collection beyond the verb.

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 parenthetical 'create_note and move_note make one too when given a new name' is effectively a when-not-to-use note, steering the agent away from this tool when the collection is a byproduct of creating a note. No explicit prerequisites or exclusions beyond that, but the context is clear.

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

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

With no annotations, the description carries the full burden. It discloses useful defaults (a status column without options gets To do/In progress/Done) and side effects (unique:true makes upsert_rows match and keeps duplicates out), but says nothing about permissions/scope, what happens on a duplicate column name, or what is returned on success.

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 purpose followed by dense, high-value semantics for the non-obvious parameters; almost every clause earns its place. The middle section is a run-on that chains several rules into one sentence, slightly hurting scanability.

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?

Covers creation input thoroughly, which is the hard part. However, with no output schema and no statement of what is returned (e.g. table id/URL), an agent that needs the new table's identity to call add_column or add_rows afterwards is left guessing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 33% (only workspace is described in-schema), so the description must compensate, and it does: it spells out the columns object shape, enumerates all eleven type values, explains the conditional requirement that options lists choices for select/multi/status, and defines unique's matching semantics. The top-level `name` argument is still 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?

Opens with a specific verb+resource ('Make a data table') and immediately narrows the resource with column/type semantics, so an agent can distinguish it from add_column, add_rows and query_rows. It never names a sibling explicitly, so differentiation is inferred 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?

Usage is implied by the resource ('create a table' before adding columns/rows), and the unique-column note hints at the upsert_rows follow-up. But there is no explicit guidance on when to use this versus add_column/get_data_table/list_data_tables, nor any stated prerequisite 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 full burden and does well: it discloses the side effect of emailing invitees, the agent-context restriction that blocks it, the 20-attendee cap, the 30-minute default, and the Meet-link side effect. It stops short of stating calendar-permission requirements or what happens on conflict/invalid timezone.

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 and front-loaded — the core action leads, then format rules, then the constraint, then the return. Semicolon-chained clauses make it slightly run-on, but nearly every clause carries non-redundant 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?

For a 6-parameter mutation with no annotations and no output schema, the description covers the action, key parameter formats, a hard restriction, and the return value. Missing only edge-case behavior (missing primary calendar, invalid timezone, attendee failure) which keeps it from being complete.

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 33%, yet the description compensates: it gives the ISO date-time format with a concrete example for start, explains the end-vs-minutes tradeoff with the default, and documents attendees as emails capped at 20. Only title is left unstated, which is self-evident.

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: 'Create an event on the user's primary Google calendar.' An agent can distinguish this from list_events/update_event/delete_event, though no sibling is named explicitly to route away from create_booking_link or find_free_time.

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 one concrete exclusion ('from an agent's own turn inside Caddie that's refused' for attendees) and a defaulting rule ('give end or minutes (default 30)'), but gives no guidance on when to prefer create_booking_link or find_free_time, or what to do when the agent needs to invite guests.

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 present, the description carries the full behavioral burden and does well: it states the resource is 'Always personal' and discloses the concrete Caddie defaults (habit: 30 minutes at 07:00 on weekdays; routine: 45 minutes at 12:30 every day). It does not cover permissions, duplicate handling, or side effects, so it falls short of complete.

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 dense sentences that front-load the two kinds before adding the disambiguation and defaults. The parentheticals earn their place, though the sentence is slightly packed and could be split for easier scanning.

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 5-parameter mutation tool with no annotations and no output schema, the description covers semantics, defaults, the personal-only constraint, and sibling disambiguation. Error or duplicate behavior is absent, but the major calling context is present.

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 already 80%, so the schema documents most parameters. The description adds genuine meaning beyond the schema by tying specific default values to kind (default minutes, times, and days per habit/routine), which the schema only partially captures via 'default habit'.

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

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

The description opens with a specific verb and resource ('Add a habit… or a routine') and immediately defines what each kind is: a habit is ticked off with a streak, a routine is planned calendar time. It also disambiguates from the sibling create_routine by calling out that agent routines are handled separately.

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

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

The description gives clear context for choosing between the two kinds and explicitly routes agent-routine creation to create_routine. It lacks explicit exclusions against update_habit or update_routine, but for a creation tool the distinction is well 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the default team (first team) and the notable assignee-refusal behavior inside Caddie agent turns, which is valuable context. However, it omits permissions, reversibility/idempotency, rate limits, and what the response contains.

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?

One front-loaded paragraph leads with purpose before parameter details, with no filler sentences. The dense parentheticals and long sentence slightly reduce readability but the content is efficiently sized.

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, it covers the core creation action and key parameter semantics. It does not state that title is required or what the tool returns (e.g., issue ID or URL), leaving the agent to infer result handling.

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 only 20%, so the description must compensate; it does for three of five parameters. It explains team format and defaulting, assignee name/email plus refusal context, and maps human priority labels to Linear's 0–4 scale. The title and description parameters remain undocumented in both places, though title is self-evident and body content is straightforward.

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 ('issue in the user's Linear'), plus integration context ('Caddie's Linear connection'). The creation action distinguishes it implicitly from siblings like linear_update_issue and linear_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?

Implies use when creating a Linear issue but never states when to prefer linear_update_issue or linear_query, nor any when-not-to-use conditions. The assignee caveat is a conditional behavior, not alternative routing guidance.

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

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

With no annotations, the description carries the full burden. It usefully discloses non-obvious rendering behavior (Markdown subset, checklist conversion, and that checklists are NOT To-dos), which is real value. However it omits permissions, duplicate-title behavior, and never states what the call returns — the id is only implied by 'this note's id', which matters for chaining into create_task.

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 tight sentences, front-loaded with the core action, then format semantics, then the To-do routing rule. Every sentence carries information; the only mild bloat is the mixed audience of formatting and cross-tool routing in one paragraph.

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 4-parameter write tool with no annotations and no output schema, the description covers format and To-do routing but leaves the agent guessing about the return value (needed to link via create_task) and about behavior when the same title already exists. Adequate but with clear 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 50%: workspace and collection are documented in the schema, but title has no description anywhere. The description compensates well for content by spelling out the Markdown semantics and checklist behavior, but adds nothing for title or the workspace/collection selection logic beyond what the schema already says. Baseline 3 fits.

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

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

The description opens with a specific verb and resource ('Create a note in Caddie') and immediately distinguishes the tool from create_task for the To-do case. It does not distinguish itself from append_to_note, update_note, or note_from_template, which share the note-creation space, so sibling differentiation is only partial.

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 routing rule: '- [ ]' lines are checklist items in the note, and to give the user a real To-do use create_task with note: <id>. It also says where to put decisions ('in your reply'). It stops short of covering append_to_note vs create_note vs note_from_template, so it is not a full when/when-not map.

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 load and does disclose the single most non-obvious behavior: omitting a date silently files the task in the Inbox rather than erroring. It also discloses the Linear-sync side effect and team-workspace scoping for assignee. It does not state permissions, failure modes, or that creation is not idempotent, keeping it below 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 the default routing rule before the optional-field enumeration. The trailing optional-field list is a long comma chain that duplicates schema content, but nothing is wasted overall.

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 13-parameter create tool with no annotations and no output schema, the description covers the core routing semantics but says nothing about the created task being returned (id, fields) or about how workspace scoping interacts with note/linear linking. Adequate but leaves gaps an agent will hit in practice.

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 69%, so the schema does most of the work, and the description adds real value on date format (YYYY-MM-DD, optional HH:MM). But it omits minutes (default 30), workspace selection, add_subtasks, and the interaction between date and list beyond the parenthetical.

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?

Opens with a specific verb+resource ("Add a task") and immediately qualifies the two routing outcomes (Inbox vs. planned day). This distinguishes it from update_task and create_event without naming them, though no sibling is called 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?

The date/no-date branch implicitly tells the agent which variant to use, and the assignee clause scopes team-workspace use. However, there is no explicit "use update_task to modify an existing task" or "use create_event for calendar blocks" guidance, so alternative selection is left 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?

No annotations are provided, so the description carries the full burden and does well: it discloses that processing happens on the user's Mac (Caddie must be running) and that the call is asynchronous — an id is returned before the transcript and notes exist. It omits failure modes (no captions available), duplicate-note behavior, and permission requirements.

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 purpose is front-loaded and the return contract is stated in a second sentence with no filler. The first sentence is dense but every clause (sources, Mac locality, Caddie equivalence, outputs produced) 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 no output schema and no annotations, the description supplies the return semantics (note id, or 'being made') and the async caveat, which is what an agent most needs. It stops short of covering what happens when transcription fails or when the workspace isn't open in Caddie.

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 schema already documents url formats, workspace defaults and collection defaults in detail. The description adds only the Mac/Caddie locality constraint, which the schema's workspace field already states, so it adds little 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 and resource ('Make a video note') and names the exact accepted sources (YouTube video, X post with video). The 'as pasting the link in Caddie does' analogy pins the behavior to a known user workflow, clearly separating it from the generic create_note sibling.

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 makes clear this is for video links and that it runs on the user's Mac, which is the operative precondition. It does not explicitly exclude non-video links or point at create_note/get_transcript as alternatives, so routing is implied rather than spelled out.

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 load and does so: it discloses refusal behavior (entries the user marked wrong or deleted are refused, including near-duplicates by text/email/handle/number), rate limits (20/hour per task, 20/hour externally, 60/hour per log overall), and attribution (external writes are logged as the user's via this client). These are non-obvious behavioral traits an agent cannot get from 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?

Front-loaded with the purpose and every clause carries real information, but the parameter rules, refusal policy, and rate limits are crammed into one undifferentiated paragraph, making the constraints harder to scan than they need to be.

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 8-parameter, annotation-free mutation tool with no output schema, the description covers qualification rules, field limits, refusal policy, attribution, and throttling. The only real gap is that it never says what a successful write returns (e.g., the new entry's id), which matters because replaces depends on ids.

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 38%, but the description compensates for essentially every parameter: character ceilings for decision (200) and why (300), cardinality and format for about (1–4 short names), the meaning of each evidence enum value, the purpose of rejected, and how from vs agent split inside/outside Caddie. This is meaning well beyond the bare schema types.

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 ("write down a real choice right after you make it") plus a concrete enumeration of qualifying decisions (identity on an account, which match was picked, which channel, a user default) and explicit exclusions ("not narration of steps"). An agent can tell this apart from note-taking siblings, though the boundary against memory_update/skill_save is never drawn.

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 timing ("right after you make it") and an explicit negative rule ("not a choice the request already made for you"), which is stronger than most definitions offer. It does not name an alternative tool for the cases it rejects, so the agent must infer where narration or facts belong.

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 burden and mostly does: it discloses result ordering (newest first), a hard cap (20 at most), and the semantic content of each line. It also implies read-only behavior by routing mutations to decision_log. It does not state permission/auth requirements or what an empty result means, so it stops short of full disclosure.

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 comes first, then usage, then per-parameter notes, and no sentence is filler. It is dense with nested parentheticals and second-person asides, which makes it slower to parse than it needs to be, but the information density justifies the length.

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 annotations, no output schema, and 50% schema coverage, the description supplies the missing pieces: entry shape, ordering, cap, and the read-vs-write split against decision_log. It leaves open whether results are text or structured and how about matching works, minor gaps for a zero-required-parameter read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All four parameters get meaning beyond the schema: about is "words for the people, accounts or topics ("Anupama Slack")" with a documented default ("without it, the newest"), from is tied to the caller's "agent:task:key", agent is the outside-Caddie substitute, and include_replaced is "the ones a later decision overrode too". The gap is that about's matching semantics (substring vs. full-text, multi-word behavior) are left unstated.

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 resource ("its Decisions log"), describes the shape of each entry, and constrains scope ("newest first, 20 at most"). It also names the sibling decision_log as the write/replace counterpart, so the agent can separate read from write. The verb itself is only implied ("Read it before you choose..."), which keeps this 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?

It gives an explicit trigger ("Read it before you choose a recipient, an account, a channel or an approach that may have been settled already"), an explicit behavior to take ("follow what's there instead of searching again"), and an explicit alternative when the data is stale ("replace it with decision_log if it's wrong now"). When-to-use, what-to-do, and the competing tool are all 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?

With zero annotations the description carries the full burden, and it does: irreversibility, the exact blast radius (links break, existing bookings persist), the user-consent requirement, and an execution-context refusal case. That is precisely the behavioral disclosure an agent needs before a destructive call.

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 dense sentences, front-loaded with the irreversible effect and its consequence before the routing and restriction clauses. The telegraphic style ('Only when the user asked') trades grammar for speed without losing meaning.

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 destructive tool with no output schema, everything needed is present: destructive semantics, consent gate, sibling alternative, discovery tool for the identifier, and a refusal condition. Nothing an agent must know before calling 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% and the single 'link' parameter already documents that a title, slug, or URL is accepted plus a pointer to list_booking_links. The description adds nothing parameter-specific beyond implying identity lookup, 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 ('Delete ... booking links') and immediately defines the material consequence: 'its address stops working (bookings already made stay on the calendar).' That parenthetical alone separates it from every other booking-link sibling, and disable_booking_link is named as the non-destructive counterpart.

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

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

Gives an explicit precondition ('Only when the user asked'), names the alternative and why to prefer it ('disable_booking_link can be undone'), and adds a hard exclusion ('From an agent's own turn inside Caddie it's refused'). No inference required about when to reach for this versus the reversible sibling.

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 at all, the description carries the full burden and does disclose the key side effect: contained notes migrate to their next collection or the Inbox, so nothing is lost. It does not state whether the collection deletion itself is permanent/undoable, whether nested collections or settings are affected, or what authorization is required, which are meaningful gaps for a destructive 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 and dense: the core behavior and its most important caveat appear in the first clause, and the consent rule closes it. The parenthetical '(as Delete collection in Caddie)' is slightly awkward phrasing but conveys a useful cross-reference and does not bloat the text.

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 destructive tool with no annotations and no output schema, the description covers the two things an agent most needs: notes are preserved and user intent is required. Missing pieces — permanence/undo, workspace defaults, and error behavior — are modest but real, keeping it from a 5.

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 50%: `workspace` is well documented in the schema, while `name` has no description anywhere. The description adds no parameter guidance of its own (e.g., whether `name` is a display name, id, or both), so it neither compensates for the gap nor adds meaning 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?

States a specific verb and resource ('Delete a collection') and immediately distinguishes the act from sibling delete_note by clarifying that notes are not deleted but reassigned. An agent can tell exactly what this removes versus what survives 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?

'Only when the user asked to' gives an explicit precondition that excludes speculative or proactive deletions, which is valuable for a destructive tool. It stops short of naming alternatives (e.g., rename_collection, move_note) or saying what to do if the user only wants to empty a collection, so it is clear but not complete 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 burden and discloses important behavior: deletion cannot be undone from Caddie and agent-initiated deletion is refused. It does not cover return values or authentication details, but the critical safety profile is present.

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

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

Three short sentences, front-loaded with purpose. The safety warning and caller restriction are compact and useful; 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?

For a simple delete tool with no annotations and no output schema, the description covers the main risks, source of parameters, and caller restriction. It could say more about optional account_id or post-delete behavior, but nothing essential 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 0%, so the description must compensate. It names all three parameters and points the agent to list_events as the source, which is useful, but it does not clarify that account_id is optional or explain expected identifier formats.

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: "Delete a Google Calendar event." It also ties the parameters to list_events, making it clearly distinct from list_events and update_event.

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 says only delete when the user asked to, and that deletion from an agent's own turn inside Caddie is refused. That gives clear when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description carries the full load and does disclose the key behavioral trait: deletion is soft, retained 30 days server-side, and recoverable. It still omits what happens to associated habit logs/streaks and whether any permission is required, but the retention semantics are a substantive disclosure.

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, front-loaded with the action and followed by the recovery window, then the usage guard. No filler; every clause 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?

A destructive tool with no annotations and no output schema needs to cover reversibility (it does) plus the parameter and downstream effects. The undocumented 'id' and unstated effect on habit history leave it only minimally complete.

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 0% for the single required parameter 'id', and the description says nothing about it — not whether it is the habit id vs. routine id, nor its format. The description does not compensate for the documentation 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?

States a specific verb (delete) and resource (habit), so an agent can identify the operation. However, 'or routine' muddies the boundary against the sibling delete_routine, leaving some ambiguity about which tool owns routine deletion.

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?

'Only when the user asked to' gives a real gating condition for use, which is more than most tools offer. But it never names the alternative (delete_routine for routines, update_habit or log_habit for other habit operations), so the sibling overlap is left unresolved.

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 soft deletion with 30-day server retention and that child tasks survive the delete, both non-obvious side effects. It omits permissions/authorization requirements, idempotency, and behavior when the id does not exist.

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, zero filler, with the core action stated first and the safety constraint 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?

A mutation tool with no annotations and no output schema is adequately covered on retention and cascade behavior, but leaves the required id parameter undocumented and doesn't state what a successful delete returns or what errors look like. Enough to call it, not enough to call it confidently.

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 50%: the workspace parameter is well documented in the schema, but 'id' has no description anywhere. The tool description adds nothing about the id's type, format, or where to obtain it, so it fails to compensate for the coverage 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?

States a specific verb+resource ('Delete a note') in the first sentence, immediately distinguishing it from append_to_note, update_note, and move_note. It does not name the obvious counterpart restore_note, so sibling differentiation is only partial.

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?

'Only delete when the user asked to' is an explicit gating condition that prevents unrequested destructive actions. It stops short of naming alternatives (restore_note for undoing, archive-style flows), so it sits at clear-context rather than full when/when-not/alternatives.

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

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

With no annotations, the description carries the full burden and does real work: it discloses irreversibility, a permission rule that causes refusal in a specific context, and the recoverable alternative. It does not say whether related history/run logs are also destroyed or whether any confirmation step is required, so it falls short of 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 short sentences, each carrying distinct information: what it does, who may trigger it, and what to do instead. Destructive semantics and the alternative are front-loaded with 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 destructive mutation with no annotations and no output schema, the description covers irreversibility, caller restriction, and the recommended alternative. The remaining gap is parameter-level: the unexplained 'agent' field and the absence of routine identifier format guidance.

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 0%, so the description must document both parameters. The '(list_routines)' hint implies where to obtain the routine identifier, but the required 'routine' parameter's accepted format is never stated, and the 'agent' parameter is entirely unaddressed in both schema and description.

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

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

Specific verb (delete) plus resource (routines) with an explicit permanence qualifier ('for good'). It also distinguishes itself from the reversible sibling pause_routine, so an agent can tell the two apart 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?

States a hard precondition ('Only when the user asked'), names the safer alternative (pause_routine, which 'can be undone'), and gives a concrete when-not case ('From an agent's own turn inside Caddie it's refused'). This is explicit when/when-not/alternative guidance.

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

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

With no annotations, the description carries the full burden. It does disclose the key trait that deletion is recoverable via the table's History in Caddie, which is genuinely useful. But it omits whether unknown ids error or are silently skipped, whether partial deletion is possible, any cap on the id list, and what the call returns — gaps that matter for a destructive 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?

Three short sentences with the destructive action and its reversibility front-loaded, and no filler. Each sentence contributes a distinct fact (what, recoverability, permission gate).

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 3-param destructive tool with no annotations and no output schema, the description covers the essentials of intent and reversibility but leaves return behavior and edge-case handling unexplained. It is adequate rather than complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%: table and workspace are already documented in-schema with cross-references to list_data_tables and list_workspaces. The description adds only "by id" on top, saying nothing about the format of ids, array size limits, or the consequence of a workspace/table mismatch. Baseline 3 fits given the schema does most of the work.

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?

"Delete rows by id" states a specific verb and resource, and the id-based scope distinguishes it from add_rows/update_rows/upsert_rows by action. It is clear without the schema, though it does not explicitly name the sibling alternatives.

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?

"Only delete when the user asked to" is a genuine invocation gate, so there is real guidance about when it is appropriate. However, there is no mention of when to prefer update_rows or how to handle a request to remove a subset of columns/values, leaving the alternative-selection reasoning implicit.

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 disclose the crucial behavioral fact: deletion is soft, retained 30 days server-side, and recoverable. It stops short of stating permission requirements, idempotency for a nonexistent id, or what happens to subtasks/recurrences tied to the task.

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, with the recoverability fact and the alternative-use case both front-loaded rather than buried.

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 2-parameter destructive tool with no annotations and no output schema, the description covers the essentials an agent needs: what it destroys, that it is reversible for 30 days, and when not to use it. Missing only permission/edge-case behavior and a note on the id's origin.

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 50%: the workspace parameter is well documented in the schema, while id is undocumented but self-evident as the target task identifier. The description adds no parameter guidance of its own, so the schema does nearly all the work — baseline 3 is appropriate at this coverage level.

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 ('Delete a task') and immediately clarifies a key property of the deletion. It also explicitly names the sibling it is often confused with (update_task) so an agent can distinguish the two 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?

It gives an explicit when-not with the exact alternative: to finish a task, use update_task with done: true. That is the single most likely mis-invocation for a delete tool, and the description routes the agent away from it with a concrete call shape.

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 and does meaningful work: it discloses that the effect is reversible and that existing bookings are unaffected. It does not mention permission requirements or whether the response confirms the new state, 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?

One sentence, front-loaded with the action, and every clause (reversibility, effect on existing bookings) adds information. Nothing is wasted or 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?

For a single-parameter, no-output-schema mutation tool, the description covers the action, its reversibility, and its side effects on existing data. The only gap is that it says nothing about what is returned or required authorization, minor given the tool's simplicity.

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 schema itself explains that 'link' accepts a title, slug, or URL and points to list_booking_links. The description adds nothing about the parameter 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 ('Turn ... off') and resource ('booking links'), and immediately clarifies the effect: no new bookings, existing bookings preserved. That phrase alone distinguishes it from delete_booking_link and update_booking_link without the agent needing to open 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?

The clause 'until it's turned back on (bookings already made stay)' implicitly routes the agent here instead of delete_booking_link for reversible takedowns, and instead of update_booking_link when the goal is to stop bookings entirely. It doesn't name those siblings explicitly, 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 zero annotations the description carries the full burden and does substantial work: it defines which events count (not declined, not marked Free), that tasks and habits also block, the time zone used, the return format, and the important edge case that a Busy all-day event leaves no free time. It never explicitly states the tool is read-only and has no side effects, which is the remaining gap.

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 dense sentences, front-loaded with the core operation and followed by return format and the key edge case; nothing is padding. The parenthetical '(default today; from now on, if today)' is syntactically awkward and costs a re-read, which keeps it off a 5.

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 describing the return as HH:MM-HH:MM slots plus what's busy. For a three-param, all-optional read tool with no annotations, the remaining gap is minor: no explicit statement of side-effect freedom or how overlapping tasks/habits are resolved when they conflict.

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 a baseline of 3 applies, but the description genuinely adds meaning: the date defaults to today and, when it is today, the window starts from now; and the 'minutes' threshold is tied to slot length ('at least minutes long'). The 'between' parameter is only implicitly referenced via the schema's 09:00-18:00 default.

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 computation — free slots on a day, derived from calendar events, planned tasks and habits — which is far more than a restatement of the name. It does not, however, distinguish itself from plausible siblings like plan_day or list_events, so an agent must infer where the boundary lies.

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

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

Usage is implied by the framing ('free time on a day', default today, from-now-on semantics for today) and the eligibility rule for events is spelled out. But there is no explicit when-to-use/when-not or pointer to an alternative tool for scheduling, listing events, or checking a specific meeting.

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 well: it says only the row's state changes, nothing is run, sent, or paid, and it explains payment-related restrictions. It does not cover permissions or failure behavior, but it is substantially transparent 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?

The definition is dense but front-loaded, beginning with the core purpose and action semantics before adding constraints. It contains little waste, though the single-paragraph structure could be clearer for a multi-action mutation.

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 complex mutation with no annotations and no output schema, the description gives a strong picture of what changes, what does not, and when the tool applies. It still leaves the note parameter and any return behavior unspecified, which keeps it short of fully complete.

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 low at 25%, and the description adds real meaning for row and action, including the source of the row id and when each action applies. However, the required note parameter is not explained, and workspace is only covered by 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 states a specific verb and resource: settling one Get it done row on a call note. It distinguishes the tool from followups_list by saying the row id comes from that list, and the three actions are clearly scoped.

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 explicit usage conditions such as 'Only when the user said so, or it's plainly done' and constraints for payment rows. It also points to followups_list as the source for the row id, though it does not name an alternative tool for the same action.

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 declares the tool read-only, describes default scoping to the last 14 days, lists returned fields, maps status semantics, and explains workspace defaults. It does not mention pagination, sort order, or row limits, but the core behavioral profile is 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?

The description is information-dense and front-loads the main purpose, but it is a single convoluted paragraph with heavy parentheticals and semicolons. It remains readable but could be structured more cleanly.

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?

No output schema exists, so the description appropriately explains returned row fields and state values. It covers the essential filter defaults and read-only nature, leaving only minor operational details such as pagination or sort order 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 only 50%, but the description compensates by explaining all four parameters: note, workspace, status, and mine. It adds meaning for status values beyond the enum and clarifies default scoping, though 'mine' gets only a brief gloss.

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 — a call's 'Get it done' follow-up rows — and clearly distinguishes the two modes: with a note vs. without a note across recent calls. It also explicitly differentiates itself from followup_act, which changes 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?

Explains the conditional behavior of using note vs. omitting note, gives default status behavior, and names followup_act as the alternative for mutations. An agent can select this tool and know when not to use it for state changes.

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 disclose the return payload in useful detail (column metadata, row count, exactly 5 sample rows), which is the key behavioral fact since there is no output schema. It never states this is a read-only operation or discusses permissions/cross-workspace visibility, so it falls short of fully self-describing.

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 return contents are front-loaded in a compact parenthetical, followed by the actionable precondition. No filler or restatement of the tool name.

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?

No output schema exists, and the description compensates by specifying precisely what comes back, including the sample-row cap of 5. Parameters are fully documented in-schema, so nothing an agent needs to call this 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% and both parameters (table, workspace) already document themselves including the list_workspaces/list_data_tables pointers, so baseline 3 applies. The description adds no additional meaning about parameter usage or format beyond what the schema provides.

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 resource (a data table) and enumerates exactly what is returned: columns with name/type/select options/unique flag/row-title flag, plus row count and 5 sample rows. That is materially more specific than the name alone. It stops short of naming sibling tools like query_rows or list_data_tables, so an agent must infer the boundary from the 'sample rows' framing.

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?

'Read this before adding or changing rows so values fit the columns' gives an explicit usage trigger tied to the write tools (add_rows, update_rows, upsert_rows). It does not state when not to use it, e.g. when to reach for query_rows to actually read full row data instead of the 5-row sample.

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 two real traits: the operation is a read (non-destructive) and the return is plain text rather than rich formatting. It omits what happens when the id does not exist or the caller lacks access to the referenced workspace, and gives no sense of note size or truncation.

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?

One short sentence, no filler, and the plain-text return format is front-loaded alongside the core action. It is efficiently sized; the remaining gaps are omissions the other dimensions penalize rather than verbosity here.

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?

A two-parameter retrieval tool with no annotations and no output schema needs the description to compensate for the undocumented id parameter and to explain error behavior and workspace scoping. The description only covers the action and output medium, leaving an agent to guess at id format and failure modes.

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 50%: the workspace parameter is well-documented in the schema, but id is a bare string with no description anywhere. The description says nothing about either parameter — not the id format, not whether workspace must match the workspace the note was found in.

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: 'Read one Caddie note in full (as plain text)'. An agent can tell it retrieves a single note by id rather than listing or searching. It does not explicitly name siblings like search_notes or get_transcript, so sibling differentiation is only implied.

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?

There is no when-to-use guidance, no mention of search_notes as the way to obtain an id first, and no condition under which this tool should be preferred over search_notes or get_transcript. 'One ... in full' hints at single-item retrieval, but that is inference rather than stated guidance.

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 shape (speaker attribution and offsets from the start of the call/video) plus a behavioral difference between the two note types. It omits pagination/truncation behavior, what happens when a note has no transcript, and the access requirements implied by the workspace parameter.

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 no filler, and the core action is front-loaded. The parallel parenthetical construction ("...or a video note's (what's said...)") is slightly dense to parse but earns its space by distinguishing the two cases.

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 read tool with no output schema or annotations, the description covers what is returned and the two note types, which is the essential part. It still leaves gaps around id semantics, empty-transcript behavior, and result size, so it is adequate rather than complete.

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 50%: the workspace parameter is documented in the schema, but `id` has no schema description. The description only indirectly implies `id` is a meeting-note or video-note id, without saying so explicitly or clarifying whether it accepts a note id versus a meeting id.

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 ... transcript") and covers both variants it handles: meeting notes and video notes. It is clear what the tool returns, though it never names the sibling it competes with (search_transcripts) so an agent must infer that this one fetches a full transcript by id rather than searching.

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

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

Usage is only implied: you call it when you have a meeting or video note and want its transcript. There is no explicit statement of when to prefer this over search_transcripts or get_note, and no prerequisites (e.g. the note must exist and have a transcript) are 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?

With no annotations, the description carries the full burden, and it does well: it discloses that results are curated tips with attribution, evidence (numbers, test results) and a link to the moment said. It does not state read-only status explicitly, rate limits, or pagination, but "Search" plus the citation requirement gives the agent a clear operational contract.

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 resource and sources, then query semantics, then usage. It is dense and runs long in the first two sentences, but almost every clause carries actionable information, so there is little 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?

No output schema exists, and the description fills that gap by describing the shape of each tip (who said it, evidence, link) and instructing the agent to cite links. Missing only edge-case behavior such as empty results or how many tips come back per query beyond the schema's limit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, and the description compensates by explaining that queries takes up to 6 keyword searches with worked examples ("paywall annual plan anchoring", "trial length") and that show narrows to a single source. The limit parameter is left to the schema, which already documents its default and max.

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?

Opens with a specific verb and resource ("Search Caddie's product and growth library") and immediately names the exact sources covered (Lenny's Podcast, Subversive, Superwall, Sub Club, abtest.design). That source list and topic list distinguish it unambiguously from siblings like search_notes or search_transcripts, which search the user's own content.

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 use cases: advising on product and growth, and auditing a screen, flow or page, pointing to the audit_screen prompt for the latter. It does not name sibling tools it should be preferred over (e.g. search_notes), but the domain-specific framing makes the choice clear in practice.

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 does so well: it discloses the join-link mechanism, the 14-day validity, the default role, the permission model, the confirmed-email requirement, and the 50-per-day rate limit. It also clearly states that calls from an agent's own turn are refused.

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 organized: purpose, role values, permissions and rate limit, then usage restriction and refusal behavior. Every sentence contributes operational information, and the main purpose is front-loaded.

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

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

For a no-annotation, no-output-schema mutation tool, this is nearly complete: it covers permissions, rate limits, invitation validity, role defaults, and refusal behavior. The main missing detail is the expected workspace identifier format and whether any success response or invitation status is returned.

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 0%, so the description must compensate. It explains the role parameter's enum values and default, and clarifies that invitation is by email to a workspace. It does not fully specify the expected format or source of the workspace parameter, which leaves a small 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 states a specific verb and resource: invite someone to a team workspace by email. It also clarifies the invitation mechanism (Caddie emails a join link) and role options, so an agent can distinguish this from related tools like list_members or set_agent_access.

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 explicit usage constraints: only when the user asked for this person to be invited, only from a confirmed email address, and only by a workspace owner or admin. It also states a hard refusal condition for an agent's own turn and directs the agent to ask the user instead.

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 disclose what an agent would otherwise have to guess: read-only semantics, the 92-day cap on ranges, that empty days are omitted from results, and that each day comes with text plus a one-line summary. It stops short of stating permission requirements or error behavior for malformed ranges.

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?

One sentence, no filler, and the most important facts (personal scope, read, two modes) come first. The deeply nested parentheses around the range parameters make it slightly dense to parse but nothing 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?

For a 3-param, no-output-schema read tool this covers nearly everything: defaults, format, range limit, return shape, and empty-day handling. The remaining gap is precedence when multiple date parameters are combined, which an agent would have to discover by experiment.

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: 'date' is documented with a default of today, 'from'/'to' are documented with YYYY-MM-DD format and a 92-day maximum. It does not say what happens if 'date' and 'from'/'to' are supplied together, which leaves one real ambiguity for a 3-param tool.

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?

Opens with a specific verb and resource ('Read the user's journal') and immediately scopes it as 'always personal', which separates it from workspace-scoped siblings and from the writing counterpart journal_write. It never names a sibling explicitly, so the differentiation is implicit rather than spelled out.

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 modes (single day vs. date range) imply when each applies, and 'default today' gives a sane fallback, but the description never states when to prefer a range over a single day or when to use journal_write instead of reading. 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.

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

With no annotations, the description carries the full burden and does the most important part: it discloses that mode=replace overwrites the day's entire text, which is the one piece of destructive behavior an agent must know before calling. It also gives the append-vs-replace default. It doesn't say whether a missing day is created implicitly (relevant to the 'default today' claim) or what the call returns, leaving a modest gap.

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 scope and gating, then the overwrite semantics. Every clause carries a fact an agent would otherwise have to guess; 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 three-parameter write tool with no annotations and no output schema, the description supplies the decision gate, the default values, and the destructive-replace warning. It is nearly complete; only the implicit day creation and the date format remain 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 0%, so the description must compensate, and it does: date is explained as defaulting to today, mode is given as append-by-default versus replace-overwrites, and text is Markdown matching create_note. The only shortfall is that the date string format is never specified.

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 — writing to the user's journal for a given day — and immediately delimits it against the sibling journal_read and against create_note, which is used only as a format reference. An agent can distinguish this from create_note or append_to_note 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?

"Only when the user asked you to write in their journal" is an explicit gating condition that excludes proactive writes, which is exactly the kind of guidance an agent needs. It stops short of naming the near-miss alternatives (create_note, append_to_note, journal_read) as the tools to prefer when it isn't a journal write.

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 does real work: it discloses the identity the comment is posted under (the user's Linear connection), the Markdown format, and the key side effect that subscribers are notified. It stops short of covering permissions, editability/deletability, or failure 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?

Three compact sentences, front-loaded with the action, then the parameter detail, then the behavioral constraint. No filler and nothing buried.

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 write tool with no annotations and no output schema, the description covers action, identity, format, ID format, and the notification side effect. Only error/permission behavior is absent, which is a minor 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 0%, so the description must compensate. It does clarify the `issue` parameter precisely ('its key ("ENG-123")') and hints at `body` being Markdown, but says nothing about body length limits, mentions, or whether the issue key must be from a specific team.

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 ('Comment on a Linear issue') plus who the action is attributed to ('as the user') and the body format ('Markdown'). The action is intrinsically distinct from create_linear_issue and linear_update_issue, but the description never names those siblings to make the boundary explicit.

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

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

Usage is implied by 'only what the user would say there' — i.e. this is a public, attributable action — but there is no explicit when-to-use/when-not rule and no routing to alternatives such as linear_update_issue for editing the issue 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?

Lacking annotations, the description must carry the burden. It clarifies the specific attributes returned (number, start and end dates, progress) which provides necessary context about the data the tool delivers, even if not explicitly stated 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?

The definition is highly concise, packing all essential information—the resource, the scope, the parameter definition, and the default setting—into a single, efficient 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?

Given the simplicity of the schema (one optional string parameter) and the lack of annotations, the description is perfectly complete. It allows an agent to understand exactly what the tool returns and how to use the single input parameter.

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?

While the schema defines 'team' as a string, the description provides vital semantic context by explaining the format of the key ('like ONC2') and the default behavior of the parameter when it is not provided ('default: all teams').

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

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

The description clearly identifies the resource ('Linear cycles (sprints)') and specifies the precise scope of the operation: retrieving the 'previous, current and next one per team.' This is highly distinct from other listing or querying tools.

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 provides guidance on how to use the 'team' parameter, specifically noting that omitting it will default to retrieving cycles for 'all teams.' This helps the agent decide whether to include the parameter based on the user's intent.

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 reasonably well: 'Read' signals a safe, non-mutating operation, ordering ('newest activity first') is disclosed, and the return shape is listed. It omits pagination/truncation behavior beyond the schema's limit field and any auth or connection-state caveats.

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 core verb and ordering, then filters, then return fields. No filler; each clause conveys usable 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 no output schema, the description usefully enumerates returned fields (id, title, state, assignee, priority, due date, cycle, project, url), which is what an agent needs. The remaining gap is routing relative to sibling Linear tools, which is unaddressed.

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 17% (only limit is documented), yet the description compensates thoroughly: it explains the team key format (ONC2), that assignee accepts 'me', a name, or an email, the five state values plus named states like 'In Review', and the cycle enum meaning. This adds real semantics 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?

States a specific verb and resource ('Read issues from the user's Linear') plus ordering ('newest activity first'). However, it never distinguishes itself from sibling tools like linear_query, linear_cycles, or create_linear_issue, leaving the agent to guess which Linear tool to pick.

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?

Enumerates that all filters are optional and what each filter accepts, which implies the listing/searching use case. But there is no explicit when-to-use guidance or exclusion versus the nearby linear_query and linear_cycles tools, which is exactly where confusion is likely.

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 load and does disclose the key behavioral trait that this is read-only and mutations are refused, plus that it authenticates through Caddie's Linear connection. It says nothing about rate limits, pagination, error behavior, or what shape results come back in — significant for an arbitrary GraphQL passthrough.

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?

One front-loaded sentence with the core purpose first, the scope boundary second, and the example parenthetical last. The inline example is long but earns its space by demonstrating the query format; nothing is redundant.

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 GraphQL passthrough with no output schema and no annotations, the description should say more about response shape and how `variables` binds to the query. It covers the query param and the read-only constraint well, but leaves the caller guessing on variables and return values.

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. The embedded `issue(id: "ONC2-123") { title description comments { nodes { body user { name } } } }` example usefully conveys that `query` takes raw GraphQL syntax including nested selections. The `variables` parameter, a nested object, is never mentioned at all, leaving half the inputs undocumented.

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 — 'Run any read-only Linear GraphQL query' — and immediately scopes it against the sibling tools linear_issues and linear_cycles, naming the resource families (projects, comments, labels) those don't cover. An agent can distinguish this from the structured Linear siblings 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?

Provides a clear routing rule: use this for what linear_issues and linear_cycles don't cover, plus a concrete example (single issue by id). It also states the exclusion 'Mutations are refused.' It doesn't mention the other Linear siblings (linear_comment, linear_update_issue) that could be confused with this escape hatch, so not quite 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 whole burden, and it discloses three things an agent could not otherwise know: this is a partial/patch update, state and assignee changes trigger notifications, and such changes are refused during an agent's own turn. It omits permission requirements, reversibility, and the response shape, which keeps it below 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 action and resource, and every clause carries information. The field list is a single comma-spliced run-on that is harder to scan than a separated list would be, which costs a point despite there being 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 5-parameter mutation with no annotations and no output schema, the description covers field formats, patch semantics, side effects, and the refusal path. It does not say what the tool returns or how a failed/refused call surfaces, leaving a small 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 description coverage is 0%, so the description must compensate, and it does: state is a workflow state name scoped to its team with examples, assignee accepts a name/email in its team, "me", or "none" to unassign, priority accepts the named levels or 0-4, and issue is the key format ("ENG-123"). These are effectively enumeration values the schema lacks entirely.

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?

Opens with a specific verb and resource ("Change a Linear issue through the user's Linear connection") and immediately enumerates the mutable fields, which cleanly separates it from siblings like create_linear_issue, linear_comment, and linear_issues. An agent can identify the tool's job 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?

States the update is partial ("Only what you give changes") and gives an explicit refusal condition with the required alternative: from an agent's own turn inside Caddie, state/assignee changes are refused, so "ask the user." That is genuine when-not guidance. It stops short of naming sibling tools for reading or bulk issue operations, so it is not a full routing statement.

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 helpfully discloses the partial-result shape { agents, partial: true, note } when there are too many agents, but it does not explicitly state read-only semantics, permission needs, or pagination behavior beyond the partial note.

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 compact and front-loads the purpose before describing the partial-return behavior. The second sentence is somewhat fragmentary ('A list; when...'), but every piece of information 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 zero-parameter, no-output-schema listing tool, the description gives enough context to call it and interpret the main response. It could be more complete by clarifying read-only behavior and the exact shape of the partial response, but the core is covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so parameter semantics are not a meaningful burden. The description does not need to explain any input parameters, and the baseline for a zero-parameter tool is 4.

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

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

The description clearly identifies the resource as the user's other Caddie agents and lists the key fields returned: purpose, current work, and Mac availability. It also states the intended use for choosing an agent for ask_agent, though it does not explicitly contrast with other agent-related siblings like agent_tasks or organize_agents.

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 provides clear usage context: this tool helps pick an agent for ask_agent. It lacks explicit when-not conditions or comparisons to adjacent tools, but the intended selection scenario is stated directly.

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 'Read only' does disclose that this is a non-mutating operation. It also thoroughly enumerates the sensitive data returned (public URLs, booking form questions, Google account, hosts), which is genuinely useful. However, it says nothing about auth, pagination, result size, or ordering, leaving notable gaps for an unannotated tool.

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

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

It's a single front-loaded sentence with no filler, and the large parenthetical enumeration earns its place because there is no output schema to otherwise describe the return shape. It is dense and slightly hard to parse as a run-on, which keeps it below a 5.

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 0-param read tool with no annotations and no output schema, the description does a solid job of covering what's returned. But it omits format concerns (pagination, empty results, ordering, size) and usage context, which the description is the only place to convey.

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 of 4 applies. There is nothing for the description to disambiguate, and the absence of parameters is consistent with a simple listing tool.

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 makes clear this returns the user's booking links with their public URLs, full settings, and upcoming bookings. It's effectively a return manifest rather than a verb-fronted statement, but the resource and its scope are unambiguous. It implicitly separates itself from siblings (create/update/delete/disable_booking_link) through the 'Read only' tag and listing nature, though it never names 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?

Usage is only implied: the agent infers 'call this to see your booking links and their upcoming bookings.' Nothing states when to prefer this over find_free_time, list_events, or the CRUD siblings, and no prerequisites or exclusions are given. Implied usage without explicit when/when-not guidance fits a 3.

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 it does disclose one behavioral detail beyond the schema: results include a per-collection note count. However, it says nothing about scope (all collections in the workspace vs. a subset), ordering, pagination, or permissions, which an agent might want for a listing 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?

One tight sentence with the resource and the payload detail front-loaded; nothing is wasted. It is a fragment rather than a full sentence, which slightly limits readability but not efficiency.

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, no-annotation, no-output-schema listing tool, the description is roughly sufficient: it names the resource, the domain mapping (folders), and the returned count field. Gaps remain around scope/ordering/empty results that an agent could otherwise infer only by trial.

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 optional parameter (workspace) is already richly documented in the schema, including how to find workspace ids via list_workspaces. The description adds no additional parameter semantics, 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?

The phrase identifies the exact resource (collections/folders) and even clarifies the domain concept by equating collections with folders, plus notes the returned metric (note counts). It reads as a noun phrase rather than 'List collections', but the name and content make the operation unambiguous and separate it from create_collection/rename_collection/delete_collection.

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 offers no when-to-use or when-not-to-use guidance, no mention of prerequisites, and no routing to alternatives (e.g., search_notes vs. this). The only usage glue lives in the schema's workspace description ('Use the same one you found the item in'), not in the tool 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?

With no annotations, the description carries the full behavioral burden. It discloses useful context such as structured typed tables, row-by-row reading/changing, and cross-workspace behavior, but it does not explicitly state that this specific call is read-only, nor does it cover ordering, pagination, permissions, or return shape.

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 reasonably front-loaded, moving from concept to usage to workspace scope. The first sentence mixes listing with row-by-row reading/changing, which slightly blurs the action, but there is little wasted text.

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 one-parameter list tool, the description covers purpose, examples, alternatives, and workspace scope. It is still incomplete because it does not clarify the list-vs-get distinction, return shape, pagination/order, or resolve the workspace omission inconsistency with the 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 defines workspace. However, the description says that without workspace it lists tables everywhere the user is, while the schema says omitting workspace selects the user's personal one; that is a potentially misleading conflict about parameter behavior.

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 explains that these are the user's structured, typed data tables and says it lists tables, with concrete examples like an outreach registry and CRM. It distinguishes data tables from note tables and spreadsheets, but it does not explicitly distinguish this listing tool from siblings such as get_data_table or query_rows.

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 rule: use data tables instead of a table inside a note or a spreadsheet whenever keeping records. It also explains that omitting workspace lists tables everywhere, but it does not state when to use this tool versus get_data_table, query_rows, or create_data_table.

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 bears the full behavioral burden. It usefully discloses the data source (connected Google calendars), the default date window, and key returned identifiers for downstream update/delete calls, but it does not clarify pagination, timezone handling, whether all connected calendars are included, or other read behavior details.

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 tight sentences with no filler. Purpose, date format, default range, and returned identifier fields are all front-loaded and useful.

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 or annotations, the description covers the essential invocation context and key return identifiers. It could be more complete about the full event payload and timezone behavior, but the core information needed to select and call the tool is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for both parameters. It does so by explaining that the two dates are YYYY-MM-DD formatted and that the default range is today through the next 7 days, though it omits explicit inclusivity and timezone semantics.

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 and scope: calendar events from the user's connected Google calendars between two dates. It also implicitly distinguishes this listing tool from mutation siblings by noting that returned ids/calendar_id/account_id are used for update_event and delete_event.

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

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

The description gives clear usage context by defining the date range and its default window, so an agent knows when this tool applies. It does not explicitly name when to choose list_events over siblings like list_meetings or find_free_time, but the calendar-event scope is clear.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that results are "always personal" (no workspace scoping) and that the date defaults to today, but it never states that the call is read-only, whether there is pagination or a result limit, or how routines are represented relative to habits.

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?

It is a single sentence with no padding, and the resource is front-loaded. But the clause structure ("and for habits whether they're done on a date...") is grammatically tangled and forces re-reading to parse habits-versus-routines 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 no output schema and no annotations, the description must explain the return shape, and it does partially (days, times, done-on-date, streak). It leaves ambiguous whether routines are returned alongside habits, whether done-status applies to routines, and any ordering or volume expectations.

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 already 100%, but the description adds real meaning: the date controls which day's completion status is reported and defaults to today if omitted. That is semantics the schema's bare "YYYY-MM-DD" string does not convey.

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 the resource ("the user's habits and routines") and enumerates the returned fields, so the agent knows what data comes back. However, it never states the operation as a verb (list/retrieve) and does not distinguish this tool from the sibling list_routines, which appears to overlap on the routines half of the same data.

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?

There is no when-to-use guidance, no mention of when to prefer list_routines, and no pointer to create_habit/log_habit for writes. The agent must infer usage entirely from the tool name and the described payload.

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 a decent job: it discloses ordering (newest first), the full per-item payload, and a non-obvious access rule — 'Secret notes show their title only' — which is exactly the kind of behavioral caveat annotations would otherwise supply. It omits auth/scope expectations and doesn't mention that results are capped (the limit max of 50 lives only 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?

Front-loaded with the resource and return shape, then filter semantics, then next-step routing — a sensible order. The telegraphic style ('minutes, people, a one-line summary...') is dense but readable. Slightly over-packed into two long clauses, but 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?

There is no output schema, and the description compensates by enumerating every returned field, so an agent knows the shape of results without guessing. With 6 optional params, no required inputs, and no annotations, the only thing an agent still needs is pagination behavior, which the schema's limit description covers.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, and the description fills the biggest gaps: 'query' and 'person' have no schema descriptions at all, yet the text defines query as matching words in title, people or note (all required) and person as someone in the call's people or a speaker list. from/to are restated with the 'user's day' nuance already in the schema. 'limit' and 'workspace' are left to the schema, which documents them adequately.

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 the resource precisely — the user's recorded calls (meeting notes) — and enumerates exactly what each row contains (id, title, date/time, minutes, people, summary, transcript line count, follow-up states). It distinguishes itself from get_note, get_transcript and followups_list by naming them as follow-ups. It lacks an explicit verb like 'list', but the 'newest first' collection framing makes the operation 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?

It explicitly routes the agent onward: 'Read one with get_note or get_transcript, its follow-ups with followups_list,' which tells the caller this tool is an index, not a content fetch. The filter clauses (from/to, person, query) imply when each filter applies. It does not contrast with search_notes or search_transcripts, which are the closest siblings, so there is no explicit when-not guidance.

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 it does disclose a meaningful behavioral trait: invites are only returned for workspace owners and admins. It does not state that the call is read-only, nor anything about pagination or result size, which is a gap for an annotation-free 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?

A single telegraphic sentence delivers the resource, its fields, the conditional invite visibility, and the parameter source with no wasted words. The terse, fragment-like phrasing is efficient, though slightly harder to parse than a full 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?

For a one-parameter read tool with no output schema, the description covers the returned fields, the permission-conditional invite data, and how to supply the workspace identifier. Only the lack of read-only/pagination context keeps it from being fully complete.

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: 'workspace: its name or id' clarifies the accepted value form and points to list_workspaces as the source. Only one parameter exists, so this is close to complete 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?

The description names the exact resource and its returned fields (name, email, role: owner/admin/member) plus the guest invites, which lets an agent distinguish it from list_workspaces and invite_member. It is a noun phrase rather than a verb-led statement, so the 'list' action is only implied by the tool name.

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 parenthetical '(list_workspaces)' points to the sibling used to obtain a workspace name or id, giving implicit routing guidance. However, there is no explicit statement of when to call this versus list_workspaces or invite_member, and no prerequisites beyond the workspace argument.

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 declares 'Read only', explains the { routines, partial } envelope, and defines 'partial' as 'some agents weren't read' — a non-obvious degradation state an agent must handle. It also clarifies that 'on' is false when paused OR when the task is done, which prevents a misread of the state field. It does not cover ordering or empty results, keeping it short of 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?

Everything is front-loaded into a single sentence with the resource first and the read-only/alternative note last. The parenthetical glosses are justified because there is no output schema, though the run-on density makes it harder to scan than it needs to be.

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-param, no-output-schema, no-annotation tool, describing the return shape and the 'partial' flag is the essential missing piece, and it is supplied. Only minor gaps remain (ordering of results, behavior when the user has no routines).

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. The description instead spends its space documenting the response fields, which is the relevant semantic detail for a no-arg call.

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

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

The description states the resource ('The user's routines') and enumerates exactly what each entry contains (id, name, running agent, schedule, on/off state, last/next run, instruction start), so an agent knows precisely what this returns. It also draws a boundary against the create path ('create_routine proposes a new one'), separating read from write.

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 read-only framing and names an alternative (create_routine) for the creation case, which is the main confusion risk. It does not address when to prefer this over sibling listing tools like list_agents or search_runs, so the routing guidance is clear but incomplete.

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; 'List' implies read-only, and it usefully discloses that in a team workspace each task reports whose it is. It says nothing about pagination, result limits, ordering, or return shape for a potentially large task set.

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 dense sentences with pipe-delimited enumerations and zero filler; the core action leads and the qualifiers follow. The parenthetical definitions are slightly compressed but each phrase 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 3-parameter, no-output-schema read tool the filtering semantics are well covered, but nothing is said about result volume, ordering, or pagination, which an agent needs to know when listing 'open' or 'done' tasks.

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 33%, but the description compensates well: every filter enum value is defined and 'mine: true' is explained as keeping own plus unassigned tasks. The workspace parameter is already documented in the schema, so the description adds real meaning beyond it.

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?

Opens with a specific verb+resource ('List tasks') and enumerates exactly what can be listed via the filter values, which separates it cleanly from write siblings like create_task and update_task. It does not, however, differentiate itself from other listing tools such as followups_list or agent_tasks.

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 filter definitions effectively explain how to scope a query (inbox = unscheduled To-dos, not Someday/Later this week; open = all not done), which implies usage. But there is no explicit statement of when to reach for this tool versus the other task-related listing siblings, and no note on defaults.

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 access scope ('each team workspace they're in' — not all workspaces) and the returned fields. It never states it is a read-only, side-effect-free operation or whether result size is bounded, which is the main remaining gap for a zero-annotation 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: what it returns, how siblings consume the result, and the selection rule. Front-loaded with the resource definition and no repeated or filler text.

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

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

For a parameterless read tool with no output schema, the description supplies return shape, access scope, and the tie-in to sibling tools' `workspace` argument. Absent an explicit read-only statement and any hint about ordering or a default personal entry, it is nearly complete but not airtight.

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 parameters, so baseline is 4; the schema is empty rather than misleading. The description usefully explains the `workspace` argument that sibling tools accept, which aids correct orchestration even though it is not a parameter of this tool.

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 the resource ('the user's workspaces') and enumerates exactly what each entry contains (name, id, their role), which is effectively a listing verb plus scope. It distinguishes itself from siblings like list_members or list_collections by making clear these are workspaces the user belongs to, though it never uses an explicit verb like 'list'.

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

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

It explicitly frames the downstream use case: notes/tasks/collections tools take a `workspace`, and without one they fall back to the personal workspace, plus a decision rule ('Pick a team when the user names it or the work is the team's'). That is clear contextual guidance, but it stops short of an explicit 'call this tool when X, not Y' trigger for the tool 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?

With no annotations, the description carries the burden and does well: it discloses that done=true affects every session of a multi-session habit, that done=false clears the day (an overwrite/erase behavior an agent must know about), and that sessions overrides done. It omits return shape and any permission/error behavior, which keeps it short of 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?

One dense sentence that front-loads the primary action and then covers the edge cases in order of likely need. It is slightly run-on but no clause 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?

For a 4-parameter mutation tool with no annotations and no output schema, the description covers the tricky semantics well but leaves gaps: what 'id' identifies, the expected date format, and whether logging is idempotent or overwrites prior entries. Adequate but not complete.

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% (id and date have no schema descriptions), so the description must compensate, and it does for the ambiguous parts: it establishes that date defaults to today and clarifies the interaction between done and sessions beyond the schema's own wording. The id parameter and the accepted date format are still undocumented.

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 ('Mark a habit done') plus the core scoping (a date, defaulting to today). An agent can tell this is a per-day habit log rather than a habit definition change, though it never names update_habit/create_habit as the alternative, so sibling differentiation is left 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?

It does explain the three usage modes clearly: done=true marks all sessions, done=false clears the day, and sessions logs a partial count. That is useful implied guidance, but there is no explicit statement of when to reach for update_habit or create_habit instead, nor any prerequisite context.

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

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

With no annotations, the description carries the behavioral burden. It usefully notes that the note is user-editable and that instructions hold a turn-start snapshot, but it never explicitly states that this operation is read-only and has no side effects.

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 a single dense sentence with a redundant parenthetical repetition of the note name. It is front-loaded with the resource, but the quotation-heavy structure makes it slightly harder to scan 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?

For a zero-parameter read with no output schema, the description sufficiently explains what data is returned and the key caveat about stale turn-start memory. It could explicitly confirm read-only behavior, but the essential context is present.

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 for a 4 when no parameter meaning needs explanation. The description appropriately focuses on what is returned rather than parameter behavior.

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

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

The description clearly identifies the resource: a user-editable memory note with specific sections ('About you', 'People', etc.). It implies retrieval but does not use an explicit verb like 'read' or name the sibling memory_update, so it is clear but not maximally sharp.

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 strong when/when-not guidance: the memory is already present at turn start, so re-read only after changing it. This routes usage effectively, though it does not explicitly name memory_update as the 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 load and does well: it discloses atomicity ('all or nothing'), hard size limits (300 chars/line, 4000 total), the forced merge/remove behavior when full, and prefix-matching semantics for edits and removals. It stops short of stating what the response looks like or whether removed facts are recoverable.

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 purpose and atomicity, then usage rules, then hard constraints, then examples — well ordered. It is wordy in places (the parenthetical 'Always send…' contrast is helpful, but the guidance portion is dense prose that could be tightened).

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?

No output schema and no annotations, so the description must define the whole contract for a single nested-array operation parameter, and it covers ops, limits, matching, and exclusions. The unmentioned `section` field and the absence of any statement about the return value are the remaining 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 description coverage is 0%, so the description must compensate and largely does: it explains add/patch/remove intent, one-fact-per-line, line length limits, and that an edited/removed line is matched by a fragment ('A line you change or remove is matched by a part of it'), which is the key semantic for the `old` field. It never mentions the `section` property or what values it accepts, leaving one 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?

States a specific verb and resource ('Change what Caddie knows about the user') plus the critical scope detail 'line by line, all or nothing' (atomic mutation). This clearly separates it from the read-side sibling memory_read without either schema being opened.

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 defines when to use ('facts that will still matter in a month') and when not to ('Don't save task progress, one-off details, what you did today'), naming the alternatives for each: search_runs for activity, a skill for procedures. Routing guidance is unambiguous.

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 substantial work: it discloses the side effect that the target collection becomes the note's main one, the special destructive-ish semantics of "Inbox", that tasks travel with the note, that team workspaces expose it to everyone, and a concrete refusal condition for agent-initiated cross-workspace moves. It does not cover failure modes (non-existent collection/workspace) or what happens when both collection and to_workspace are supplied.

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?

It is a single front-loaded sentence that leads with the primary action before qualifications. The nested parentheticals make it dense to parse, but nearly every clause conveys a non-obvious rule an agent needs, so there is little wasted text.

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 4-parameter mutation tool with no annotations and no output schema, the definition covers the important behavioral consequences and one hard constraint. Missing are return/confirmation behavior and error conditions, which an agent would likely need before firing the call blindly.

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 50%: workspace and to_workspace are documented in the schema, while id and collection are not. The description compensates for the collection gap by defining the "Inbox" sentinel and the main-collection effect, but adds nothing about `id` and does not clarify interaction between collection and to_workspace when both are set. Adequate, with a clear residual 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 names a specific verb and resource ("Move a note") and spells out the two independent dimensions it operates on: collection membership and workspace. It even characterizes the special "Inbox" value. It stops short of explicitly contrasting with siblings like update_note or create_collection, but the operation is 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?

Usage is implied rather than stated: there is no "use this when..." or explicit alternative tool named. It does provide useful in-context rules — use "Inbox" to clear collections, and pass the same workspace you found the item in — plus a disclosed refusal case, which lifts it above bare implication but leaves the agent to infer when to prefer this over update_note.

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 note is created as a local copy on the user's Mac, that the operation mirrors the native 'New from template' flow, and that it returns the new note's id. It stops short of covering failure modes such as an ambiguous template name or a workspace not open in Caddie, which matter for a dependent-on-local-client 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?

A single tightly packed sentence with the action front-loaded, followed by the qualifying definition and the return value. Nothing is redundant and every clause adds 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?

For a 4-parameter, no-annotation, no-output-schema tool, it covers the essentials: template semantics, the Mac/local-client dependency, and the return value. What's missing is guidance on cross-parameter constraints (workspace must match the open Caddie workspace) and error behavior, which the schema only partially implies.

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 the schema lacks: it defines what constitutes a valid template ('notes marked "Use as a template"') and frames the output as a copy to fill in, which clarifies the relationship between the new note and its source.

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 ('Make a new note from one of the user's templates') and disambiguates from plain note creation by defining what a template is ('notes marked "Use as a template"') and what the result is ('a copy to fill in'). The UI analogue (⌘K › New from template) makes the behavior concrete and separates it from siblings like create_note or create_video_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 description makes the intended use case clear (instantiate a template rather than author a blank note) but never explicitly says when to prefer create_note instead, nor what happens if multiple templates match. Clear context, no stated exclusions.

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