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

With no annotations, the description carries the full behavioral burden; it does disclose that each call appends rather than overwrites and that markdown is supported, which is useful. It does not say whether a daily note is created when none exists for today, where in the note content lands relative to the timestamp, or that the markdown syntax can create Task/Tag objects as a side effect (that only appears 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?

Three short sentences with the core action front-loaded and no filler. Every sentence contributes: target, format support, and append semantics.

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 append tool with a fully documented schema and no output schema, the description covers the essentials. The main residual gap is note-creation behavior when today's note does not yet exist, which an agent would want to know before calling.

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

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

Schema description coverage is 100%, so the schema already explains markdown conventions and the no_timestamp flag in detail. The description only echoes that markdown is supported and says nothing about no_timestamp, so it adds little beyond the structured field data — baseline 3 is appropriate.

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

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

The description gives a specific verb and resource ("Add content to today's daily note in Capacities") plus the scope constraint that only today's note is targeted, which separates it from the generic append_to_object sibling. It stops short of naming that sibling or any other alternative, but the action itself is unambiguous.

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

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

Usage is only implied: an agent can infer this is for journaling into today's note rather than an arbitrary object, but the description never states when to prefer it over append_to_object, create_object, or update_object. No exclusions or prerequisites 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 does well: it declares the operation additive, non-destructive ("never removes"), scoped only to the body ("never touches typed properties"), and positional (appends at the END). It stops short of stating what is returned or any auth/error behavior if the objectId is invalid.

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 tight sentences: the additive/end-of-body constraint is front-loaded, then the sibling disambiguation follows. No filler, no restating 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?

For a two-parameter mutation tool with no output schema and no annotations, the description covers intent, scope, and routing adequately. The one real gap is that the agent cannot learn what the call returns or how failures surface, which matters slightly more given there is no output schema to fall back on.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the Capacities markdown conventions and their object-creating side effects. The description adds only the notion of appending to the body's end, which is baseline-level value when the schema does the heavy lifting.

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 ("Append markdown to the END of an existing object's body") plus the underlying endpoint, and explicitly contrasts itself with the sibling update_object. An agent can separate this from update_object 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?

Gives an explicit routing rule: use update_object to change typed properties (scalars/labels/relations), use this to add notes/body. Both the when and the when-not are named, with the alternative called out by name.

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 real behavior: name resolution is strict ('an unknown name is an error, never a guess'), `create_missing_relations` is an explicit opt-in, and body markdown has side effects that create objects. However, it never says what the tool returns or how to obtain the new object's id, and says nothing about permission/auth or duplicate-title handling.

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

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

Front-loaded with purpose, then prerequisite, then parameter grouping, then the mutation caveat—so the most important routing information arrives early. It is dense and backtick-heavy, with some overlap against the schema's parameter descriptions, but no sentence is purely 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 an 8-parameter nested-object mutation tool with no output schema, the definition covers inputs well but omits the return shape entirely—an agent does not learn whether the created object's id is returned or whether a follow-up `get_object`/search is needed to link it. That is a real gap for a create tool whose typical next step is linking.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by splitting parameters into semantic groups (scalar → `properties`, options → `labels`, entities → `relations`), stating that dates are ISO-8601, and clarifying that names resolve strictly rather than fuzzily. That strictness contract is the key addition beyond the schema's generic 'resolved strictly' phrasing.

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 ('Create a new object') and scopes it ('of any structure in your Capacities space'). It also explicitly separates itself from sibling `update_object` ('not this tool... replaces; this creates'), so an agent can route without opening schemas.

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

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

Gives an explicit prerequisite workflow: 'Call `get_space_info` first to get structure_id, property ids, label options, and relation target types.' It also names the alternative for the adjacent case (`update_object` for replacement), covering both when-to-use and when-not.

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 supplied, the description carries the full burden and does disclose the critical traits: default behavior moves the object to Capacities trash and is recoverable, while hard_delete=true is permanent and irreversible. It omits secondary effects an agent might need, such as what happens to linked objects or backlinks and whether an error occurs if the object is already trashed.

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 tight sentences with the recoverability consequence front-loaded and the destructive caveat attached directly to the flag that triggers it. No filler, no repetition beyond what is needed to bind behavior to the parameter.

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 destructive tool with no annotations and no output schema, the essential risk information is present, so an agent can call it safely in the common case. Completeness is weakened by the absence of any statement about cascade effects on linked content, permissions, or the result of deleting a non-existent or already-trashed object.

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

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

Schema description coverage is 100%, so both objectId and hard_delete are already documented in the schema, and the description largely restates the hard_delete semantics rather than adding new meaning. It adds nothing about objectId format or constraints, 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 description opens with a specific verb+resource ('Delete an object'), which is unambiguous and clearly distinct from siblings like update_object, append_to_object, or unlink_from_context. It never names a sibling to contrast with, but the operation itself leaves no ambiguity about what the tool does.

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

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

The hard_delete=true/false explanation implicitly tells an agent which mode to pick for recoverable vs permanent removal, which is useful. However, it gives no guidance on when to delete at all versus unlinking or updating (siblings exist), and no prerequisites such as required permissions or whether the object must exist.

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 thoroughly: per-call budgets (5 relation filters, 45 requests), fallback behavior (a 50-result title search lists the whole type), ordering rules (date-in-title, newest first, undated last), and rate-window notes on fetch_cap. It even discloses partial-result signaling — the "Note:" line plus `seed_complete`/`candidates_complete` — which an agent cannot get from any structured field.

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 and nearly every clause carries operational detail. The cost is a dense wall of run-on sentences with repeated defaults (page_budget/fetch_cap limits already in the schema), which makes it harder to scan than a bulleted form would 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 tool with nested filter objects, no annotations, and no output schema, the description covers staging, budget exhaustion, result ordering, and even the shape of the second text block. An agent has everything needed to call it correctly and to interpret an incomplete result.

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 beyond it: title matching ignores case/accents/punctuation, requires a letter or digit, and short numeric hints match dates ("1:1" matches 2024-11-12). It also explains how page_budget and fetch_cap interact with the 45-request budget rather than just restating their defaults.

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 concrete verb+resource and scope: "Locate objects of one `structure`... then filter and sort client-side on properties the API cannot search." It also implicitly separates itself from body-returning siblings by stating it returns ids+titles only, so an agent can tell it apart from get_object 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?

Gives explicit seeding strategies (title_hint, tag, both, neither) with the condition for each ("omit `title_hint` to list by tag or list the whole type") and routes to get_object for bodies and get_space_info for structure ids. The one gap is that the overlapping full-text sibling search_content is never mentioned, so the choice between property-filtering here versus content search must be inferred.

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 a non-obvious behavioral quirk (the Labels line is parsed from the structured object and overrides frontmatter) and enumerates concrete known discrepancies such as omitted Open Question/Backlog/On Hold and Complete rendered as Done. It stops short of covering error behavior for invalid ids or truncation of large bodies.

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 in the first sentence and the remaining length is spent on parsing-critical detail (separator format, `(none)` sentinel, precedence rule) that genuinely earns its place. It is dense but not padded, though the Labels exposition could be tightened slightly.

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

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

For a one-parameter tool with no output schema and no annotations, the description compensates well by describing the exact return shape (frontmatter, body, synthesized Labels line) that an agent would otherwise have to discover empirically. Only failure modes and size limits remain 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 description coverage is 100% and there is a single parameter, so the schema already explains objectId. The description adds nothing about id format or provenance, leaving this at the baseline.

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

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

The opening sentence gives a specific verb and resource plus the return format: 'Read an object rendered as Markdown (YAML frontmatter of its properties + body).' It does not, however, distinguish itself from siblings such as find_objects or search_content, nor say how an objectId is obtained.

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 by the verb 'Read'; there is no explicit when-to-use guidance, no statement that this is the by-id fetch after find_objects/search_content, and no exclusions. The agent must infer the workflow from the required objectId parameter alone.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the payload contents (object types, writable properties, collections), from which read-only, metadata-only behavior can be inferred, but it never states that it is non-mutating, what permissions or space selection are required, or whether results are cached/static.

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

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

A single front-loaded sentence with the resource and its three returned components listed in order of importance. No filler, no restatement of the tool name beyond what's needed.

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 is the only source of return-value information, and it gives content categories but not shape or format (e.g., whether properties are keyed by object type). For a zero-parameter discovery tool this is adequate but leaves the agent guessing at the response structure.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond the (empty) schema. Baseline 4 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?

Uses a specific verb ('Get') and enumerates exactly what is returned: structures (object types), their writable properties, and collections, scoped to 'your Capacities space'. This distinguishes it reasonably well from list_spaces (which enumerates spaces) and from the object CRUD siblings, though it never names 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?

There is no explicit when-to-use statement, no prerequisites, and no named alternative. The reader must infer that this is a discovery/metadata call useful before create_object or update_object; the description never says so.

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 this is a mutation that appends to the END of the body (POST /blocks/append), that it is idempotent with existing block ids reported on a no-op, and that task_id must be a RootTask. It stops short of permission requirements, whether the target object's modified timestamp or notifications are affected, and what an error looks like when task_id is not a 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?

Four short sentences, purpose front-loaded, then model, then mechanism/idempotency, then type constraint. The 'derived, not a property' aside is slightly academic but earns its place by explaining why the tool exists rather than setting a field. 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 mutation with no output schema and no annotations, the description covers purpose, mechanism, idempotency, and a partial return-value hint ('existing block id(s) are reported'). Gaps remain around auth/permissions and the full success response, but nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning not in the schema: task_id must specifically be a Task/RootTask (a type constraint the schema omits), and object_id can be any embeddable object such as a person, project, or meeting. That materially reduces wrong-type calls.

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 task to another object's Context') and then defines the mechanism precisely: appending an EntityBlock embedding the task to the end of the target's body. The 'Context is derived, not a property' framing separates it conceptually from a plain property update and from unlink_from_context, even though append_to_object is never named.

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 derived-Context model, and the idempotency note tells the agent it is safe to call repeatedly. However, there is no explicit 'use this instead of append_to_object when...' routing, no prerequisite/permission note, and no pointer to unlink_from_context as the inverse.

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 implies a read-only list operation but does not state permissions, ordering, pagination, or whether it returns every accessible space; with no output schema, return behavior is also left implicit.

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 front-loaded sentence with no redundant wording. Its length is appropriate for a zero-parameter list tool.

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

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

