Traceable

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description still adds substantial beyond-schema context: soft-delete is recoverable, deleting a table/ID header cascades to children, and inbound links are marked broken. It also warns that atOrder goes stale after inserts and that the response echoes itemId for verification.

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

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

Three dense sentences, front-loaded with the primary action and effect, then the concurrency/freshness caveat, then the anchoring preference. No filler; each clause carries actionable 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 destructive mutation with no output schema, the description covers the essential facts: reversibility, cascade scope, link side effects, ordering freshness, and result verification. 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 coverage is 100%, so the baseline is 3, but the description earns extra credit by explaining operational semantics the schema omits — that atOrder must come from a read issued after the last insert and that itemId anchoring is preferred. It adds genuine usage meaning over the parameter 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 ('soft-delete one block') and immediately distinguishes itself from the write/update siblings by noting it is recoverable in-app with editor-equivalent semantics. An agent can tell it apart from traceable_block_update and traceable_block_write 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 a concrete anchoring rule ('Prefer itemId anchoring') and clarifies cascade behavior so the agent knows the blast radius. It stops short of an explicit comparison to the sibling update/write tools or a when-not statement, so it falls just below full routing guidance.

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

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

Annotations already cover the safety profile (destructiveHint=true, idempotentHint=true, readOnlyHint=false), but the description adds real behavioral context: inserts renumber later rows (invalidating stale anchors), page/section breaks in trmContent overwrite the row's break flags, and read-only annotations are rejected. It stops short of saying what happens to the replaced block's TraceID or its non-content metadata.

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

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

Four tight sentences, front-loaded with the action, then identification, then content constraint, then the rename escape hatch. No filler and no repetition of schema text.

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

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

For a destructive single-block mutation with no output schema, the description covers identification, freshness preconditions, break-flag side effects, and routing to the rename tool. The remaining gap is the effect on the replaced block's TraceID and metadata, plus any reference/link handling, which an agent might need.

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

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

Schema coverage is 100%, so the schema already documents all five parameters and a 3 would be the baseline. The description goes beyond it by glossing itemId as a TraceID example (FR-003), tying atOrder to the [[row N]] anchor with a freshness constraint, and constraining trmContent to exactly one block — semantics the schema descriptions do not carry.

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 ('Replace one block') and immediately scopes it to a single block, distinguishing it from a bulk or multi-block operation. It also names the sibling it is not (traceable_trace_id_rename) for the rename case, so an agent can route without opening another 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 identification alternatives (TraceID via itemId vs [[row N]] anchor via atOrder) and the precondition that atOrder must come from a read issued after the last insert. It also states an exclusion (renames not supported, use traceable_trace_id_rename), but does not contrast this tool with traceable_block_write (insertion) or traceable_block_delete.

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 idempotentHint=false, so safety is partly covered. The description goes well beyond them by disclosing the non-obvious renumbering side effect, its scope (footer rows too but not counted), the `renumbered` marker shape (`by`, `rowsShifted`), and the resulting staleness of prior row orders. It stops short of stating permission/auth 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?

Front-loaded with the core action and anchor options, and every clause carries operational information (return shape, renumbering warning). It is dense and long-sentenced, so it is not maximally scannable, but there is little 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 multi-param mutation with no output schema, the description covers the return payload (created rows, new row orders, renumbered marker), the stale-order hazard, and where the analogous write tool lives. Nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it maps afterItemId to a TraceID anchor, afterOrder to the [[row N]] anchor, clarifies position is only a fallback (default end), and notes that read-only [[row]]/[[document]] directives are rejected. That exceeds what the field descriptions alone convey.

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

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

The description opens with a specific verb and resource ('Insert one or more body blocks') and enumerates the three anchor modes (afterItemId, afterOrder, position). It actively distinguishes itself from the sibling traceable_segment_write by stating that title-page content is written there instead.

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 selection criteria for each anchor variant, names the alternative tool for title-page content, and adds operational guidance ('re-read before further order-based calls, or anchor by TraceID'). An agent can pick the right tool and the right anchor without 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-idempotent, non-destructive mutation. The description adds useful lifecycle context: calling it twice plans the document twice, and the placeholder's cardId is the bridge to traceable_doc_create. It does not cover permissions, rate limits, or error behavior, but the annotations lower the burden and the added context is substantive.

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 purpose, then parameters, then duplicate behavior, then integration with traceable_doc_create, and finally a caveat about non-placeholder cards. Every sentence contributes to correct selection or invocation, with no filler.

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

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

For a mutation tool with no output schema, the description covers purpose, required and optional inputs, duplicate behavior, and the follow-up workflow. It implies the placeholder's cardId is the returned handle but does not explicitly state return values or error conditions; that is a minor gap rather than a blocking one.

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. The description largely repeats that guidance, noting placement is a cell's phaseId and workstreamId from traceable_board_read and that position 0 is the top, but it adds little beyond 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?

The description states a specific verb and resource: planning a document as a placeholder card on a project's board. It distinguishes this from writing an actual document via traceable_doc_create and from placing a card that already holds a document. An agent can tell what this tool does and how it differs from 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 explicit routing: use this to plan a not-yet-written document, then pass the placeholder's cardId as placeholderId to traceable_doc_create. It also provides a when-not-to-use rule: a card that holds a document is not a placeholder and should be moved with the document's placement instead. Nothing essential 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 declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful scope context beyond them: deletion is limited to the plan/placeholder, and no document is deleted. It stops short of saying what happens when the cardId refers to a non-placeholder card (error vs no-op).

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

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

Three short sentences, front-loaded with the action, then the required argument, then the scope caveat. Efficient, though the provenance hint mildly repeats the schema and the title's content.

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

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

For a single-parameter mutating tool with no output schema and full annotation coverage of safety, the description supplies the necessary scope caveat. The only omission is failure behavior when cardId is not a placeholder, which matters for an agent deciding to call it.

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

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

Schema description coverage is 100% and the cardId field already documents its provenance and UUID format. The description's 'Pass its cardId (from traceable_board_read)' restates what the schema provides, adding no new syntax or constraint 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 and resource ('Remove a placeholder card from a project's board') and immediately narrows the scope to placeholder-only cards, which cleanly separates it from sibling placeholder_create/update and from document deletion tools. An agent can identify the operation and its boundary 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 the precondition (cardId from traceable_board_read) and an explicit when-not condition: a card holding a document is not a placeholder. It does not name a sibling alternative for the document case (e.g. doc_archive), so routing advice stops just short of fully explicit.

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 idempotentHint=true, destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds genuinely useful behavior beyond that: partial-update semantics ('only what changes'), the card-identity rule that determines whether this tool even applies, and the handoff to traceable_doc_create. It does not explain what becomes destructive (e.g., clearing documentType or repositioning), so it falls short of full disclosure.

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

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

