OrgGen AI

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

Annotations only declare non-read-only and non-destructive; the description adds substantial behavior: creation of the struct-{parentId}-{cellId} dependency, parent growth, the container-vs-hat rendering rule, refusal semantics with 'nothing written', and the post-call tidy-up that may recompute x/y or raise card height. It even explains the divergence between MCP responses and chat bursts for final coordinates.

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

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

Front-loaded with the core action and coordinate rule, then routing, then edge cases — a sensible order. It is a single dense paragraph of ~200 words with some redundancy against the schema (displayMode and confirmRootPlacement caveats are repeated), which keeps it just short of a 5 for a tool this complex.

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 23-parameter mutation tool with no output schema, the description covers what matters: refusal conditions, side effects on the parent, the returned fields (cell, structuralDependency, note), and the caveat that the returned position may change after tidy-up. An agent has enough to call it correctly and interpret the 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 cross-parameter meaning the schema does not: x/y are relative only for a child of a 'container' parent, and in 'hat' mode children should be root blocks linked by structural dependencies instead. It does not add much on the remaining 20+ fields (colorKey, layoutHint, statusType, kindMetadata), which is acceptable given their thorough schema docs.

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 ('Adds one new org block') and immediately scopes it to a single block at given x/y coordinates, including the root-vs-child coordinate frame. It then names the sibling tools that handle adjacent cases (apply_batch, add_entity, add_kind_node), so an agent can distinguish it 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?

Explicit routing: single addition here, multiple blocks with content to apply_batch, ERD tables to add_entity, diagram nodes to add_kind_node, and existing blocks to update_cell/move_cell/clone_cell. It also states when the call is refused (duplicate id, unknown parent, locked root placement without confirmRootPlacement).

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

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

Annotations only tell the agent this is a non-read, non-destructive write; the description goes well beyond that by explaining that the canonical id is unchanged, that references need not move, that the alias is reserved for life and can never be reused, that derived identifiers intentionally keep citing the canonical id, and that replaying the call converges without duplicates. The idempotency and reservation semantics are exactly the kind of behavioral context annotations cannot carry.

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

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

The non-destructive guarantee is front-loaded and the structure (effect, caveats, alternative) is easy to follow, but the all-caps emphasis, warning emoji, and restatement of the 'reserved FOR LIFE' rule already present in the schema descriptions add some redundancy. It is informative rather than padded, so it stays above the midpoint.

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

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