For a simple zero-parameter list tool, the description identifies the resource and scope adequately. However, with no annotations or output schema, it omits return-shape context and does not explicitly relate the tool to get_space_info, leaving minor but real 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?

The tool has zero parameters, so the baseline is 4. There are no parameter meanings to clarify, and the description does not need to compensate for schema gaps.

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

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

The description states a specific verb ('Get a list') and resource ('Capacities spaces') with the scope 'all'. It distinguishes itself from get_space_info only by implication, since it does not explicitly say it enumerates all spaces rather than details 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?

There is no explicit when-to-use, when-not-to-use, or alternative routing. The word 'all' hints that this enumerates spaces rather than retrieving one space's details, but the agent must infer that from sibling tool names.

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 weblinks are create-only and immutable afterwards, that title/description override auto-fetched metadata, that other properties are not settable, and that `()` tasks and `#tags` in notes create objects as a side effect. It stops short of stating auth/permission needs, duplicate-URL behavior, or what a successful save returns.

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 the core action and the create-only constraint front-loaded. The stacked parentheticals are information-rich but slightly heavy; no sentence is genuinely 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 creation semantics, field limitations, markdown conventions, and side effects well. Return values are not needed, though duplicate-handling and any side effects of the metadata fetch remain 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 already 100%, so the baseline is 3; the description still adds value by explaining that title/description override auto-fetched page metadata and are the ONLY settable fields, and that notes is the channel for tags, tasks, and links. That override semantics is not evident from the schema alone.

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?