Four tightly written sentences, front-loaded with the operation and its fields before the cross-tool and exclusion notes. Every sentence carries routing or constraint information; minor cost is that the cross-tool note to traceable_doc_create sits in a description for a different tool.

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

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

For a mutation tool with a nested placement object, no output schema, and destructive/idempotent annotations, the description covers the operation set, id sourcing, partial-update expectations, and the key precondition for applicability. It stops short of stating what happens when the target is not a placeholder or whether changes can be undone, which an agent would still have to discover at call time.

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 a little meaning on top: it frames the update as a partial patch ('pass ... only what changes'), identifies placement as the mechanism for moving versus title/documentType for editing, and ties cardId provenance to traceable_board_read.

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

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

States a specific verb and resource (change a placeholder card on a project's board) and enumerates the exact mutable fields (title, documentType, placement). It explicitly distinguishes a placeholder card from a card that holds a document, so an agent can separate this from traceable_board_placeholder_create/delete and from document-placement operations 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 affirmative routing (use this to change/move a placeholder; pass the placeholder's cardId as placeholderId to traceable_doc_create to write the planned document) and an explicit exclusion (a card holding a document is not a placeholder — move it with the document's placement instead). Both when-to-use and when-not-to-use are stated 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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value beyond that by disclosing the return shape: cells addressed by phaseId/workstreamId, human-readable labels, ordered card lists with cardIds, and documents not on any cell. No pagination or size limits mentioned, keeping it below 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?

Two sentences, both dense but front-loaded with the purpose before the return shape and the follow-up routing. No filler, though the second sentence is long and carries multiple clauses that could be split for scanability.

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

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

With no output schema, the description carries the burden of explaining return values and does so thoroughly — board variant, cell address fields, label format, card ordering, and orphan documents. It omits any note on board size or truncation, which is the only meaningful gap for a whole-board read.

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?

Only one parameter and schema description coverage is 100%, so the schema already documents projectId including its source (traceable_workspace_projects). The description adds nothing parameter-specific beyond 'a project's board'. 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 ('Read a project's board') and immediately disambiguates the two variants: the Design Phases board for product/process projects versus the quality system diagram for Quality projects. An agent can tell this apart from traceable_grid_cell, traceable_workspace_map and traceable_doc_read 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?

Explicitly routes the agent: take a cell's phaseId/workstreamId and pass it as 'placement' to traceable_doc_create, traceable_doc_update_meta, or traceable_board_placeholder_create. That is concrete downstream guidance with named alternatives. It stops short of stating when NOT to use this versus other read tools, so not a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds no behavioral context beyond a content inventory — nothing about return format, size, caching, or whether the manifest is static, which matters for an agent deciding whether to call it repeatedly. Appropriate at 3 given the annotation coverage.

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 what the tool returns and ending with the when-to-use instruction. The mid-sentence enumeration of six content categories is informative but slightly list-heavy for the value it adds.

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 burden of indicating what is returned, and listing row types, directives, segments, tokens and paper sizes does that adequately for a zero-parameter reference tool. Minor gaps remain about format and reuse, but nothing essential for correct 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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. The content enumeration loosely maps to what callers will need, but no parameter semantics are required.

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

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

The description names the specific resource (TrMD format spec and capabilities manifest) and enumerates its contents (row types, block directives, segments, property tokens, paper sizes), so an agent knows exactly what comes back. It stops short of an explicit verb, resting on a noun phrase, but it is clearly distinguishable from every sibling tool since none other retrieves the format spec.

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

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

"Read this before reading or authoring documents" gives a concrete trigger condition and ordering relative to the sibling read/write tools. It does not need alternatives because no other tool serves this purpose, but it also doesn't state what happens if it's skipped.

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?

Despite annotations covering write/idempotency, the description adds substantial non-obvious behavior: trace links are marked broken and shown as gaps, restoring in-app heals them, review state blocks the call, and archiving is idempotent. This is richer than the annotation set and not derivable from it.

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?

Packed with actionable facts and front-loaded with the core action, but several clauses (trace-link healing, deletion policy) read as a run-on; a slight trim would improve density without losing content.

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

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