With no output schema, the description still tells the agent everything needed to call the tool correctly: what changes, what does not, what is irreversible, and what happens on repeated invocation. All three parameters are required-or-optional with clear semantics, so nothing material 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 description coverage is 100%, so the schema already documents all three parameters, and the description's claims about newId being 'reserved FOR LIFE' and cellId accepting canonical ids or existing aliases largely duplicate the schema text. Baseline 3 is appropriate since the description adds little parameter meaning beyond what structured fields provide.

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 states a specific verb and resource ('Adds an extra call identifier (alias)') and immediately clarifies the intended effect ('to "rename" a block's identifier WITHOUT DESTROYING ANYTHING'), which separates it from the delete_cell/add_cell rename path named later. An agent can identify this tool's role 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?

It gives a clear context for use (renaming an identifier while preserving references) and names an explicit alternative — delete_cell + add_cell — along with the consequence that selects against it (links are destroyed). It does not state a hard 'do not use this when...' rule, so it falls just short of the 5 bar.

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

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

Annotations only declare it as a non-destructive write; the description adds substantial behavior the annotations do not: a named refusal if the task doesn't exist, the explicit no-cascade rule so threads survive task deletion, and how list_comments surfaces such threads as orphaned:true. It also discloses that mention IDs without real project access are silently dropped and reported in a `warning`, which is real anti-surprise information.

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

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

Front-loaded with the core action, then a dense anchor-type enumeration where each clause carries distinct information. It is long and would scan better as a per-anchor list rather than one paragraph, but there is little redundancy to cut.

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 nested-anchor mutation tool with six params and no output schema, the definition covers preconditions, the anchor decision tree, and failure/orphan semantics. It says almost nothing about the successful return value (thread id, the mentioned `warning` field is only mentioned in passing), which is the one thing an agent would still need to guess.

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 would be 3, but the description goes well beyond the schema's generic 'Comment anchor (...)' sentence: it maps each anchor type to its required companion IDs (pinX/pinY for free, documentId alone for document_range, taskId alone with explicitly no cellId for task) and explains why. The schema declares none of these conditional requirements.

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 is a precise verb+resource: 'Creates a new comment thread + first message.' It also enumerates the anchor variants, which clarifies the tool's scope. However, it never distinguishes this tool from the sibling reply_comment, which is the obvious alternative when a thread already exists — the agent must infer that this one starts a thread rather than extending 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?

The bulk of the text is guidance on which anchor.type to choose for a given situation, which is genuinely useful routing. It also states a precondition ('The task must exist in the active project (named refusal otherwise)'). What is missing is the primary when-to-use decision: new thread here vs. reply_comment for an existing thread, and it never says what to do when you don't have a cellId.

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 annotations only declaring write/non-destructive/openWorld=false, the description carries real behavioral weight: a hard volume cap (12 cumulated entries) that triggers a 'content.card-truncated' finding, which items do and do not count toward it, and the fact that contentBudget is returned both by get_cell_details (before) and by this tool (after). This is context the annotations cannot supply.

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

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

Front-loaded with the core action and type list, then the create_tasks routing rule and the volume cap as clearly marked warnings. It is dense and long but nearly every sentence earns its place; minor verbosity in the cap explanation keeps it from 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?

No output schema exists, yet the description still explains the meaningful return value (contentBudget after writing) and pre-empts the next call. For a non-destructive mutation tool with full schema coverage and annotations, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; however the description adds behavioral meaning about parameters beyond the schema, notably that 'text' blocks carry no entries and do not count toward the entry cap. It stops short of adding per-parameter syntax or edge-case detail the schema already 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?

States a specific verb ('Adds') and resource ('structured content block'), and enumerates the four block types ('list', 'text', 'actions', 'links') with their behavior. It explicitly differentiates itself from the sibling create_tasks, so an agent can tell them 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?

Names the alternative tool (create_tasks) and the exact condition that routes to it: work assigned to someone, carrying a due date, or tracked to 'done'. It also states this is 'THE mechanism to attach notes and detailed states', giving a positive routing rule as well as the exclusion.

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

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

Annotations only cover the safety profile (not read-only, not destructive, closed-world). The description goes well beyond them by disclosing a hard validation policy: any credential-like key at any nesting depth causes the entire call to be refused, nothing is written, and the error names the offending key. That is exactly the kind of behavioral contract annotations cannot express.

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 creation contract, followed by the guardrail and the usage cue. The credential sentence is long but earns its place; nothing is padding.

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

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

For a 13-parameter mutation tool with no output schema and thin schema descriptions, the description covers the two things an agent most needs: what gets written and the credential refusal that can void the call. It is silent on the returned identifier and on how a new source should be positioned relative to auto_layout_mcd, which are minor 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 low (38%) across 13 parameters, so the description must compensate; it partially does by naming sourceType, refreshCadence and the credential-free constraint on connectionInfo. However, position/size/colorKey/extractionLogic and the placement interaction with auto_layout_mcd get no description-level treatment.

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 (creates) and resource (a data-source block with kind='data-source'), and enumerates the metadata it writes. This cleanly separates it from update_data_source and delete_data_source in the sibling 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?

Gives an explicit selection cue: 'Fits when the user mentions an external source (Salesforce, internal database, file, event stream…)'. It never names a competing sibling (e.g. update_data_source) as the alternative, so it stops short of full when/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?

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, and the description adds substantial context beyond them: three explicit refusal conditions (duplicate id, fromId==toId, unknown block) with 'nothing written', and the downstream effect of `shares` on compute_group_ownership with the ignored-value rules. It does not state what a successful response returns, but with no output schema that is a minor gap for a create 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?

Purpose and the primary type distinction are front-loaded, and the later clauses on refusals and alternatives each carry decision-relevant information. The single dense paragraph duplicates the `shares` rules already present in the schema and would read better split into type/refusal/related-tool segments, but there is little true 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 13-parameter mutation tool with no output schema in a domain-specific org-chart model, the description supplies the semantics an agent cannot infer: type meanings, automatic-creation paths, refusal behavior, and which sibling to use instead. The omission of `expectedProjectId`'s project-targeting behavior is the main remaining hole.

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 92%, so the schema already documents nearly every parameter, including the `shares` look-through rules that the description largely repeats. The genuine additions are conceptual: what 'business' vs 'structural' actually mean and how `style` interacts with the default dashed rendering. `expectedProjectId`, the only cross-project switching parameter, is not mentioned at all.

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?

"Adds one dependency (arrow) between two existing org blocks" states a specific verb, resource, cardinality and scope. It immediately differentiates from the nearest lookalikes by naming add_relation (ERD field relations) and connect_kind_nodes (arch/process/journey/captable flows) as out of scope.

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

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

Explicit guidance on which of the two types to use and when: 'business' for ownership/lease/service relations including parent-to-child stakes, 'structural' only where add_cell (parentId) and move_cell do not apply, e.g. hat-mode parents. It also names the alternatives (add_relation, connect_kind_nodes, update_dependency, delete_dependency) with the conditions that select them.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=false, so the safety profile is structured rather than described. The description adds nothing about mutation semantics — notably it never explains why a create is flagged destructive (e.g. behavior when the id already exists) or that subsequent add_field calls are the intended follow-up. It does not contradict the annotations, but it leaves the surprising destructive flag unexplained.

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 core action front-loaded before the disambiguation clause. Every clause carries information an agent needs for selection.

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 create tool with a fully documented schema, annotations carrying the safety flags, and no output schema, the description covers identity and one routing decision. The remaining gap is sibling coverage: add_entity_with_fields is the obvious shortcut an agent might miss, and no guidance is given on when a single add_entity beats that combined call.

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% across 11 parameters, with per-parameter text covering auto-placement for x/y, kebab-case ids, color defaults, and the replace-vs-clear semantics of kindMetadata, so the schema does the heavy lifting. The description contributes only the 'kind=entity' framing and the 'ready to receive typed fields' hint, adding little beyond the structured fields — baseline 3.

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

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

States a specific verb and resource ('Creates an ERD entity') and pins the implementation detail ('block with kind="entity"'), then adds what it is for ('ready to receive typed fields'). It explicitly distinguishes itself from the sibling add_cell by contrasting data-table modeling with org-chart blocks.

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?

'Fits when modeling a data table; an org-chart block belongs to add_cell' gives an explicit when-to-use plus one named alternative, which is strong. It never mentions add_entity_with_fields, the near-duplicate sibling that creates an entity plus its fields in one call — the single most consequential alternative 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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation profile is known; the description adds the genuinely non-obvious ordering constraint on reference fields and the round-trip cost tradeoff. It does not cover failure behavior (duplicate `id`, atomicity/partial-creation on error), which is the remaining gap for a destructive 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?

Two dense sentences, front-loaded with the value proposition before the FK caveat; nothing is filler. The ⚡ glyph and the parenthetical round-trip arithmetic are marginal, but they support the speed argument rather than distract from it.

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 12-parameter nested, destructive creation tool with no output schema, the description covers the decision-relevant risk (FK ordering, batching alternative) while the schema carries most field-level detail. It could say more about what is returned or what happens when `id` already exists, but nothing required to call it correctly is missing.

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

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

Schema description coverage is ~58%, with parameters like `width`, `height`, `colorKey`, `parentId` and `desc` undocumented in both places. The description adds meaning only for `fields` — array order defines display order and FK entries require an existing target — which is valuable but leaves the geometry/parenting parameters unexplained. Baseline 3 fits given the partial schema 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?

States a specific verb and resource (creates the entity AND all its fields in one call) and explicitly contrasts it with the `add_entity` + N×`add_field` path, so an agent can distinguish it from those siblings without opening any schema. The concrete '6 tables × 5 columns' framing pins down the intended shape of the call.

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

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

Gives the selection condition ('when the fields are known at creation') against the named alternatives, and handles the main edge case: FKs are only allowed if the target entity exists, so create FK-free entities first and add the references afterwards via `add_fields_batch`. That is both a when-to-use and a when-not-to-use rule.

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

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

Annotations already declare a non-destructive, non-open-world mutation, so safety is covered. The description adds the discriminated-union call pattern and the add_relation follow-up, but much of it restates the schema (kind union, referencesCellId/referencesFieldId) rather than disclosing new behavior such as the enum 'values' replace semantics it leaves to 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 tight sentences with the core purpose front-loaded, the batch alternative bolded, and the reference workflow last. No filler; each sentence carries distinct 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 mutation tool whose annotations cover the safety profile and whose schema fully documents every parameter (no output schema to explain), the description covers the main call patterns and the FK follow-up. It could note failure conditions (e.g., duplicate id) 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 description coverage is 100%, so the schema already documents all 11 parameters, giving a baseline of 3. The description's notes on the `type` union and reference construction largely duplicate the schema, adding only the add_relation linkage, so no meaningful lift over 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 ('Adds ONE typed field to an existing entity') and uniquely differentiates itself from the sibling add_fields_batch by emphasizing the singular 'ONE'. An agent can select this versus the batch variant without opening either schema.

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

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

Names the alternative (add_fields_batch) and the exact condition that selects it ('Several fields to add'). It also routes the agent to add_relation as the required follow-up for foreign keys, giving explicit when-to-use guidance for a multi-step workflow.

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

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

The annotations already declare this is a non-read-only but non-destructive mutation, and the description adds useful context that it is a batch alternative to repeated calls. However, it does not disclose atomicity, duplicate-field behavior, partial-failure semantics, or permission requirements beyond what the schema's `expectedProjectId` note provides. With annotations covering the safety profile, this is adequate but not rich.

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 batch action and followed by the alternative and typical use case. Every sentence contributes to tool selection and there is no 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?

The description gives enough context to identify the tool and its typical workflow, and the rich schema covers parameter-level details. For a batch mutation tool, though, it leaves important behavioral gaps: whether the batch is atomic, how duplicate or conflicting fields are handled, and how it relates to `add_entity_with_fields`.

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 `cellId`, `fields`, and `expectedProjectId` are already well documented, including display order and enum replacement semantics. The description adds only the contextual notion that the field list must be known and the parent entity already exists, without adding syntax or constraints beyond the schema.

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

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

The description states a specific verb and resource: it adds several fields to an existing entity in one call. It also names the sibling alternative explicitly by contrasting itself with N× `add_field` when the field list is known, so an agent can distinguish the batch operation from the single-field 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?

It gives clear usage context: use this when the list of fields is known, and it cites the ERD workflow case of adding FKs after entities are created. It names `add_field` as the alternative but does not explicitly state when not to use this tool or discuss other siblings such as `add_entity_with_fields`.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds a genuine behavioral fact beyond them: orderInPhase is auto-computed when omitted. It does not disclose return values or access requirements, keeping it out of 5 territory.

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 verb and resource, and each sentence carries distinct information (domain semantics, auto-order behavior, sequencing). No filler, though the kind/journeyType clause is slightly dense.

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 full schema coverage and annotations on safety, the definition is largely callable. However, since there is no output schema, the description never says whether the created phase (and its phaseId) is returned — a notable gap given the stated intent that later steps reference phaseId.

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 documents all four parameters including expectedProjectId's retargeting behavior. The description only re-touches orderInPhase auto-computation and references phaseId (not a parameter here), adding little beyond the schema — the baseline 3.

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

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

States a specific verb+resource (create a journey phase) and disambiguates from the crowded add_* sibling family by defining the underlying object (kind='journey' / journeyType='phase' block). It does not name which sibling to use for other block types, but the purpose 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?

Gives real sequencing guidance: 'Meant to precede the creation of steps that will reference phaseId,' which tells the agent when in a workflow to invoke it. No explicit when-not or named alternative, so it falls short of a 5.

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

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

Annotations already declare a non-destructive write (readOnlyHint=false, destructiveHint=false), so the safety profile is covered. The description adds real behavioral context: metadata is 'strictly validated per kind' (implying refusals on malformed input) and the kind must align with the project's primary_kind, both of which affect whether the call succeeds.

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 tightly packed sentences that are front-loaded with the core action and constraint. The 'ALL LIVE since May 2026' clause is a slightly noisy, low-value claim, keeping it from 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 13-parameter, 4-required polymorphic creation tool with no output schema, the description covers the essential decisions (which kind, matching primary_kind, where to find metadata shape). Pointing to get_playbook closes the biggest gap, though it leaves return/ID behavior 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%, so the schema already documents all 13 parameters in depth. The description reinforces kind semantics and gives two metadata examples, but adds little that isn't already in the schema, so the 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 states a specific verb and resource ('Creates a node') and scopes it to the 4 polymorphic diagram kinds, naming them explicitly. It does not directly distinguish itself from siblings like add_cell/add_entity/add_swimlane in the description text (that differentiation lives only in the schema), so it stops short of a 5.

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

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

It gives a concrete usage rule ('kind must match the project's primary_kind unless the user explicitly asks to mix') and routes the agent to get_playbook for the per-kind metadata shape. It lacks explicit when-not/alternatives guidance against sibling creation tools, which the schema carries 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?

Annotations only declare this is a non-readonly, non-destructive, closed-world write; the description adds the failure contract ('REFUSED with an error, nothing written, if the id already exists') and the full default-filling behavior for omitted fields, which annotations cannot convey. It stops short of mentioning permissions or auth requirements for the write itself, so not quite 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 core action and the entity definition, then failure modes, then defaults, then sibling routing — a logical order with no filler sentences. It is dense with long parentheticals, but every clause carries operative 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 12-parameter creation tool with no output schema, the description covers the required fields, the uniqueness/refusal behavior, all defaults for omitted fields, and the lifecycle relationship to assign_person and update_person. An agent has everything needed to call it correctly on the first attempt.

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 value by enumerating the concrete default values (initials derived from name, role empty, colour '#5b9eff', network 'core', category 'executant', level 'Intermédiaire', no tags) that the schema mostly does not state. That is meaningful semantics beyond the field-level descriptions, though it repeats the kebab-case id constraint the schema already carries.

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 ('Creates a person') and immediately defines what a person is in this domain ('a member of the project's network: partner, executive, contributor…'), which distinguishes it from update_person, search_people and assign_person by naming each of 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 explicit routing: use search_people to check existence, update_person to modify, and calling this tool with a new id deliberately creates a second separate person. It also states the when-not case implicitly via the refusal rule, leaving almost nothing to inference.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world mutation. The description adds real behavior beyond that: the default cardinality ('many' on the FK side, 'one' on the target side) and the reference-type requirement on the source field. It does not, however, explain the referential-action semantics of onDelete/onUpdate.

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 tightly-packed sentences, zero waste, with the core verb and the batch alternative both front-loaded. 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 an 11-parameter mutation with no output schema, the description covers the essential creation semantics and defaults but omits the referential actions (cascade/restrict/set_null/no_action) that are central to a relation, and the project-targeting behaviour of expectedProjectId. 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 73%, so the schema already documents most parameters (toCellId, fromCellId, cardinals). The description reinforces the source-FK/reference constraint but says nothing about label, onDelete, onUpdate, or expectedProjectId, which lack schema descriptions. Baseline 3 is appropriate for 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?

Specific verb+resource ('Creates ONE relation between two entities'), with the singular 'ONE' capitalised to distinguish it from the batch sibling. It also states the key precondition (source field must be of type 'reference'). 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?

Explicitly routes to the alternative: 'Several relations: add_relations_batch places them in 1 call.' This names the sibling and the condition that selects it, and the reference-type prerequisite is also given up front. Nothing is left to inference for tool selection.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the mutation/safety profile is covered. The description adds the prerequisite condition (reference fields must already exist) and the cardinality notation, but says nothing about atomicity, partial-failure behavior, or validation of the referenced cells/fields.

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: the verb and batch scope come first, then the workflow placement. No filler, though the leading emoji and the parenthetical notation note are decoration rather than load-bearing.

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 batch write tool with no output schema and annotations that only say 'not read-only, not destructive', the description covers placement and prerequisites but omits what happens if one entry fails, whether the call is atomic, and how errors are surfaced. Adequate but with clear gaps for a multi-item mutation.

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 documents relations and expectedProjectId, including the cardinality enums. The description's only added gloss is labelling cardinalityFrom/cardinalityTo as 'Merise crow's foot' notation, which aids interpretation but does not explain the individual enum values or the onDelete/onUpdate 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?

States a specific verb + resource + batch scope ('Creates several FK relations in a single call'), which immediately distinguishes it from the singular create sibling add_relation and from add_fields_batch. An agent can tell what it does 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 sequencing guidance: 'phase 3 of the ERD workflow, after all the reference fields have been created via add_fields_batch.' This is a real prerequisite statement with a named predecessor tool. It stops short of naming add_relation as the single-relation alternative or stating when-not-to use the batch form.

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

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

Annotations already declare a non-read-only, non-destructive, closed-world mutation, so the safety profile is covered. The description adds genuine cross-tool behavioral context: lanes must exist before tasks and their laneId is referenced in task kindMetadata, which is not derivable from the annotations.

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

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

Three tight sentences, front-loaded with the action and definition, then the required input, then the multi-actor workflow. Nothing is wasted and no sentence merely restates the 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?

With no output schema needed and annotations covering the mutation profile, the description supplies the crucial workflow context (create before tasks, reference laneId) an agent needs. The one gap is that it does not explain expectedProjectId's session-override behavior, though the schema does.

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 each parameter (id, name, actor, order, expectedProjectId) is fully documented in the schema, so the baseline is 3. The description reiterates actor's required status and gives examples, but adds no format or defaulting detail beyond what the schema already 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 ('Creates a swimlane (actor lane) for the process') and immediately defines what a lane is, so an agent can distinguish this from siblings such as add_kind_node or add_journey_phase without opening any schema.

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

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

Gives clear ordering guidance ('one lane per actor, created before the tasks, with its laneId referenced in the kindMetadata of each task') and confirms 'the actor is required'. It establishes when and in what sequence to call the tool, but never names an alternative tool or a when-not-to-use condition.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, and the description adds genuinely new behavioral context: the three extra payloads are PERMANENT state, they are findings rather than mutations ("nothing is touched in the 'actions' content block"), and "fields absent = nothing to report, which does not mean 'I did not look'". That last clarification is exactly the kind of disambiguation annotations cannot carry.

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

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

The purpose and trigger are front-loaded, but the body is several very long run-on sentences with shouted emphasis (PERMANENT, WHOLE, THE SAME block) that are costly to parse. The detail is substantive, but it is not tight, and much of the return-field prose could be compressed.

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

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

With no output schema, the description carries the full burden of explaining returns and does so thoroughly, including three non-obvious diagnostic collections and the semantics of absent fields. It is complete for calling the tool correctly, though the trigger/routing vs the validate_* family remains 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 description coverage is 100%, so includeAllDeps, includeAllCells and expectedProjectId are already documented in detail (including that expectedProjectId actually retargets the call and is refused without access). The description adds no parameter-level semantics beyond the schema, 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?

Opens with a specific verb+resource ("Analyzes the state of the canvas") and enumerates the concrete problem classes it detects (missing positions, overlaps, invalid references, orphans, broken dependencies), which is more than a restatement of the name. It never distinguishes itself from the many sibling validators/analyzers (validate_arch, validate_journey, analyze_tasks, analyze_data_model), so an agent must infer the boundary.

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 states the trigger: "Serves when the user reports a visual problem or asks for a diagnostic." That is clear usage context, but no exclusion or alternative routing is given — it never says e.g. "use validate_captable for captable rules" or when NOT to call it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully discloses the class of findings returned, but says nothing about scope or permissions – notably that the call is refused unless access is granted to a targeted project, which is real behavioral context the agent needs.

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, no filler: the capability and its outputs come first, then the usage cues. Every clause carries information about either what is detected or when to invoke it.

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 only two optional params, the description adequately explains what the tool returns (a set of inconsistencies) and when to run it, so an agent can call it correctly with defaults. It is slightly thin on scope/permission behavior, but nothing essential to invocation 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 description coverage is 100%, so both parameters (minSeverity, expectedProjectId) are already documented in the schema, including the default and the project-targeting/refusal semantics. The description adds no parameter-level detail beyond that, 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 (audits) and resource (complete data model MCD/ERD), then enumerates the exact defect classes it detects (missing PK, broken FK, FK cycles, duplicate names, many-to-many without junction table). This distinguishes it from the validate_* and analyze_canvas/analyze_tasks siblings, which target other artifacts.

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 two concrete triggers: a user asking 'check my ERD', and the pre-export checkpoint before proposing SQL. That is clear when-to-use context, but it never names an alternative to prefer instead (e.g., validate_arch, export_ddl) or states when this tool is not the right call.

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

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

With readOnlyHint already declared, the description still adds substantial context: 'Modifies nothing', nothing is blocked, doubt stays silent (unreadable dates, corrupted cycles), signals are 'SIGNAL TO VERIFY rather than a verdict'. It also discloses severity taxonomy, the infoHidden count behavior, and explicit exclusion zones in notChecked.

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

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

Purpose and usage are front-loaded, then rules and caveats follow in a deliberate order with separators. The single dense paragraph is long, but nearly every clause carries rule or behavior information an agent needs; only minor redundancy (restating 'nothing is written/blocked') keeps it from 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 fully: it documents the finding shape (severity, message, suggestion), the measures block, the notChecked disclosures, and the infoHidden count. For an 8-parameter read-only analysis tool, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it ties arbitrationDays/clarificationDays to measures.openArbitrations and advises re-measuring before tightening, and clarifies doneNotArchivedDays is OPT-IN and OFF by default. It doesn't restate the limit/offset/cellId semantics already well 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?

States a specific verb and resource (analyzes the honesty of task/arbitration tracking) and defines the concrete deliverable: places where tracking announces OPEN what is closed or leaves a question unanswered. It also names the sibling it complements ('before relying on list_tasks'), so an agent can distinguish it from plain listing 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?

Explicitly says when to reach for it ('useful WHEN RESUMING a run, before relying on list_tasks'), names the alternative, and enumerates the exact rules that fire. It also states what it does not do ('does not compare task text to a repository... does not read CONTENT... does not look at linked projects'), giving real 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?

Annotations already declare readOnlyHint=false and destructiveHint=false; the description goes further by explaining what that non-destructiveness means concretely — existing attachments on neither side are touched, making the operation purely additive. It still omits auth/permission requirements and return behavior, so it is not exhaustive, but it adds real semantic value over the annotations.

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

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

Two sentences, front-loaded with the additive-vs-replace distinction and the alternative tool. Every clause earns its place; nothing is padding.

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

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

For a 3-param mutation tool with full schema coverage and safety annotations, the description covers purpose, the replacement alternative, and the additive guarantee. Only the result/return behavior is unaddressed, which is minor given no output schema exists.

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

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

Schema coverage is 100% and the cellId description already carries the 'in addition to existing attachments, not a replacement' wording, so the description largely restates structured data. It frames the parameters usefully but adds no syntax or format 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 precise verb (adds an ADDITIONAL attachment) and the exact resource pair (document↔block), and explicitly distinguishes its behavior from update_document's replacement semantics. An agent can tell it apart from update_document, unanchor_document, and add_content_block 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?

Names the selecting condition ('when a document must appear on SEVERAL blocks at once') and the excluded common case, routing it to update_document({cellId}) explicitly. Both when-to-use and when-not-to-use are 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?

Annotations only flag destructiveHint=true; the description explains exactly what is destroyed (supplying contentBlocks replaces the entire list, absent blocks are LOST), what is preserved (blocks from prior batches, kindMetadata merges), and what is returned to compensate (removedContentBlocks, skippedRefs). It also documents whole-batch refusal conditions and the contentBudget absence-is-not-'did not look' caveat — none of which the annotations carry.

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

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

The replacement warning is correctly front-loaded, and nearly every sentence carries operational content. However it is a dense wall of ALL-CAPS emphasis and emoji warnings that is hard to scan, and the closing contentBudget paragraph duplicates what get_cell_details already exposes, making it the least essential part.

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, multi-entity batch write with no output schema, the description covers sequencing, partial-failure behavior, overwrite semantics, and the shape of the response. An agent has enough to plan a correct multi-call sequence without trial and error.

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 cross-parameter semantics the schema cannot express: ordering of parent blocks across batches, the requirement that fromId/toId and personId/cellId already exist or be born in this batch, and that layout coordinates are server-recomputed. It omits the cardinality ceilings (12 cells / 20 people / 30 dependencies / 40 assignments), which the schema already 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 — builds the schema in batches — and positions itself as 'the write tool suited to any broad request', which distinguishes it from the single-block siblings (add_cell, update_cell, add_content_block) listed in the same breath. An agent can tell what it does and what class of operation it replaces 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 clear usage context: broad requests go here, while adding a single content block goes to add_content_block or a read-modify-send via get_cell_details. It also spells out the dependency-ordering rule and what to do with skippedRefs. It stops short of an explicit 'do NOT use this for a single block' sentence, but the routing 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?

Annotations only say destructiveHint=true; the description carries the real behavioral load: the task leaves lists and card indicators but is not destroyed, archiving never cascades and the response reports `liveChildren`/`liveChildrenNote`, and batch calls return `succeeded`/`failed` while still succeeding partially. These are non-obvious traits an agent cannot infer from annotations or 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 core action and its key property (non-destructive, replaces deletion), then layers edge cases in descending importance. Slightly redundant, since its batch-independence sentence largely repeats the `taskId` schema description verbatim in 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?

No output schema exists, and the description compensates by describing the response shape in both modes (`liveChildren`/`liveChildrenNote` for single, `succeeded`/`failed` for batch). Combined with the mutation-safety picture, an agent has enough to call and interpret 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?

Schema description coverage is 100%, so the schema already documents `taskId` array bounds, `claimToken` secret/lease semantics, and `expectedProjectId` targeting. The description only restates the array form and batch independence, adding little beyond the already-rich schema; baseline 3 applies.

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

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

Names a specific verb (archives) and resource (a task), and clarifies scope by noting `taskId` may be an array of up to 100. It also frames the tool as the non-destructive replacement for deletion, which positions it well. It never names the sibling it inverts (`unarchive_task`) or contrasts with `update_task`, so sibling disambiguation is incomplete.

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 conditions: use this instead of deletion; archive subtasks explicitly rather than expecting a cascade; in batch form ids are processed independently. It stops short of stating when NOT to use it or naming `unarchive_task` as the reversal path, which is the obvious alternative an agent would need.

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

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

The description explains the layout mechanics (start position + configurable spacing), which is useful context beyond the annotations. But annotations declare destructiveHint=true and readOnlyHint=false, and the description never says what that destruction means here — whether existing positions are overwritten, whether an overlapping block is displaced, or whether the move is undoable. With the safety profile already in annotations, this is adequate but leaves the mutation risk unexplained.

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 what front-loaded and the routing constraint second. Every clause carries information an agent needs to choose between this tool and the auto-layout family.

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

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

For a 7-parameter, fully schema-documented mutation with no output schema, the description covers purpose, scope, and the key alternative. What is missing is the consequence of the destructive mutation (displaced or overwritten blocks) and any indication of what the call returns or how a large cellIds list affects behavior.

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 layout, startX/startY, cellIds, spacing, gridColumns, and expectedProjectId are already documented, including defaults and enum meanings. The description restates the layout types and spacing but adds no new semantics such as how gridColumns interacts with grid or how expectedProjectId refusal behaves beyond the schema text. Baseline 3 applies when the schema carries the parameter detail.

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 (arranges), resource (several blocks), and the mechanism (row/column/grid from a start position with spacing). It also names the sibling auto_layout_canvas and the distinction (local few-block repositioning vs. whole-canvas tidying), so an agent can separate the two 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?

Explicitly bounds usage to 'LOCAL repositionings of a few blocks only' and routes the whole-canvas case to auto_layout_canvas with the reason (dedicated engines per kind). Both the when and the when-not are present, with the alternative named.

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

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

Annotations already flag this as a non-read-only, destructive mutation, and the description adds real domain behavior: shares are refused on non-entity block types, including 100, and omitted when unknown rather than invented. It still doesn't disclose the obvious destructive aspect — whether an existing assignment is replaced, or what happens on a duplicate assignment — so it stops short of full transparency.

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 five words, followed immediately by validation rules that matter for correct invocation. The single dense paragraph is justified by the domain complexity, though the parenthetical block-type lists make it slightly hard to scan.

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 output schema, the description covers validation but omits assignment semantics that matter: whether this overwrites an existing person on the block, whether role or shares are merged, and how expectedProjectId interacts with the session project. Those gaps leave an agent unsure of the side effects even though the schema is fully documented.

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

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

Schema coverage is 100%, so every parameter including expectedProjectId is already documented in the schema, often verbatim the same wording as the description. The description reinforces the shares/cellId interaction but adds little semantic detail beyond structured fields, 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 states a specific verb and resource ('Assigns a person to a block') and immediately scopes it with which block types accept assignments. It is distinguishable from the sibling unassign_person by direction, though it never names that 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?

It gives useful preconditions (block must be an assignable type, shares only for entity types), which is more than nothing. But it never says when to use this versus unassign_person, or what to do for a division/externe/infrastructure beyond omitting shares, so an agent still has to infer the alternative paths.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so safety is covered; the description adds real behavioral content — deterministic positions, no overlap, reserved routing gutters, separated cross-kind regions. It stops short of saying existing manual placement is overwritten and irreversible, which is the key consequence of a destructive whole-canvas rearrange.

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 core verb and scope, with the sibling comparison closing it out. Slight cost from capitalized emphasis (WHOLE, ONLY) and a long kind list, but nothing 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 destructive, no-return-value, aggregate layout operation the description covers what changes and how the result is determined. The missing piece is the reversibility/undo story and any duration or scale caveat for a whole-canvas operation.

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

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

Schema description coverage is 100%, and expectedProjectId is fully documented in the schema, so the baseline 3 applies; the description adds nothing about parameters. It also doesn't acknowledge that the call can be run with no parameters against the session project.

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 (Rearranges) and an explicit scope (the WHOLE canvas), and enumerates the kinds it handles (org, entity/ERD, arch, process, journey, captable). It also distinguishes itself from the nearest sibling, arrange_cells, so an agent can pick it 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?

It names the alternative (arrange_cells only makes a grid) and the condition selecting this tool, plus a claim of exclusivity for arch and captable. It doesn't explain when to use the per-kind siblings (auto_layout_org, auto_layout_process, auto_layout_journey) instead of this whole-canvas pass, leaving that inference to the agent.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description earns credit on top of that by disclosing the cross-region side effect: overlapping recomputed regions may shift FOLLOWING regions (org, ERD, process, journey, arch, captable) as a whole, not card by card. It stops short of saying whether the rearrangement is undoable or reversible, which matters for 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?

One front-loaded sentence pair: the action and resulting layout come first, the caveat about other regions second. It is dense but every clause carries information; the all-caps FOLLOWING/AS A WHOLE reads slightly awkward but signals emphasis rather than padding.

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

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

For a destructive, zero-required-parameter mutation with no output schema, the description covers what changes, what is preserved, and what collateral movement can occur. The main remaining gap is recoverability (undo/rollback) and what happens if phases or swimlanes are absent.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning by tying the geometry to the parameters — columns correspond to phases and rows to swimlanes, which is what columnWidth and swimlaneHeight control. It also surfaces 'order via orderInPhase', a phase-ordering concept not visible in the input schema.

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

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

The description names a specific verb ('Rearranges') and resource ('journey blocks') and states the exact resulting geometry: phases as a horizontal header, steps at phase column × swimlane. That geometry plus the journey-specific framing clearly separates it from auto_layout_org, auto_layout_process, auto_layout_canvas and auto_layout_mcd.

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 (call it to snap journey blocks into a grid) and one boundary is stated — it does not touch the internal layout of other kinds. But there is no explicit trigger condition, no 'use auto_layout_canvas instead when…' routing, and no prerequisite such as having phases or swimlanes defined first.

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

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

Annotations only say destructive=true; the description adds the operative details an agent needs: it overwrites hand-placed positions, clears manual waypoints, keeps no copy of the previous layout, has no dry run, and can shift other regions as a whole. This is exactly the context that annotations cannot convey.

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 layout algorithm, then consequences, then recovery, then exclusions. Dense but nearly every clause carries decision-relevant information; the single long paragraph and the trailing stacking-order list make it harder to scan than it could 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?

A destructive, no-input, no-output-schema mutation tool whose description covers side effects, reversibility, refusal conditions and cross-region consequences. There is essentially nothing an agent needs before calling it that 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 description coverage is 100%, so the baseline is 3. The description adds only 'Takes no input', which is slightly at odds with the schema's expectedProjectId (which actually retargets the project); no format or behavior detail is added beyond what the schema already documents.

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 ('Automatically rearranges all the ERD entities and data-source blocks') and immediately differentiates itself from auto_layout_org, auto_layout_process, auto_layout_journey and auto_layout_canvas by naming what it does not lay out. An agent can pick the right tool 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 trigger ('Handy after a large series of entity/relation additions'), explicit exclusions for the sibling layout tools, and a named recovery path (restore_version) plus a refusal condition (no ERD entity or data-source block). Nothing 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?

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds real substance: it discloses that the entire schema is repositioned deterministically, that container sizes are changed, and how roots are distributed. It stops short of saying whether existing manual positions are lost irrecoverably or whether the change can be undone.

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

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

A single dense sentence with zero preamble, front-loading the action before the mechanics and the usage condition. The internal algorithm details (measuring real block height, grid stacking) are close to implementation trivia but still frame the outcome an agent should expect.

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 is needed since the tool's effect is visual rearrangement, and the description covers what changes, on what scope, and under what conditions it is worth invoking. Combined with the destructive annotation, an agent has enough to decide and act.

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 expectedProjectId already documents cross-project targeting and the refusal-without-change behavior. The description mentions no parameters at all, so it adds nothing beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Rearranges the WHOLE org schema') with an explicit scope qualifier (WHOLE) and concrete outcomes (stack children in a grid, resize containers, distribute roots into columns). The word 'org' distinguishes it from the sibling layout tools (auto_layout_canvas, auto_layout_journey, auto_layout_mcd, auto_layout_process) only by implication, not by naming them, so it stops short of a 5.

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

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

'Fits when blocks overlap or after several additions, to tidy the canvas up' gives a clear triggering condition for when to call it. It does not state when NOT to use it (e.g., instead of the narrower auto_layout_* siblings) or any prerequisites, so it is clear context without exclusions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds meaningful behavioral detail beyond annotations: it does not change the internal layout of other kinds, and overlapping recomputed regions may shift following regions as a whole rather than card by card.

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 core rearrangement behavior and remains reasonably tight. The second sentence is dense but carries useful side-effect information; 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?

With no output schema, the description adequately covers the operation's scope, lane behavior, and cross-region shifting side effects. Annotations supply the destructive/read-write profile and the schema fully documents parameters, leaving only minor niceties like return value or idempotency 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%, with laneHeight, columnWidth, and expectedProjectId fully documented in the schema. The description adds only light context around lane placement (swimlaneOrder) and does not explain the sizing parameters, so 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 states a specific verb and resource: automatically rearranges process blocks into a left-to-right grid, with event-start, tasks, and event-end placement. It clearly scopes the operation to process blocks and swimlanes, making it distinguishable from generic canvas or journey auto-layout siblings.

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 one usage context: useful after several add_kind_node calls to get a clean rendering. However, it does not explain when to use this tool instead of the other auto_layout_* siblings, nor does it state any exclusions or preconditions beyond the implied process-block scope.

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

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

Annotations only mark this as a non-read-only, destructive write; the description supplies the real behavioral picture: a 15-minute lease, `claimToken` as a secret holder credential, what happens on expiry (takeover, not refusal), that a refusal writes NOTHING, that `CLAIM_HELD`/`CLAIM_LOST` gate other writes, and the exception for `impl-2026-10-*` tracking tasks. This is dense, non-obvious behavior an agent could not infer from structured fields.

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

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

Front-loaded with the core atomic-claim idea before any of the refusal taxonomy, and every block is information-bearing. It is nonetheless very long with heavy capitalization and some overlap between the refusal list and the lease section, which costs it the top score.

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 carries the return contract — `{ claimed: true, task }` versus `{ claimed: false, reason, message }`, the full `reason` enumeration, `reclaimed` on takeover, and `startedArbitrages` — plus the lease fields. For a zero-required-parameter, race-sensitive mutation tool, nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: `taskId` omitted means "the FIRST ready task ... priority, then position" with a race caveat, and `agentLabel` signing is explained along with the key-name fallback and the notion that the token never appears in written text. `expectedProjectId` is left entirely to the schema.

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

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

Opens with a specific verb and mechanism: "CLAIMS a task ATOMICALLY ... it goes from 'to do' to 'in progress' in ONE conditional write". It explicitly distinguishes itself from the nearest sibling by naming `update_task({ status: "doing" })` and explaining why that alternative is insufficient, so an agent can route correctly 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 explicit when/when-not: use this instead of a status update to avoid double-taking; omit `taskId` to take the next ready task; use `renew_claim` to hold the lease; use `update_task({ status })` to hand a task back; carry out arbitrations through child tasks, not dependents. It also names many refusal conditions that indicate when the tool is the wrong choice (arbitrage, human-task, awaiting-validation, write-locked).

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?

Goes well beyond the annotations (which only declare non-read-only, non-destructive, closed-world) by disclosing side effects and refusal conditions: a structural dependency is auto-created only for kind='org', and root placement may be refused without confirmRootPlacement. These are exactly the mutation side effects an agent needs.

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

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

Front-loads what is cloned before the exceptions, and each sentence covers a distinct cloning rule that earns its place. It is dense and slightly long, but not padded.

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

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

With no output schema, the description covers the important behavioral contract (what is copied, what isn't, refusal cases) thoroughly. It does not describe the return value of the clone, a minor gap for a tool with no output schema.

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

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

Schema description coverage is 100%, so the baseline is 3; the description reinforces and adds rationale for the newParentId/confirmRootPlacement interaction and the expectedProjectId refusal behavior. It adds contextual meaning about cloning rules, though little new syntax 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 (duplicates) and resource (a block with all its contentBlocks), scoping precisely what is and isn't copied. It also names the sibling it is distinct from (link_project_to_cell), so an agent can differentiate it 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?

Explicitly says what is NOT cloned (children, assignments, projectLink), directs project linking to the alternative tool link_project_to_cell, and explains that a child is cloned via its own clone_cell call. This gives clear when/when-not conditions and 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?

The readOnlyHint already establishes that this is a safe read operation, and the description adds value by naming the computed breakdown and return fields, which matters because there is no output schema. It still does not discuss permissions, errors, or the expectedProjectId override behavior beyond what the schema says.

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 sentences, front-loads the computation, then gives the visualization use case. There is no filler, and every clause contributes useful 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 read-only compute tool with no output schema, the description usefully names the return fields and the presentation context. It is nearly complete, but it could have clarified the relationship to compute_group_ownership or the cross-project targeting semantics.

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 both parameters, including the expectedProjectId targeting and access-refusal behavior. The description adds no parameter-specific meaning, so the 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 ('Computes ... direct ownership') and enumerates the outputs (totalShares, pricePerShare, per-holder shares/ownershipPct/valueAtPPS). It is clear what it does, though it does not explicitly contrast itself with the sibling compute_group_ownership.

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

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

It says the result 'Serves the numeric recap or a table view visualization,' which implies a usage context. However, it does not state when to choose this over compute_group_ownership or when not to use it, leaving alternatives to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description goes further: it spells out the exclusion rule (frontstage/backstage/support steps are skipped even if they carry metadata.emotion) and enumerates the returned fields. That is real behavioral context beyond the structured fields, though it says nothing about empty-result or partial-data 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 sentences, each carrying distinct information, with the core computation front-loaded before the filtering caveat and the return shape. Dense but every clause earns its place; only the parenthetical about orderInPhase is slightly 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?

There is no output schema, but the description compensates by enumerating the return values (emotionCurve fields, overall averageEmotion, swimlanesUsed, countsByType) and the exclusion/ordering logic. An agent has everything needed to call it and interpret the 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 description coverage is 100%, so the parameters (expectedProjectId, _unused) are already documented at the schema level. The description adds no parameter guidance of its own, 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?

Uses a specific verb+resource ('Computes the emotion curve of the journey') and immediately defines the unit of aggregation (average emotion per phase). It also carves out a precise inclusion rule (customer-side steps only), which makes it unmistakable against sibling analysis tools like analyze_canvas or validate_journey.

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 its intended consumer ('Serves summary visualizations or a numeric recap'), which gives an agent a clear context for when to reach for it. It does not explicitly name an alternative tool or a when-not-to-use condition, so it stops short of the top band.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, yet the description adds substantial non-obvious behavior: only `business` dependencies count as stakes, `structural` arrows are ignored even if they carry shares, and the exact return contents (sorted ultimate holders, paths, data-quality notes). This is genuine value beyond the annotations.

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

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

The definition is front-loaded with the core meaning and every sentence carries real information (stake semantics, return contents, read-only status). It is somewhat verbose with a rhetorical restatement ('who really owns how much...'), keeping it short of 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?

No output schema exists, and the description compensates by naming the returned artifacts (ultimate holders, detailed paths, data-quality notes). Combined with the ownership-modeling caveat, an agent has everything needed to call and interpret this 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% and all three parameters (minPct, targetCellId, expectedProjectId) are documented in the schema itself. The description adds no parameter-level meaning beyond what the schema provides, so the baseline of 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 ('Computes the EFFECTIVE OWNERSHIP ... of a block of the group') and immediately distinguishes it from the sibling compute_direct_ownership by scoping to transitive/look-through ownership up the whole chain. An agent can tell exactly what this tool produces without opening the schema.

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

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

Explicitly states when to use it ('Fits whenever an effective %, a transitive ownership, or "who controls X" is asked') and implies the contrast with direct ownership via the up-the-chain framing. It does not name the alternative sibling (compute_direct_ownership) or give an explicit when-not, so it falls short of a 5.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), lowering the burden. The description adds the semantic mapping of connection types, but says nothing about duplicate-edge behavior, whether self-loops are allowed, cross-kind edges, or authorization — beyond what the schema's expectedProjectId already notes about refusal on missing access.

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

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

A single dense sentence, front-loaded with the core action, followed by a scannable kind → type mapping. Every clause earns its place; the only mild waste is overlap with the schema's `type` description.

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 mutating, 12-parameter tool with no output schema, the definition covers the hardest decision (which type to use) but omits sibling differentiation, preconditions, and result behavior. Adequate to invoke for a user who already knows which tool they want, incomplete for an agent choosing among the many add_*/connect_* siblings.

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 42% across 12 parameters, so the description must carry weight — and it does for the most complex parameter: it maps each `type` enum value to a kind and adds meaning beyond the schema (HTTP/gRPC vs queue vs SQL vs event stream; dashed for process-message). It still leaves id, label, style, animated, anchors, strokeWidth, and color entirely to the schema, so it only partially compensates.

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 — 'Creates a dependency (arrow) between two nodes' — and adds the kind-specific type dimension. However, it never distinguishes itself from sibling tools like add_dependency or update_dependency, which plausibly do overlapping work, so an agent cannot route confidently from the description alone.

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 type-per-kind list implicitly tells the agent which argument values belong to which diagram kind, which is useful usage context. But there is no explicit when-to-use vs add_dependency/add_relation, no stated preconditions (do both nodes have to exist? must they be the same kind?), and no failure 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?

Annotations only say readOnlyHint=false and destructiveHint=true; the description goes far beyond by disclosing that the call is pure by default, exactly which fields get mutated when persist=true (securityType→preferred, shares, securityRound), and the non-obvious downstream consequence of omitting roundId — the holder is counted forever in every later round's pre-money base.

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

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

Front-loaded with the operation and formula, then the default/mutation contract, then the roundId pitfall — a logical order. It is dense with nested parentheticals and dashes, but every sentence carries information an agent needs.

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

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

No output schema exists, and the description compensates by naming the computed outputs (effectivePrice, sharesIssued) and the resulting holder state. For a five-parameter mutation tool with rich annotations, nothing an agent needs to call it correctly appears to be 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 already 100%, so baseline is 3; the description adds value by explaining the computation that consumes safeId and nextRoundPricePerShare (effectivePrice = min(price × (1-discount), cap / preMoneyShares)) and by reinforcing why roundId matters. It stops short of describing expectedProjectId's session-project fallback in the prose, leaving that to the schema.

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

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

States a specific verb and resource ('Converts a SAFE holder into preferred at the next priced round') and immediately gives the exact formulas used, so an agent knows precisely what the call computes. It also distinguishes itself from simulate_round by noting that the same conversion is built into round simulation.

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?

Clearly states the default (pure simulation, no schema change) and the two conditions that change behavior (persist=true to mutate, roundId to attach to a round), plus expectedProjectId's access-check semantics. It references simulate_round's built-in conversion as the equivalent path but doesn't explicitly say when to prefer one over the other.

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?

Goes far beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false): scope intersection with the caller, unconditional stripping of 'emit_keys'/'admin' limiting delegation to one level, refusal when no scope survives, silent-drop prevention via excludedScopes, 90-day default expiration, shared hourly issuance cap, account-level and parent-level live-key caps, and single-return plaintext key. This is exactly the behavioral context annotations cannot carry.

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

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

Purpose is front-loaded and most sentences earn their place, but the text is roughly 350 words with heavy duplication of the scopes-intersection and emit_keys/admin rules already present verbatim in the schema, plus emoji/ALL-CAPS emphasis. It is thorough rather than tight, and a reader must wade through repetition to extract the novel facts.

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 output schema, 5 parameters and only partial annotation coverage, the description supplies the missing pieces: what is returned (key plaintext once, excludedScopes/excludedProjectIds), what is never created, and the cap/refusal behaviors. Nothing needed to call it correctly or to interpret the response is absent.

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

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

Schema description coverage is 100%, so the schema already documents name, scopes, projectIds, description and expiresInDays in depth. The description's parameter discussion (intersection semantics, default expiration) largely restates the schema rather than adding new syntax or edge cases, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Issues a CHILD API key, from the calling key') and immediately scopes it as child-key issuance rather than generic key management, distinguishing it from revoke_api_key and from interface-created keys. An agent knows exactly what this call produces 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 preconditions and refusals: it is RESERVED for MCP calls authenticated by a key carrying 'emit_keys', and session/JWT callers are refused. It also routes to the sibling ('revoke_api_key revokes a child you no longer use') and contrasts with interface-created keys. There is no explicit 'use this instead of X' statement, but the when/when-not conditions are unusually complete.

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

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

Annotations already mark it as non-read-only, non-destructive, and closed-world, but the description adds substantial behavioral context: refused constructs (raw HTML, checkboxes, deep nesting), the meaning of the warnings field, a firewall 403 behavior that produces no application message, attack-pattern triggers, and the response url field. Nothing contradicts the annotations.

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

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

The description is long and dense, but each sentence carries concrete information and the core purpose is front-loaded. Some tangential details (e.g., firewall 403 and attack-pattern examples) could be trimmed or moved to error documentation, but overall it is efficient and 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 9-parameter creation tool with no output schema, the description covers response fields (url, warnings), refusal conditions, sandbox behavior, and integration with update_document. It provides enough context for an agent to call the tool correctly and interpret common 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 description coverage is 100%, so the parameter semantics are fully documented in the schema. The description largely repeats that information (e.g., contentMarkdown recommended, both omitted means empty) with minor emphasis, but adds little new parameter-specific meaning beyond what the schema already 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?

The description opens with a specific verb and resource: 'Creates a rich document.' It distinguishes the primary content-creation paths (contentMarkdown vs. content) and clarifies that an empty document can be created for later filling with update_document. The purpose is unambiguous and not a tautology.

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

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

It gives clear conditional guidance: contentMarkdown is the recommended path over content, both omitted yields an empty document, and cellId attaches the document at creation. However, it does not explicitly state when to use this tool versus siblings like add_content_block or update_document beyond a passing mention, so an agent must infer routing from resource 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?

Annotations already declare non-read-only, non-destructive, closed-world behavior, so the description's job is to add context — and it does: the governing-role authorization requirement and the fact that allowGuests lets people join without an account. It omits any note on link expiry, revocation, rate limits, or idempotency, so it stops 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?

Purpose and route are front-loaded in the first clause, followed by the authorization prerequisite and optional-parameter notes — a logical order. It is a bit dense, stacking an implementation note ('matches POST /api/projects/[id]/shares/token since 2026-08-19') and parentheticals into one long 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 four-parameter mutation tool with no output schema, the description covers the key facts an agent needs: what is created, the link format, the required role, and the guest-join behavior. It does not describe the returned token/link shape explicitly, 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 description coverage is 100%, so every parameter (including expectedProjectId and its refusal semantics) is already documented in the schema. The description's mentions of the 'viewer' default and allowGuests default true largely restate the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Creates a shareable invite link for a project') and even names the resulting artifact (/join/<token>), so the output is concrete. It also clarifies the mechanism is identical to the app's own 'Share' button, which removes any ambiguity about what is being produced.

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

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