"Save a URL as a weblink object" gives a specific verb and resource, and the parenthetical that weblinks are create-only in the API separates this from create_object/update_object siblings. An agent knows immediately this is the weblink-creation path.

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 clearly frames when to use this tool (creating a weblink) and what cannot be done through it (updating, setting Category/Topic or other properties) and steers tagging/annotation to the notes field instead. It does not explicitly name a sibling alternative, but the create-only constraint effectively rules out the update path.

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 behavior, and it does disclose meaningful traits: results may include semantically related objects, they appear after title matches under a 'Related by meaning' label, and limit caps the combined list. It does not state that the tool is read-only, how permission or account state affects semantic results beyond a conditional, or anything about ordering within the title-match group.

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, front-loaded with the core action, then behavior, then parameter notes. No filler or repetition. Slight density in packing both result-group behavior and the limit interaction into consecutive sentences, 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?

No output schema exists, and the description compensates by describing the shape of results: title matches plus an optional labeled 'Related by meaning' section. Combined with the limit and scoping notes, an agent can call this correctly. The missing piece is the absence of read-only/mutation expectations, which matters given no annotations.

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

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

Schema coverage is 100%, so all three parameters are already documented, establishing a baseline of 3. The description adds real meaning for limit ('caps the combined list', i.e., across both result groups) but restates the schema for query and structureIds. Net value above the schema is modest.

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 first sentence names a specific verb and resource with scope: 'Search Capacities objects in your space by title.' That distinguishes it from generic retrieval, and the semantic-search sentence clarifies the match mode. It stops short of naming or contrasting with the sibling find_objects, which an agent could reasonably confuse with this tool.

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

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