Covers operation, side effects, failure modes, idempotency, lifecycle limits (no delete by agents), and a recommended usage scenario, fully sufficient for a one-parameter mutation 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 coverage is 100% and the single parameter (documentId UUID) is fully documented; the description adds no per-parameter detail. 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 the specific verb+resource (archive a document) and anchors it to a known app action ('as the app's Archive action does'), which grounds the semantics beyond the bare name.

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

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

Gives explicit preconditions and exclusions: refused under review, no-op if already archived, agents cannot delete, and a concrete use case ('retire a superseded document after replacing it'). An agent knows when and 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower; the description still adds non-obvious behavior: trmContent is APPENDED after the template body, only default header/footer bands are seeded for segments trmContent omits, and the call returns documentId plus created rows with row orders. It does not disclose permission requirements or any rate limits, keeping it out of the top band.

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 organized by concern (template, content, composition, board placement, placeholder, returns). It is long and somewhat run-on with many parenthetical cross-references, but the length is largely justified by a 10-parameter tool with nested placement and no output schema; the test-report and composition sentences are the most tangential.

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 create tool with 10 parameters, a nested placement object, and no output schema, the description covers template interaction, content append semantics, board placement, placeholder consumption, and the return shape. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns an upgrade by explaining interactions the schema cannot, notably that templateId clones an org/system template including bands and revision/signature scaffolding, that trmContent is appended after the template body, and that placeholderId makes the document take the placeholder card's cell and position. It does not add syntax guidance for idPrefix or documentType 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?

Opens with a specific verb+resource ("Create a document in a project") and immediately differentiates itself from read/update/archive siblings by describing clone-from-template, append, and placement behavior. An agent can distinguish this from traceable_doc_read, traceable_doc_update_meta, and traceable_block_write 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 routes to alternatives and conditions: discover templates via traceable_workspace_templates, read the template first with traceable_doc_read before appending, use traceable_block_update/delete to change template rows, and traceable_block_write with afterOrder to nest under a template heading. It also states what happens without a template (only default bands seeded), which is a genuine when-not branch.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds substantial context on top: the revision=value on the [[document]] line is meant to be passed as baseRevision so a later write is refused on conflict, incoming cross-document links are returned as a second grouped block, and a bounded read only returns links into the rows it covers. It also discloses empty-range behavior ('says so and gives the row orders the document spans').

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 nearly every sentence carries load-bearing detail about modes, revision handling, or link output. It is dense and contains long parenthetical sentences (the outline enumeration, the revision sentence) that could be broken up for easier parsing, but there is little outright 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, so the description must carry return-shape information — and it does: meta.revision, outline contents (headings, titlePageHeadings, landmarks, item counts, references with referenceId), and the TrMD block format with [[row N]] anchors and ID-grid structure. For a read tool of this complexity, 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema strings: it defines what outline vs full actually return, states outline is the default, and clarifies that fromOrder/toOrder take 'row orders from the outline or a prior read'. That is operational semantics the schema's terse 'First row order to include' does not convey.

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

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

Opens with a concrete verb+resource ('Read a document or a template') and immediately characterizes the two modes, so an agent knows this is the document reader. It does not explicitly contrast itself with sibling readers like traceable_board_read, traceable_test_plan_read, or traceable_library_read, leaving that distinction to inference from the resource name.

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

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

Gives real routing guidance: outline is 'cheap; default when exploring', full is for content, and a full read should be bounded with fromOrder/toOrder 'to load only a section'. It also states a concrete precondition/alternative — accept a template id from traceable_workspace_templates to inspect a body before cloning with traceable_doc_create. It stops short of saying when NOT to use this tool versus other read 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?

Goes well beyond the annotations by enumerating exactly what is rewritten (traceable rows, native-table trace cells, ID-grid id cells) and what is not (plain text, other rows without a TraceID, prefix written as prose). It also states that trace links are preserved and that only human-readable ids change, plus the editable-draft requirement, giving the agent real mutation semantics for a destructiveHint=true 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?

Four dense sentences with no filler, and the core action and its scope are front-loaded. Every clause earns its place, though the prose is on the heavier side for a two-required-param tool.

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

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

For a mutation tool with no output schema, it covers mutation scope, what is left untouched, link preservation, and the draft precondition, and the schema supplies the revision idiom. The only gap is the absence of sibling routing against traceable_trace_id_rename.

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 documentId, newPrefix (with format constraints), and baseRevision in detail. The description adds no parameter-level syntax or format 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.

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

States a specific verb (Rename) and resource (a document's TraceID prefix) and details the scope of the rewrite across traceable rows, native-table trace cells, and ID-grid id cells. It is clear what the tool does, but it never names or distinguishes itself from the sibling traceable_trace_id_rename, leaving that boundary 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?

Gives a clear precondition (the document must be an editable draft; published documents are read-only) and an implicit alternative exclusion ("you do NOT need to recreate the document to re-prefix it"). It does not explicitly say when to pick this over traceable_trace_id_rename, so it stops short of full routing guidance.

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

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

Annotations supply readOnly=false, destructiveHint=true, and idempotentHint=true, so the bar is lower; the description still adds useful non-obvious behavior: 'Only the fields you pass are changed' (partial-update semantics), 'Placement changes no document content and opens no new draft' (limits perceived blast radius), and the numberedHeadings auto-numbering side effect. It does not contradict destructiveHint, though it leaves the destructive nature of a metadata write somewhat implicit.

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

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

Front-loaded with the field list, then constraints and sibling routing; every sentence carries information. Dense but slightly long, with parentheticals that could be tightened, 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?

For a 7-parameter mutation tool with no output schema, the description covers scope, partial-update behavior, placement sourcing, and the prefix alternative. It does not state whether a new revision/draft is otherwise triggered for content fields or what the response contains, but annotations carry safety and the absence of an output schema limits the obligation.

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 goes beyond the schema by explaining that placement uses a cell's phaseId/workstreamId sourced from traceable_board_read and that null removes the document from the board, and by describing the practical workflow implication of numberedHeadings.

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 (update) and resource (document metadata) and enumerates exactly which fields are in scope: name, number, type, group, numberedHeadings, and board placement. It explicitly names the sibling it is not (traceable_doc_rename_prefix for TraceID prefixes), so an agent can separate it from that tool 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 concrete when-to-use routing: use traceable_board_read to obtain placement ids, use traceable_doc_rename_prefix for prefix changes, and consult the headingNumbering note in traceable_capabilities. It also states a when-not condition ('it is not settable here') that prevents a common mis-invocation.

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 idempotentHint and destructiveHint=false, but the description adds side effects they cannot express: creating the Glossary row at the end of the body if none exists, silently creating a new organisation glossary term, requiring `description` in that case, and the admin-gated 'Agents can fill a Glossary' setting for controlled releases. This is rich behavioral context beyond the 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 action, then placement, then identification, then creation semantics, then idempotency, then the auth caveat. Dense but each clause carries information; only the parenthesis about [[glossary]] is slightly incidental.

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

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

For a 6-parameter mutation with annotations but no output schema, the description covers conditional parameter requirements, side effects on the org glossary, idempotency, and permission gating. The main omission is any indication of what the call returns or how errors surface, which is minor given no output schema is declared.

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

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

Schema coverage is 100% and the schema already documents every parameter, so the baseline is 3. The description nonetheless adds conditional semantics the schema does not: description is required only when the term is new, kind/categories apply only to new terms, and termId and term are alternative identifying paths. That conditional logic is genuine value-add.

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

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

States a specific verb and resource ('Add a term to this document's Glossary') and immediately distinguishes itself from the read-side sibling by pointing to traceable_glossary_search as the source of termId. An agent can tell it apart from glossary_search and from block-writing tools 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 concrete guidance: reference an existing term via termId from traceable_glossary_search, or pass raw text in `term`. It also explains the placement alternative ('write [[glossary]] there first') and the controlled-release prerequisite. It stops short of an explicit when-to-use-vs-alternatives rule, but the routing is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds value by disclosing the return shape, case-insensitive matching, and the admin-enablement gate on controlled-release organisations. It omits pagination/limits, but 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?

Front-loaded with the primary action and mode split, then return fields, then downstream usage, then the precondition. Every clause carries information, though the final controlled-release sentence is a long subordinate clause that slightly taxes readability.

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 compensates by enumerating returned fields, and it covers both modes, the enablement precondition, and how the returned id is consumed. For a two-parameter read-only search there is nothing an agent needs 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 coverage is 100%, so the baseline is 3, but the description genuinely adds matching semantics that the schema lacks: the search is case-insensitive and matches against both term and description text. documentId is described as the document whose glossary is searched, consistent with (but not richer than) 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?

Names a specific verb and resource with two clear modes: listing the organisation glossary a document draws on, or searching terms whose term/description contains `query`. It also discloses the returned fields (id, term, kind, description, categories), so the agent knows exactly what comes back. It differentiates from the sibling add_term by pointing at it as the downstream consumer, though it does not explicitly name a competing search 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?

Gives clear context for both invocation modes (omit query to enumerate, supply query to filter) and states a concrete precondition: in controlled-release organisations the tool only works once an admin enables 'Agents can fill a Glossary'. It does not state exclusions versus alternatives or error behavior, but the conditions for correct 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 already declare destructive/idempotent/not-read-only, yet the description adds substantial context beyond them: link/identity preservation, per-type value normalization (PASS/FAIL, checkbox true/false mappings, dropdown case-insensitive matching with refusal), image syntax, and link-cell non-settability. The prominent 'NON-DESTRUCTIVE' framing sits in tension with destructiveHint=true, though it is explicitly scoped to identity and trace-link survival rather than to the prior value being overwritten, so it does not logically contradict the annotation.

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

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

A single dense paragraph that front-loads the core action before the qualifiers. It is information-dense with no filler, though the many inline normalisation clauses would scan better as a short list; still appropriately sized for the tool's complexity.

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 five parameters, a nested row object, and no output schema, the description covers purpose, alternatives, non-destructiveness, and value semantics. Return/revision behaviour is covered by the schema's baseRevision description, so little is missing; only the response shape is left implicit.

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 baseline is 3. The description goes beyond the schema by defining how `value` is interpreted per column type (raw text, image markup, PASS/FAIL normalisation, checkbox booleans, dropdown option matching) and by restating the itemId/atOrder row-identification contract, which materially aids correct invocation.

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 (Set), resource (one ID-grid cell's value), and scope (identified by id-ROW and 0-based colIdx). It is immediately distinguishable from siblings like traceable_segment_write, traceable_link_create, and traceable_image_upload, which it names 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 when-not and alternatives: link cells are not settable here, use traceable_link_create; images are uploaded with traceable_image_upload; contrast with traceable_segment_write which breaks links. An agent knows exactly which sibling to pick under which 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?

The annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, but the description adds substantial context beyond them: every id-row gets a fresh empty cell, existing cells and trace links are preserved, and calling it twice adds two columns (confirming non-idempotence). It also clarifies the identifying mechanism (header row) and contrasts with traceable_segment_write's destructive replacement 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?

The description is front-loaded with the core action and efficiently packs important constraints and alternatives into a few sentences. Every sentence adds value, though it could be slightly tighter (e.g., the header identification sentence and the cell-value pointer could be separated more cleanly). It is concise but not maximally 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?

Given the tool's complexity (a non-idempotent mutation with nested header identification and revision control) and the rich schema with 100% parameter coverage and annotations, the description provides all the behavioral context an agent needs: what happens to existing data, non-idempotence, the one-id-column constraint, and how to identify the grid. It also points to the right sibling for cell value changes, completing the picture.

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 input schema already documents every parameter and its meaning. The description reiterates that type is required, insertAt is 0-based with append default, and label defaults to the type's default, but it does not add syntax or format details beyond the schema. Baseline 3 is appropriate when the schema already 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?

The description states a specific verb and resource: 'Add a column to an ID grid.' It distinguishes this tool from siblings like traceable_grid_column_rename, traceable_grid_column_set_type, and traceable_grid_cell by explaining that this adds a new column while those handle other operations. An agent can identify the tool's exact purpose 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 explicitly says when to use this tool versus alternatives: use traceable_grid_cell to set a cell's value, and note that traceable_segment_write replaces the whole grid and breaks links, unlike this tool. It also states constraints like only one id column allowed per grid and that calling twice adds two columns. This is explicit 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 destructive=true and idempotent=true, and the description supplements this with concrete preservation semantics: existing cells and trace links survive, only the header text changes. It does not, however, explain permission requirements or how the returned revision interacts with a refused write (that detail lives in the schema).

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

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

Four tight sentences, front-loaded with the action and its scope, then usage, then the alternatives. No sentence is filler; each adds either scope, routing, or preservation 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 with no output schema, the description covers what changes, what is preserved, how to identify the target, and which sibling to use instead. Remaining details (revision handling, UUID format) are already carried by the fully described schema and annotations.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a useful clarification beyond the schema: the header identifies the GRID, not the column being renamed, and colIdx/label are the operative inputs. It stops short of adding format or edge-case detail for baseRevision.

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 ('Rename an ID-grid column: change its header text in place') and immediately bounds the change ('leaving its type and cells alone'). It is readily distinguishable from siblings like traceable_grid_column_set_type and traceable_grid_cell.

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 triggering scenario ('correct a mislabeled header (e.g. a default "Column")') and names the alternative to avoid ('unlike traceable_segment_write, which replaces the whole grid and breaks links'). It also routes the neighboring case ('To set a CELL's value use traceable_grid_cell'), so when/when-not is fully covered.

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

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

Annotations already carry destructiveHint=true and idempotentHint=true, but the description adds real value beyond them: existing cells and trace links are preserved (contrasted with segment_write), and "only one id column is allowed per grid" is a validation constraint found nowhere in the structured fields. It stops short of saying what happens to cell values that cannot survive the type conversion (e.g. text -> dropdown), which is the remaining behavioral gap.

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

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

Purpose is front-loaded in the first clause, followed by parameter guidance, a constraint, and then sibling exclusions. Every sentence earns its place and none is repetition of the schema or title.

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

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

For a 6-parameter mutation tool with nested objects and no output schema, the description covers usage, constraints, and preservation semantics well. It does not state what the call returns (the schema's baseRevision note mentions the revision is returned, but the description itself leaves the response shape implicit).

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

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

Schema coverage is 100%, so a baseline of 3 is warranted, but the description adds concrete config shapes that the schema only abstracts ("{ \"op\": \"product\", \"sources\": [1,2] } for a calculation") and clarifies that header identifies the HEADER row specifically, not just "a row".

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 ("Change an ID-grid column's type, converting each id-row cell to it") and explicitly distinguishes itself from two siblings, traceable_segment_write (which replaces the whole grid and breaks links) and traceable_grid_cell (for setting a cell value). An agent can route correctly 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 alternatives with the exact conditions that select them: use this tool to preserve links, use traceable_segment_write only when replacing the whole grid is acceptable, and use traceable_grid_cell to set a CELL's value rather than its type. It also gives the grid-identification rule (HEADER row via header.itemId or header.atOrder), which is the main invocation decision.

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 mark it as a non-read, non-idempotent, non-destructive write, and the description adds real substance beyond that: format is detected from bytes not name, a 3 MB cap, that calling twice uploads twice (consistent with idempotentHint=false), foreign/data: URI refusal, and the controlled-release gate. This is rich context the annotations alone do not 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 return value are front-loaded in the first sentence, and subsequent sentences each carry distinct constraints (formats, size, placement, permission). It is dense and long for a single paragraph, but almost no sentence 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?

There is no output schema, yet the description fully describes the return shape ('The result's `trmd` is ') plus the width/align suffix syntax, so an agent knows how to consume and place the result. Combined with format, size, and permission constraints, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: format is inferred from the bytes rather than the `name`, and `content` is base64 with an accepted data: prefix. It also explains what `name` drives (the default alt) and that only app-held srcs are writable.

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 ('Upload an image to a document') and names the concrete outcome ('get back the src to place it with'). This clearly separates it from traceable_image_view, traceable_library_upload, and traceable_test_plan_evidence_upload, so an agent can select it without opening schemas.

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

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

Explicitly says uploading places nothing by itself and names the four tools that actually place the image (traceable_block_write/update, traceable_segment_write, traceable_grid_cell), including where the src goes. It also gives the when-not condition (SVG refused, external/data: URIs refused) and the admin-enablement prerequisite.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world, but the description adds substantial non-obvious behavior: the result is a reduced copy (max 512px on the long side) with metadata stripped and is NOT the stored file, and every view is written into the document's agent change record so reviewers see what was read. It also discloses the admin-enablement dependency. This is exactly the kind of context annotations cannot carry.

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

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

Front-loaded with the action, then inputs, then return shape, then side effects, then the gating condition. Every sentence carries distinct information with no restatement of the name or title.

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, so the description must, and does, specify the return payload (reduced image, name, size, full dimensions) as well as the audit side effect and availability gating. Nothing an agent needs to invoke 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 description coverage is 100%, so the baseline is 3. The description still adds value by showing the expected src format inline ('') and by tying 'crop percentages' to the returned full dimensions, clarifying how src relates to the cursor/crop context. No further syntax or edge-case detail is given.

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 ('Look at') plus resource ('an image in a document') and immediate scope qualifier ('a document you can read'). It is clearly distinct from the sibling traceable_image_upload (view vs. upload) and traceable_doc_read, so an agent can route 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?

States a precondition ('Only an image the document holds can be viewed'), the correct input convention ('src exactly as a read of the document shows it'), and an environmental gate (admin must enable the tool under Org settings > Releases when controlled releases are on). It does not name an alternative sibling for the case where the image must be uploaded first, so it stops short of full routing guidance.

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

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

Annotations already declare non-readOnly, idempotent, non-destructive, but the description discloses a non-obvious side effect the annotations cannot: a Reference Table row is created at the end of the body if absent. It also restates idempotency concretely ('re-adding an existing reference succeeds without duplicating it'), which is real 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?

One dense paragraph that front-loads the primary action and side effect, then folds in routing, exclusivity and the citation syntax. Nothing is padded, though the single-block format makes some secondary rules (e.g. cite:<referenceId> syntax) easy to lose.

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, so the description carries the return burden and does so: it names referenceId and shows its use as [label](cite:<referenceId>). Combined with the side-effect and exclusivity notes, an agent has everything needed to call this 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by enforcing mutual exclusivity (exactly one of code_or_id / targetDocumentId), explaining the default for referencedVersion (target's current/published version), and giving the REF-code format example.

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

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

States a precise verb and resource: attach a Reference Library item or another document to this document's reference list. It also names the sibling tools involved (traceable_library_search for codes, traceable_segment_write for placing the table), letting an agent separate it from the other traceable_library_* 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 states the exactly-one rule between code_or_id and targetDocumentId, tells the agent to pre-write [[reference-table]] when a non-default location is wanted, and points to traceable_library_search for obtaining codes. When-to-use and the key alternative path are both covered.

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

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

Annotations declare readOnlyHint=false and openWorldHint=true; the description usefully explains the underlying behavior — text extraction runs locally for docx/spreadsheets/CSV/markup while webpage items are fetched (supporting the openWorld hint) — and discloses the persisted side effect. It also enumerates outcome states (character count, unsupported, noContent), which goes well beyond the annotations, though it omits auth/permission or size-limit 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?

Three sentences, front-loaded with the purpose, then supported types, then return states in a predictable order; no filler. It is dense and slightly long for a one-parameter tool, but every clause carries information, so it is close to optimal.

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 describing the return values (character count, unsupported=true, noContent=true plus note), and it covers the single parameter and the idempotent/persistent nature of the operation. Missing only edge detail such as re-indexing behavior or extraction limits.

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

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

There is a single required parameter and schema coverage is 100%, so the schema already documents the REF code versus UUID forms. The description only restates 'identified by its REF code or id' and adds no format, validation, or fallback guidance beyond the schema — the baseline 3 for a fully-covered single param.

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 ('Extract and persist the plain text of a Reference Library item') with a named input key, and explicitly differentiates the outcome from siblings by naming traceable_library_search as the beneficiary. An agent can distinguish this from traceable_library_read or traceable_library_upload 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?

The description gives a clear motivating context ('so it becomes searchable ... and cheap to read') and names the downstream sibling tool, which tells the agent when this step is worth invoking. It stops short of explicit when-not-to-use guidance or prerequisites (e.g., whether the reference must be added first), so it does not reach 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?

Goes well beyond the annotations by disclosing that stored indexed text is returned when available, otherwise extraction happens on the fly without persisting, and that unsupported types (PDF, PowerPoint, images) return empty text with an explanatory note. These are non-obvious behaviors an agent needs to interpret results correctly.

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

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

Front-loads the core action, then layers in caching behavior, the unsupported-type edge case, and the alternative in three dense sentences with no filler. Every sentence earns its place.

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

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

For a one-parameter read tool with no output schema, the description surfaces the caching semantics, the empty-text failure mode for unsupported types, and the escalation path. Nothing an agent needs to call it and interpret its result 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% and the schema already documents code_or_id as a REF code or UUID. The description restates the same accepted forms with an example, adding only marginal value over the structured field, so the baseline of 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 ('Return the extracted plain text of a Reference Library item') and names the identifier form. It implicitly distinguishes itself from library_index, library_search, and library_upload, so an agent can route correctly 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?

Clearly scopes when this tool applies (reading extracted text by REF code/id) and points to traceable_library_index when the goal is persisting text for search. It doesn't explicitly contrast with traceable_library_search, but the when/when-else context is clear.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral context: substring/case-insensitive matching with no semantic search, snippet-around-first-hit output, and the hard constraint that unindexed items are invisible to search. The indexing caveat is a non-obvious, consequential trait.

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 two modes are front-loaded and each sentence carries information, but the description is dense and somewhat run-on, packing search semantics, return shape, and the indexing caveat into contiguous prose. Nothing is wasted, though a bulleted mode split would read faster.

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 carries the burden of describing return values for both modes (matched fields + snippet; REF code, name, kind, file type, scope, indexed flag). Combined with access-scope and indexing caveats, 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 real meaning beyond the schema: it enumerates the searchable fields (name, REF code, extracted text) and clarifies the access scope for `organisationId` (org items plus projects you are a member of). The only thin spot is the exact format of the returned snippet.

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 (find/library items) and explicitly splits the tool into two modes: keyword search with `query`, full listing without it. It distinguishes itself from siblings by naming `traceable_library_index` and describing exactly what is searched (name, REF code, extracted text).

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 tells the agent when to use each mode (with vs without `query`) and, crucially, what to do when a search returns empty: list first and check the indexed flag, then run `traceable_library_index`. This is actionable routing guidance, not 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 declare only a mutation profile (readOnly=false, idempotent=false, destructive=false); the description adds substantial context beyond that: the 3 MB limit, non-idempotent duplicate behavior, immediate text indexing, the org-settings gating, and the returned citation syntax. No contradiction with 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?

One dense paragraph that front-loads the core action, then layers constraints and the sibling alternative. Nearly every sentence earns its place, though the prose is packed and could be broken into shorter units for faster scanning.

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

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

With no output schema, the description compensates by describing the return values (REF code, the referenceId used in [label](cite:<referenceId>)) and indexing behavior. Given six parameters and a mutation profile, this is complete enough for correct invocation.

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

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

Schema description coverage is already 100%, so the baseline is 3. The description still adds meaning beyond the schema by explaining that `title` defaults to the file name, that `number` is the reference's own designation, and that `content` is base64 with an optional data-URL prefix, clarifying parameter intent and defaults.

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

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

The first sentence states a specific verb (upload) and resource (reference file to the document's project Reference Library), including the default side-effect of adding it to the document's references. It is clearly distinguishable from the sibling traceable_library_add_reference, which it explicitly names.

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 route (traceable_library_add_reference for files already in the library), warns that calling it twice files the file twice, states the 3 MB ceiling and tells the agent to upload larger files in the app, and notes the controlled-releases/admin prerequisite. Both when-to-use and when-not-to-use are covered.

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

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

Annotations cover the safety profile (idempotentHint=true, destructiveHint=false, readOnlyHint=false), and the description adds substantial behavior beyond them: idempotency is on the PAIR not the direction, existingDirection reports same/opposite, warnings explain suppressed chips and cycles, placedInColumn reports the column used, and the column-choice fallback chain (first output link column → first link column → pinned edge with warning) is fully disclosed.

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?

Eight sentences is long, but each carries distinct load-bearing information (idempotency semantics, direction, column placement, warning cases) and the core action and pair-idempotency rule are front-loaded. Slightly dense, but minimal waste.

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

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

No output schema exists, yet the description explains the meaningful return signals (existingDirection, warning, placedInColumn) and every edge case that affects whether a chip becomes visible. For a 6-parameter mutation tool, 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 coverage is 100% so the baseline is 3, but the description adds real meaning for toColumnIndex (defaults to the row's first OUTPUT link column, falls back to first link column, can be overridden) that the schema only restates more briefly. It does not extend meaning for baseRevision or the four required IDs 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+resource (create a trace link) and immediately scopes it: between two TraceIDs, resolved server-side within one project, addressed by the TraceID pair. It also names the sibling that performs the inverse operation (traceable_link_delete), so the agent can partition the create/delete pair 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 clear conditions: use this to add an edge, use traceable_link_delete to remove one, and it explains what happens when an edge already exists in either direction (nothing is written, existing edge returned). It does not explicitly state when to prefer this over other write tools in the family, but the create/delete routing is explicit.

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, idempotentHint=true and readOnlyHint=false, but the description adds real behavioral detail beyond them: it removes both the edge and the chip from the source row's link cell, and it fails atomically ('nothing is deleted') with an explanatory error when the pair exists only in the reverse direction. That is meaningful failure-mode 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?

Three tight sentences, front-loaded with the action, then addressing convention, then effect. The final clause explaining why direction is enforced is slightly rhetorical but justifies the constraint 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 mutation with no output schema, the description covers the effect (edge plus chip removal), atomic failure on direction mismatch, and defers concurrency handling to the baseRevision schema text. Safety and reversibility are carried by annotations. Only the result shape and any permission requirements are 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 from/to UUID and TraceID parameters, including the baseRevision concurrency note, are already documented in the schema. The description's emphasis that direction carries meaning adds interpretation to the from/to ordering, but it does not supply syntax or format 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?

States a specific verb and resource ('Delete a trace link between two TraceIDs') and immediately differentiates itself from the sibling traceable_link_create by specifying that it uses the same pair-addressing convention. An agent can distinguish this from create/update siblings 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?

Usage is implied by the verb and by the note that direction must match an existing link, but the description never states when to prefer this over traceable_link_create or traceable_link-related siblings, nor any preconditions beyond the direction constraint. The traceable_link_create mention is a reference for addressing, not an alternative-selection 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?

Even though annotations already declare destructiveHint=true and idempotentHint=true, the description adds the concrete consequence — existing rows are soft-deleted and links to them marked broken — plus the rejection of read-only annotations. This is valuable beyond the flags, though the revision-conflict mechanics live mostly in the schema rather than here.

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 sibling comparison before drilling into directive syntax. It is dense and fairly long, but nearly every clause carries operational detail an author needs; only the column/grid syntax could plausibly be deferred to traceable_capabilities, which it already references.

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 bulk-write tool with no output schema, the definition covers scope, side effects, alternatives, edge cases, and authoring syntax. An agent has enough to invoke it correctly without further lookup.

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 earns above baseline by explaining trmContent directive syntax ([[column-start]]/[[column-break]]/[[column-end]], [[id-header]]/[[id-row]]) and the title_* segment semantics that the schema only labels as 'Which segment to replace.'

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 — 'Replace a whole segment' — and immediately labels itself 'the primary bulk-authoring tool,' which positions it against the block-level siblings. An agent can distinguish it from traceable_block_write 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?

Explicitly routes incremental edits to traceable_block_write/traceable_block_update, and explains the title_* edge case (content stores but will not render until the title page is enabled). Both when-to-use and an important exception are covered.

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

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

Goes well beyond the annotations: the entry belongs to the plan (not the document) and survives document archive/delete, validation and limits match the editor, result is derived from steps when a protocol has steps, and "" clears a value. These are non-obvious behaviors an agent would otherwise get wrong.

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 payload shape, then scope, then columns, then step behavior, then cross-references. Dense and long, but nearly every clause carries actionable information; the column list is lengthy though necessary given the free-form fields map.

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?

Mutation tool with no output schema, yet the description covers scope persistence, validation parity with the editor, derived-vs-explicit result rules, the review state, agent-inapplicable signature, and where evidence belongs. Nothing material is left for the agent to infer.

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% but the `fields` map is a free-form string map with no key/value constraints, so the description carries the real semantics: it enumerates every valid column and its allowed values (decision include|exclude, result pass|fail|"", resolution passed|failed|passed_with_deviation|failure_accepted) and redefines the `step` field set. This compensates for enums absent from 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: 'Record data in one Test Plan entry', with the primary payload shape ({column: value}). It is clearly separable from traceable_test_plan_read (retrieval) and traceable_test_plan_evidence_add (evidence), which it names.

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?

Routes evidence work to traceable_test_plan_evidence_add explicitly, states that the Tester signature cannot be applied by an agent, and notes the row goes to review — all conditions an agent needs to decide whether this is the right call and what will happen next.

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 cover the safety profile (idempotent, non-destructive, not read-only), and the description adds real behavioral context on top of that: the idempotent no-op behavior, the lifecycle/scope rule that entries belong to the plan and survive document archive/delete, cross-document visibility via boundDocuments, and the side effect that the row goes to review.

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, then prerequisites, alternatives, and scope. It is somewhat long, but nearly every sentence carries distinct routing or behavioral information, with only minor overlap on the reference naming already in the schema.

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, the definition covers the prerequisite dependency, alternative tools, idempotency, and the plan-vs-document ownership model plus the review side effect. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents row resolution, step numbering, entry identification, and the reference format. The description restates REF-code/item-id naming and the chip/citation-format behavior, but adds no syntax or format detail beyond what the schema provides; 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 ('Attach file evidence to a Test Plan entry (or one of its test steps)') and immediately scopes it against siblings by naming traceable_library_add_reference and traceable_test_plan_evidence_upload. An agent can distinguish it from evidence_upload and evidence_remove 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 explicit routing: add the reference first with traceable_library_add_reference, upload new files with traceable_test_plan_evidence_upload, and notes that re-attaching existing evidence is a no-op. Prerequisites, alternatives, and edge conditions are all covered.

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

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

Beyond the destructiveHint/idempotentHint annotations, it discloses genuinely valuable behavior: the library item is preserved, entries are shared across every document bound to the plan (boundDocuments from traceable_test_plan_read) and survive archiving/deletion of this document, and the affected Test Plan row is pushed into a review state.

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, followed by a clarification of non-deletion and then ownership/persistence semantics. Every sentence carries information, though the persistence paragraph is somewhat long for the value it adds.

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

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

For a 5-parameter mutation tool with nested objects and no output schema, the description covers side effects, scope, and persistence well. Minor gaps remain: it doesn't state permission/auth requirements or whether the uploaded file itself (versus the library item) is retained.

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 row/entry/reference/step. The description adds limited extra meaning ('by REF code or item id, whichever document attached it'), which closely mirrors the schema's own description of the reference parameter. 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+resource (remove file evidence from a Test Plan entry or step) and immediately bounds the scope by clarifying that the Reference Library item itself is not deleted. This clearly separates it from the sibling evidence_add and evidence_upload 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?

The description establishes clear context for when to use it: to detach a file reference while explicitly preserving the underlying Reference Library item, implying a different tool is needed for true deletion. It does not, however, explicitly name an alternative tool or state hard exclusions, so it stops 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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false): it discloses that type detection is byte-based not name-based, that non-images are added to the Reference Library and indexed for search, that entries live on the plan rather than the document and survive archival/deletion, and that the row is moved to review. This is unusually rich side-effect 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?

Purpose is front-loaded in the first sentence, then behavior follows in a dense but information-rich block. It is long, but nearly every clause carries a distinct operational fact; a slightly tighter grouping of the plan-vs-document semantics would improve 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 6-parameter, nested-object mutation tool with no output schema, the description supplies the missing pieces: size limit, idempotency, downstream indexing behavior, scope/persistence of entries, and the review side effect. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the nested row/entry identification. The description restates the base64/name convention but adds little parameter-level meaning beyond the schema, 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 ('Upload a file as evidence on a Test Plan entry (or one of its test steps)') and scopes it precisely. It is clearly distinguishable from siblings like traceable_test_plan_evidence (read/list) and traceable_library_upload, and even names the read tool that supplies the identifiers.

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 operational context: how the file is passed, what happens for images vs other types, the 3 MB cap, and that repeat calls upload twice. It does not explicitly route between alternative upload tools (traceable_image_upload, traceable_library_upload), 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 readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds real behavior: archived documents are marked archived=true and sorted last, entries follow protocol-join order and do not reorder when a protocol is moved later, and steps are numbered from 1. It stops short of saying anything about size or response envelope, but the ordering semantics are genuinely valuable.

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 content is front-loaded with the resource, which is good, but it is delivered as one extremely long run-on sentence with a stacked parenthetical list of column names. Every clause carries information, yet the structure makes it hard to scan; breaking the ordering rules and return fields into separate sentences would help.

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, so the description must carry the return contract, and it does: it names each returned component, the entry-level attributes, the evidence REF hook, and the ordering behavior. Nothing an agent needs to interpret the result of this nested-object read is missing.

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

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

Schema coverage is 100%, and the schema already explains that `row` takes itemId or atOrder ('pass one') and that documentId holds the row. The description adds no formatting or disambiguation guidance beyond the structured fields, 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 ('Read a bound Test Plan row') and then enumerates exactly what the read returns: plan, bound documents, columns, entries, evidence, signatures and protocol steps. It is clearly distinct from mutation siblings and explicitly contrasts itself with traceable_test_plan_entry.

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?

Closes with 'Use it before traceable_test_plan_entry', giving an explicit sequencing rule, and the evidence note tells the agent that the returned `reference` feeds traceable_test_plan_evidence_add. It gives clear usage context but no when-not conditions beyond that ordering hint.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds a genuinely non-obvious trait: 'Reading never marks anything read for you,' which an agent could not infer from structured fields. It also enumerates the fields returned per thread type, compensating for the absence of an output 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 sentences, each load-bearing: what is listed, organisation scoping, and the read follow-up plus the no-read-marking caveat. The parenthetical field lists double as return-value documentation, so they earn their space rather than being filler.

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

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

For a zero-required-param list tool with no output schema, the description still covers what comes back (field-by-field), what the optional parameter changes, and what happens next. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% for the single optional parameter, so the schema already defines organisationId and its format. The description adds provenance guidance ('from traceable_workspace_projects') and states the default is the active organisation, which is modest but real added value over 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+resource: lists 'your threads', enumerating both subtypes (document Discussions and direct/group conversations) along with the identifying fields of each. It also separates itself from traceable_thread_read by positioning that tool as the follow-up rather than the listing 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?

Gives a clear condition and the alternative: list here, then 'Pass an id to traceable_thread_read' to open one. It also explains the default scope (active organisation) and when to override it. It stops short of explicit exclusions, but usage is otherwise 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?

Adds substantial context beyond annotations: posting identity ('as you, marked as posted via this agent'), notification fan-out to everyone in the thread, and an authorization gate ('refused where you could not post yourself — a Discussion needs a reviewer role or above'). The non-idempotency warning largely restates the idempotentHint=false annotation, though it usefully spells out the consequence ('calling it twice posts twice').

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

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

Dense and front-loaded: target selection, threading, mentions, safety warning, idempotency, and permissions each appear once and earn their place. It runs as one long paragraph, so the permission and idempotency caveats are buried mid-stream rather than separated out.

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

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

For a 5-param mutation with no output schema, the description covers targeting, threading, mentions, safety, and authorization thoroughly. The one minor gap is not saying what the call returns (e.g., the created message id), which an agent might want for a follow-up reply.

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 adds meaning the schema cannot express: the XOR constraint that exactly one of documentId/conversationId must be given, that replyTo must be a top-level message id sourced from traceable_thread_read, and how mentions work (inline '@Full Name' alone suffices; user ids optional).

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 ('Post a message') and immediately distinguishes the two target surfaces (a document's Discussion via documentId vs a conversation via conversationId). This is clearly differentiated from the sibling read/list tools (traceable_thread_read, traceable_thread_list) which the description references by name.

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

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

Explicit when-to-use routing: it tells the agent to get replyTo and the people list from traceable_thread_read, and to pass exactly one of documentId/conversationId. It also gives a clear when-not-to: 'do not post without being asked to' because everyone in the thread is notified.

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

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

Annotations already declare readOnlyHint/idempotentHint, and the description adds substantial context beyond them: ordering (oldest first), reply nesting, explicit field list of what each message carries, permission info ('whether you can post'), mentionable people with ids, and the notable side effect that messages are left unread.

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 operation and its exclusivity rule are front-loaded in the first clause, then return contents follow. The parenthetical field enumeration is dense and slightly long, but it earns its place because there is no output schema to document the return shape.

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 burden of describing return values and does so thoroughly (message fields, ordering, replies, permissions, mentionables). The only remaining gap — how to obtain a documentId — is minor for a two-param read tool.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds meaning the schema cannot: the two ids are mutually exclusive alternatives and exactly one must be supplied — a constraint the schema contradicts by listing zero required params. It also clarifies that documentId targets the Discussion specifically.

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

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

States a specific verb and resource ('Read one thread') and immediately scopes it to two exclusive cases: a document Discussion (documentId) or a conversation (conversationId). This separates it cleanly from siblings traceable_thread_list and traceable_thread_post 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?

'give exactly one' is an explicit selection constraint between the two modes, and the conversationId schema note points at traceable_thread_list for discovery. It stops short of explicitly naming when not to use it versus thread_list/thread_post, so it is clear context rather than full routing guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's real contribution is the in-place semantics: database identity is preserved, inbound/outbound trace links survive, ID-grid id cells are kept in sync, and cached link labels are refreshed project-wide. It also describes the revision guard, though conflict handling is left mostly to the schema's baseRevision text.

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 a distinct load: what changes, what is preserved, and the alternative/batch strategy. The most decision-relevant fact (identity and links survive) is front-loaded with no filler.

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

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

No output schema exists, yet the description covers the mutation's side effects (label cache refresh, id-cell sync) and the anchor/re-read behavior an agent needs to chain calls. Nothing essential for a correct 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 fromItemId/toItemId/documentId/baseRevision are already well documented in the schema itself. The description adds the notion of anchoring by TraceID after a batch rename but no format or value constraints beyond that, 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?

Names a specific verb and resource ('Rename a row's visible TraceID in place') and scopes it to two row kinds (traceable row, ID-grid row). An agent can distinguish it from siblings like traceable_doc_rename_prefix or traceable_block_update 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 routes away from the tempting alternative ('Use this instead of delete-and-reinsert, which would break links') and gives a concrete batch pattern ('To renumber a whole grid, call this once per row'). Both when-to-use and when-not-to-use conditions are stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the bar is lower. The description adds useful behavioral detail: default output format is Markdown (token-efficient), format=json returns the structured object, and include modes change what is returned.

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

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

The description is information-dense and front-loads the core purpose, but it runs as a single long paragraph rather than using scannable structure. Every sentence is relevant, though the include-mode details could be more digestible.

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 fully explains what each include mode returns, the default format, and the alternative format option. An agent has enough context to call the tool correctly without further documentation.

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%, but the description significantly enriches the enum values by explaining exactly what structure, links, and both return. It also clarifies that structure is the default and that format controls Markdown versus JSON, adding meaning beyond the terse schema descriptions.

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

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

States a specific verb and resource: 'Survey a project' to produce a map of structure, links, or both. It distinguishes the tool from document-reading siblings by positioning it as a pre-read survey and by describing the two distinct output modes in detail.

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 says to use it 'before opening any document' and explains that structure mode helps decide what to read. It does not explicitly name alternatives like traceable_doc_read or state when not to use this tool, so it stops short of full routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial value beyond them: the full return shape (id, name, org/project number, role, document count, last-updated), the empty-projects edge case, and the projectsWithoutOrganisation bucket. This is exactly the return-shape context an agent cannot 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?

The description is dense and longer than typical, but it is front-loaded with the core 'what you get' clause and every sentence earns its place (return shape, routing, edge cases, parameter use). Minor tightening is possible but no sentence is filler.

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

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

With no output schema, the description carries the full return-value burden and does so thoroughly, including non-obvious buckets like projectsWithoutOrganisation. Combined with the routing guidance, an agent has everything needed to call and consume 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 coverage is 100%, so the organisationId parameter is already documented, giving a baseline of 3. The description goes further by explaining the purpose of the parameter — disambiguating same-named projects across organisations — which adds semantic value the bare schema line does not.

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

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

States a specific verb and resource — listing every organisation the user belongs to plus their member projects — and the exact fields returned for each. It is unambiguously distinguishable from siblings like traceable_workspace_map, which it names as the downstream consumer of the projectId.

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 positions itself as the entry point ('Start here') and routes the agent: projectId feeds traceable_workspace_map, organisationId feeds traceable_library_search and traceable_workspace_templates. It also explains when to pass organisationId (to disambiguate same-named projects across organisations), giving both when-to-use and how-to-narrow 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 readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds real value beyond that: the scope of templates returned, the field shape, the null-vs-organisation semantics of the owning org, and the downstream cloning behavior in traceable_doc_create.

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, purpose front-loaded, with the field enumeration and the workflow hint following. The field list is dense but each item is informative; nothing is redundant, though the long comma-delimited enumeration is slightly heavy for a single clause.

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 burden of describing the return shape, and it does so by listing the fields and the null semantics for system templates. It is complete enough to call correctly; only minor things like ordering or result size are unspecified.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description's mention of templateId is about a different tool's input, not this one's, so there is nothing further to document here.

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 ("List") plus a precisely scoped resource ("the document templates available to you (system templates plus your organisations')"), and it enumerates the exact fields returned. No sibling tool lists templates, so there is nothing to confuse it with; an agent knows immediately what this does.

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

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

The description gives clear downstream context: use a template's id as templateId in traceable_doc_create to clone its bands and body scaffold, which tells the agent why and when to call this. It stops short of stating any exclusions or alternative sources of the same data, so it is strong context without explicit when-not guidance.

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