Gives a clear prerequisite: a GOVERNING role (owner or manager) is required, which tells the agent when this call will succeed. It does not, however, point to any alternative or sibling tool for related sharing/permission operations, nor state when not to use it.

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

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description supplies the substantive behavior an agent cannot infer: writes require targeting the new project (expectedProjectId or set_active_project), nothing is written during the turn in the in-app chat, the sub-view inherits the host's rights and shares, and the call counts against the project cap. This is unusually rich disclosure 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 core action is front-loaded in the first sentence, and every sentence carries distinct information (targeting, refusal, rights inheritance, alternative tool). It is long and heavily emphasized with capitals and parentheticals, which costs some readability, but little is genuinely 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 complex, side-effecting creation tool with no output schema and a 100%-covered input schema, the description covers the remaining risk surface: refusal semantics, rights/share propagation, where the write actually lands, and the chat-vs-MCP targeting difference. An agent has everything needed to call it correctly or route elsewhere.

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 genuine meaning: primaryKind is framed as the place where cross-kind inception happens ('a BPMN process under an org chart block, an ERD under an architecture component'), and it clarifies that cellId is the host block that stays in this project while only a pointer is set. These reinforce rather than merely repeat the schema.

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

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

States a precise verb+resource+effect: 'creates an INDEPENDENT (empty) project and links it immediately to the host block, in a single action.' It explicitly contrasts itself with the sibling that handles the already-existing case ('A project that ALREADY EXISTS is linked with link_project_to_cell') and implicitly with create_project, so an agent can separate it from neighbors without opening any schema.

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

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