The description implies usage through the conditional semantic-search clause and the optional structureIds scoping, which hints at when to narrow results. However, it never states when to prefer this over find_objects or get_object, and gives no exclusion guidance. Usage is inferable but not directed.

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 operation is a destructive multi-delete ('deletes EVERY EntityBlock... at any depth, in any block field, one DELETE /block each'), warns that nested content inside a removed block is destroyed too, and specifies the no-op case when no embedding exists.

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 action, with no filler; the parenthetical '(people, projects, meetings, ...)' and '(at any depth, in any block field)' are dense but each adds real semantic precision, though the middle sentence is long enough to be slightly harder to parse 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 two-parameter mutation tool with no output schema and no annotations, the definition covers mechanism, destructive scope, and the no-op case; it stops short of stating permission requirements, whether the call is idempotent, or what a partial failure across multiple DELETE /block calls returns.

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

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

Schema description coverage is 100%, so both parameters are already documented; the description only reinforces that object_id is the object whose body embeds the task and that removal happens at any depth, which adds marginal meaning beyond the schema baseline.

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

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

States a specific verb and resource ('Remove a task from another object's Context') and immediately defines what 'Context' means in Capacities as a derived set of embedding objects, which lets an agent distinguish this from siblings like link_to_context and delete_object without reading the schema.

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

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

Usage is implied by the derived-Context explanation and the no-op clause ('If the target does not embed the task, nothing is removed'), but the description never explicitly names an alternative such as link_to_context for the inverse operation or delete_object for destroying the task 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 behavioral burden and discloses the PATCH mutation, destructive replacement of named multi-value relations/labels, the body append side effect, strict name resolution errors, and the create_missing_relations side effect. It does not cover permissions, rate limits, or broader error/return behavior, so it is strong but not 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?

The description is front-loaded with the action and scope, then moves through the replacement warning, additive-relation guidance, body behavior, strict resolution, and create-missing behavior. It is dense but every sentence carries relevant information, and the warning is placed where it will be seen.

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 nested property maps and no output schema, the description covers replacement semantics, side effects, alternatives, strict name resolution, and relation creation. It leaves out return details and permission/error context, but provides enough for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds useful sequencing and resolution details: body is appended after the PATCH, keys accept property names or ids, labels and relations resolve strictly by name, and create_missing_relations auto-creates unmatched targets. Much of this reinforces the schema, but the added operational context is valuable.

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: replace typed properties of an existing object via PATCH /object. It clearly distinguishes this update operation from additive sibling behavior by explaining that named properties are replaced rather than appended.

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 explains that only named properties change, warns that values are replaced rather than appended, and gives explicit guidance for adding to relations by reading current values and passing the full desired list. It also identifies append_to_object as the standalone alternative for additive body writes.

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