Gives an explicit when-to-use rationale (the 'inception' pattern: keep the summary on the main view, push detail one level down) and an explicit when-not/alternative (link_project_to_cell for pre-existing projects). It also states the refusal condition — 'Refuses if the block already carries a link (no project is created then)' — which is exactly the routing information an agent needs.

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

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

Annotations only say readOnlyHint=false and destructiveHint=true; the description goes well beyond that by disclosing that the active-project binding is NOT guaranteed, that the project is created regardless, and that activeProjectBound/activeProjectWarning must be inspected. Crucially it explains why a create tool carries destructiveHint — boundProject is the real session binding that a later destructive call acts on — which is exactly the context annotations cannot convey.

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 default behavior, then the return fields, then the warning — a sensible order. The final warning run is dense but every clause (setActive:false / no API key / write failure) corresponds to a distinct condition, so little 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?

There is no output schema, and the description compensates by naming the key response fields (projectId, activeProjectBound, activeProjectWarning, boundProject) and explaining how to interpret them. For a create tool with a binding side effect, an agent has everything needed to call it and verify success.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: it restates setActive's default binding behavior, confirms 'org' as the primaryKind default, and ties setActive to the activeProjectBound failure modes. It adds real semantics on top of already-complete schema docs.

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 ("Creates a new project") plus the important side effect (binds it as the active project for this API key) and the return value (projectId). It also enumerates primaryKind values, so an agent knows exactly what this produces. It does not, however, distinguish itself from close siblings like create_nested_project or set_active_project, leaving that comparison to inference.

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 when binding is and is not applied ("it is false when setActive:false, when there is no API key (chat)"), which is useful conditional guidance. But it never routes the agent between alternatives: nothing says when to prefer set_active_project, create_nested_project, or to create first and bind later. Usage is implied rather than 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?

Beyond the annotations, it discloses replay semantics via `id`, `alreadyExisted`, generated ids, `batchUrl` behavior, arbitration inheritance, unresolved assignees, archived parents, and the fact that links are added later rather than replaced. These details materially change how an agent should call and interpret the 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 description is very long and dense, with many sentences repeating schema details and using emphasized caps for concepts already documented. It is front-loaded enough to state the core create behavior first, but overall the wording is not concise and some behavioral points are buried in long parenthetical passages.

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 creation tool with no output schema, the description covers return shape, batch URL behavior, edge cases, and project targeting. An agent has enough information to understand both what will be created and what the response may contain.

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. The description reinforces important semantics such as `id` as a replay key and `dependsOn` versus `parentTaskId`, but most of that meaning is already present in the schema and it adds little new syntax or formatting guidance.

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: it creates one task as an object or up to 100 as an array. It distinguishes the two call forms and ties them to the same parameter model, so an agent can identify the tool without inspecting the schema first.

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

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

It gives clear contextual guidance: use the object form for one task, the array form for a batch, prefer `cellId` except for genuinely cross-cutting work, and use `update_task.addLinks` for later deliverables. The main gap is that it never names `import_tasks` as the alternative for bulk migration, even while discussing Linear/Jira/Notion imports.

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

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

Annotations only declare destructiveHint=true, but the description discloses far more: permanence with no trash/undo, the exact cascade (content, sharing grants, block links destroyed), what survives detached (comments, tasks, documents), and the orphanedComments/detachedTasks response flags. This is unusually rich behavioral context.

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

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

It is front-loaded with the core action and most sentences carry real information. However, the dense parentheticals and repeated clauses ('they survive (they are not destroyed)' twice) add length without new 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?

With no output schema, the description covers the return value ('Returns the complete list of what was deleted') and the conditional response fields. Everything an agent needs to invoke a destructive cascade safely 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 100%, so id, dryRun, and expectedProjectId are already fully documented in the schema itself. The description's dryRun explanation largely duplicates the schema text and it never mentions expectedProjectId's targeted-project override, so it adds little beyond 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 first sentence states a specific verb, resource, and cascade scope: 'Deletes a block and all its children, assignments and linked dependencies.' This lets an agent distinguish delete_cell from siblings like delete_content_block or delete_dependency, which target different resources.

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 when-not guidance ('This is NOT an erasure of personal data: that goes through deleting the account or the project') and an alternative recovery path (restore_version), and it prescribes dryRun:true as the way to preview a cascading deletion before committing.

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

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

Annotations already declare destructiveHint=true, but the description goes well beyond them: it discloses that the whole thread plus all its messages are destroyed (cascade), that document_range anchors also lose their document mark, and that this cleanup is best-effort with failures surfaced via `markStripNote` rather than blocking deletion. That is precisely the destruction scope and failure-mode context annotations cannot express.

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

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

Three sentences, each earning its place: the core action and scope first, the sibling contrast second, the document_range edge case and its non-fatal failure semantics third. Front-loaded and free of 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, but the description covers what gets destroyed, the alternative operation, the anchor-specific side effect, and the failure-signaling field (`markStripNote`). Nothing an agent needs in order to invoke this destructive tool 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 description coverage is 100%, so threadId's cascade behavior and expectedProjectId's targeting/access-refusal semantics are already documented in the schema. The description adds no parameter syntax, format, or interaction detail beyond that, so the baseline of 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 ('Deletes a thread and all its messages') plus the cascade scope, and explicitly contrasts itself with the sibling resolve_comment. An agent can distinguish it from resolve_comment, move_comment, and reply_comment 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?

Names the alternative operation (resolve_comment) and states the discriminating condition: it resolves without deleting, this one deletes. That is exactly the when-to-use-this-vs-that guidance an agent needs, with no inference required.

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

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

Annotations already flag destructiveHint=true, but the description adds the operationally critical detail that a missing blockId yields success-with-no-change while an unknown cell errors — a silent no-op an agent must know about. It also warns 'No dry run' and describes what the response carries (contentBudget used/available).

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

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

Front-loads what is deleted and what survives, then prerequisite, then the sibling alternative, then return shape. Roughly five dense sentences with no restatement of the name or 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 3-parameter tool with no output schema, the description covers side effects, prerequisite lookup, the silent-failure case, absence of dry run, and the response payload. Nothing an agent needs before calling 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 per-parameter docs are already covered; the description still adds meaning by telling the agent where blockId comes from and by explaining the divergent failure semantics of cellId vs blockId. expectedProjectId's project-override behavior is left entirely to the schema.

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

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

States a specific verb and resource ('Deletes ONE content block (list, text, actions or links)') and immediately bounds the scope: entries inside the block go, the block itself and its other content blocks stay. That distinguishes it cleanly from delete_cell and from update_content_block 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 prerequisite ('read the block ids with get_cell_details first') and names the alternative with the condition that selects it ('To remove a single entry rather than the whole content block, send the remaining entries with update_content_block'). No inference required.

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

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

Annotations already declare destructiveHint=true, but the description goes far beyond: permanence with no trash/undo, what is cascaded (content, sharing grants, block links), and what survives detached (comments, tasks, documents) with the re-attach semantics. It also discloses the orphanedComments/detachedTasks reporting, which annotations cannot convey.

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 permanence warning is well front-loaded, but the body repeats the same survival claim for comments and tasks after already stating it generically, and the heavy ALL-CAPS emphasis adds noise. Information is dense but not efficiently structured.

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 correctly compensates by explaining return signals (orphanedComments + note, detachedTasks + note). For a destructive cascading delete with 100% schema coverage, nothing material 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 both parameters are already documented in the schema. The description adds no syntax or behavioral detail about `id` or `expectedProjectId` (e.g., how the project override interacts with the session project), 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 ("Deletes a data-source block") plus the cascade scope ("and all its lineage connections"). The scope is precise, but it never names a sibling (e.g., delete_content_block, delete_cell) to route the agent when the block type is ambiguous.

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-not ("This is NOT an erasure of personal data: that goes through deleting the account or the project") and names the recovery alternative (restore_version). The agent knows both the boundary and the fallback 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?

Annotations already flag destructiveHint=true, but the description adds the operational consequences: no dry run, no undo besides restoring a saved version, and an error with nothing deleted on unknown id. It also discloses the non-obvious edge case that hierarchy arrows (id struct-{parentId}-{cellId}) count as dependencies and that recreation loses history.

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 scope, then consequences, then alternatives. Dense but every clause carries a distinct fact; the final sentence about update_dependency and history is slightly long-winded but justifies its length by preventing accidental history loss.

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 covers the failure case but not what a successful call returns (confirmation shape, deleted object). Otherwise the destructive semantics, id sourcing, and alternatives are all present for a 2-parameter mutation 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 100%, so the baseline is 3; the description earns above that by documenting the composite id format for hierarchy arrows, which the schema only calls 'ID of the dependency to delete'. expectedProjectId is left entirely to the schema, so it is not a full 5.

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

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

States a specific verb and resource ('Deletes ONE dependency (arrow) by its id') plus an explicit non-effect ('the two blocks it linked are untouched'), which immediately separates it from delete_cell and move_cell. The capitalized 'ONE' also signals it is a single-item operation, unlike batch siblings.

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 routing rules: re-parent blocks with move_cell rather than deleting the hierarchy arrow, read dependency ids via get_cell_details, and use update_dependency to change type/label/appearance instead of delete-and-recreate. That is explicit when-to-use, when-not-to-use, and named 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?

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds valuable detail beyond that: the deletion is permanent, irreversible, and also removes the file attachment where applicable. It does not cover permission/authorization behavior, though the schema does partially address access refusal for expectedProjectId.

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 permanent-deletion warning and followed by the alternative. Every clause 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 simple two-parameter destructive tool with no output schema and full schema description coverage. The description supplies the essential irreversibility and attachment-removal context, and annotations cover the destructive profile.

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

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

Schema description coverage is 100%, so both parameters are already documented in the input schema. The description does not add syntax, format, or side-effect information beyond what the schema provides for documentId and expectedProjectId.

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 (deletes) and resource (document) and immediately distinguishes the operation from the softer alternative update_document({archived: true}). The 'PERMANENTLY' qualifier makes the destructive scope 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?

Explicitly says this is irreversible and names the alternative tool and parameter for non-destructive removal, giving a clear when-not-to-use condition. No inference is required to choose between the two siblings.

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

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

Annotations only supply destructiveHint=true; the description carries far more: cascade at any depth, PERMANENT with no trash/undo, the restore_version caveat (replaces the WHOLE schema), which attached artifacts survive detached (comments, tasks, documents), and the orphanedComments/detachedTasks/note reporting. It is consistent with the destructive annotation, adding substantial context the structured fields do not.

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 correctly: deletion scope and permanence come first, survival semantics after. It is efficient but somewhat long and repetitive (comments and tasks each explained twice), which keeps it from 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 destructive mutation with no output schema, the description is complete: it covers cascade behavior, irreversibility, recovery, what survives, and even the return fields (orphanedComments, detachedTasks, note). An agent has everything needed to call it correctly and warn the user.

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 meaningfully enriches the `id` parameter by spelling out the cascade depth (parentId, any depth) and the full set of dependent artifacts removed. It adds little for `expectedProjectId`, which the schema already documents well.

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

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

States a specific verb (Deletes) and precisely scoped resource: an ERD entity plus every nested entity at any depth, plus all referencing artifacts (fields, relations, lineage, assignments, dependencies, data sources). The 'ERD entity / NESTED entity' framing implicitly separates it from sibling delete_cell, delete_field, delete_relation, so an agent can identify it without opening the schema.

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

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

Provides a clear when-not and alternative: it is 'NOT an erasure of personal data: that goes through deleting the account or the project,' and names restore_version as the recovery path. However it gives no positive guidance on when to prefer this over other delete_* siblings, so it stops short of a full when/when-not/alternatives 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?

Annotations already declare destructiveHint=true, so the safety profile is covered structurally. The description adds real value beyond that by disclosing the cascade to referencing relations, which is exactly the kind of 'what else gets destroyed' context the annotations cannot express. It stops short of stating irreversibility or the project-scoping refusal behavior.

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

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

Two short sentences, zero filler, with the core action front-loaded and the cascade consequence immediately following.

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 single-parameter delete with a fully documented schema and no output schema, the description covers the action and its side effect adequately. The remaining gap is irreversibility/permission context, which is partly implied by destructiveHint.

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 id parameter description already repeats the cascade note, so the prose adds essentially nothing beyond the schema. The expectedProjectId override semantics are documented only in the schema. Baseline 3 is appropriate 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 ('Deletes a field') so the agent immediately knows the operation. It does not, however, distinguish itself from neighboring destructive tools such as delete_field_lineage or delete_relation, so sibling disambiguation is left to the name alone.

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 never says when to reach for this tool versus alternatives (delete_field_lineage, update_field, delete_relation) nor any precondition. Usage is only implied by the verb 'Deletes'.

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

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

Annotations only declare destructiveHint=true; the description adds concrete destruction scope (only the traced path disappears), failure semantics (unknown id is REFUSED with nothing written), absence of dry run and undo, and two concrete recovery routes (re-trace with link_field_lineage, or restore_version which replaces the whole schema). That is materially more than the annotations provide.

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

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

Every clause carries information — scope, alternatives, error behaviour, recovery — with no filler. It is a single dense paragraph of long multi-clause sentences, which slightly hurts scannability, but 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 two-parameter destructive delete with no output schema, the description covers destruction boundary, error path, irreversibility, and recovery options. Nothing an agent needs in order to decide or invoke safely 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 description coverage is 100%, so both parameters are already documented, so baseline 3 applies. The description reinforces that `id` is the value previously returned/passed to link_field_lineage, but adds nothing about expectedProjectId's override-and-refuse behaviour beyond what the schema says.

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 ('Deletes one lineage link by its id') and immediately scopes what is and is not affected: the source block/field and target field are untouched. That scope statement alone separates it from delete_field and delete_data_source without opening any schema.

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

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

Gives the fitting case ('a link traced wrongly or a data flow that no longer exists') and explicitly routes three sibling behaviours elsewhere: mark_field_pii for PII flagging, delete_field for removing a field with its links, delete_data_source for removing a whole source block. When-to-use and when-not-to-use are both covered with named 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?

Annotations already carry destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds genuinely new behavioral information beyond the annotations: the deletion cascades to the person's assignments, which is the single most important side effect for an agent to weigh. It stops short of stating permanence or 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?

One sentence, front-loaded with the action and immediately followed by the consequence of calling it. Every word earns its place.

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

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

For a destructive, no-output schema tool the description covers the core consequence, but it omits irreversibility/undo options and any mention of the cross-project targeting behavior of expectedProjectId (left entirely to the schema). Adequate but with clear gaps for a delete operation.

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

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

Schema description coverage is 100% and both parameter descriptions are detailed, including the refusal semantics of expectedProjectId. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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