Traceable

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

Goes well beyond the annotations (destructive, idempotent, not read-only) by disclosing the operation is a recoverable soft-delete, that deleting a table or ID header cascades to children, and that links to deleted trace targets are marked broken. It also describes a verification artifact (echoed itemId) not covered by any structured field. The 'recoverable soft-delete' vs destructiveHint=true is a clarification, not a contradiction.

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

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

Front-loaded with purpose, then behavior, then parameter constraints, with no filler. The trailing 'Prefer itemId anchoring' fragment reads slightly tacked-on, keeping it out of 5 territory, but 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 mutation tool with no output schema and 3 well-documented params, the description supplies cascades, soft-delete recoverability, parameter-sourcing constraints, and a verification step. Missing only peripheral detail such as required permissions, which limits it to a 4.

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% (baseline 3), and the description adds real meaning beyond it: atOrder must come from a read issued after the last insert because inserts renumber later rows, and itemId anchoring is preferred. It does not detail the itemId/documentId formats, but the schema already carries those.

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 the scope word 'one block' distinguishes it from the sibling traceable_doc_delete (whole document) and from traceable_block_update/write. An agent can tell what this does and roughly how it differs from siblings without opening schemas.

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

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

Gives clear usage context ('Prefer itemId anchoring,' soft-delete is recoverable) and a hard constraint on atOrder sourcing. It does not explicitly say when to choose this over traceable_block_update or traceable_doc_delete, so it stops short of full when/when-not/alternatives 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, and the description adds non-obvious behavior: page/section breaks in trmContent replace the row's break flags, trmContent must parse to exactly one block, read-only [[row]]/[[document]] annotations are rejected, and inserts renumber later rows (invalidating stale anchors). This is substantial context beyond the annotations.

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

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

Four dense sentences with no filler; the core action and identification keys are front-loaded, and the caveats (renumbering, break flags, rename routing) each carry distinct operational value.

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, non-open-world mutation with full schema coverage and no output schema, the description covers identification, content constraints, and side effects well. It leaves ambiguous whether itemId and atOrder are alternatives or must be combined, which matters since neither is required.

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

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

Schema coverage is 100% so baseline is 3, but the description adds real meaning: itemId format example (FR-003), the atOrder staleness rule tying it to a post-insert read, and the constraint that trmContent parses to exactly one block. It does not clarify the either/or relationship between itemId and atOrder, which is not marked 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?

States a specific verb and resource ('Replace one block') and immediately specifies the two identification keys (TraceID or [[row N]] anchor). It also names the sibling it is not for renames (traceable_trace_id_rename), so an agent can distinguish it from traceable_block_write/delete/write without opening schemas.

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

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

Gives clear selection guidance between the two identification methods and routing to traceable_trace_id_rename for renames. It also warns that atOrder must come from a read issued after the last insert. It does not explicitly say when not to use this tool versus traceable_block_write, but context is otherwise strong.

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 (destructiveHint, non-idempotent) by disclosing the critical side effect that an insert renumbers every subsequent row, that prior row orders go stale, and that a `renumbered` marker is returned. It also notes that read-only annotations are rejected, which is exactly the behavioral context an agent needs before calling.

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

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

Front-loaded with the action and anchor options, then the return values, then the IMPORTANT warning in its own sentence. Dense but every clause carries actionable information; nothing is padding.

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

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

With no output schema, the description compensates by describing the return (created rows with new row orders plus a `renumbered` marker) and the staleness consequence. Anchoring semantics, defaults, and rejection behavior are all covered, so an agent can call it correctly without further discovery.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: afterItemId takes a TraceID like FR-003, afterOrder corresponds to a [[row N]] anchor from a document read, and position is a fallback defaulting to end. It clarifies the anchor mutual-exclusivity that the flat schema does not express.

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

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

Specific verb+resource ('Insert one or more body blocks') with the exact anchoring modes enumerated (afterItemId, afterOrder, position) and the return shape named. An agent can distinguish this from traceable_block_update/delete purely from the description.

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 conditions for each anchor path and the default ('position; default end'), plus explicit downstream guidance: re-read before further order-based calls, or anchor by TraceID. It does not explicitly contrast with the sibling update/delete tools, but the when-to-use guidance within the tool 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 declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety and repeatability profile is covered by structured data. The description adds that the return value is a static spec/manifest rather than live document state, which is useful, but it says nothing about authentication needs or payload size.

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

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

Two sentences, zero waste. The content enumeration comes first so the agent knows what it is looking at, and the actionable directive (read before authoring) is placed last where it reads as a conclusion.

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

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

With no output schema and zero parameters, the description correctly carries the burden of conveying what comes back, and the content enumeration does that adequately. It could be marginally stronger by indicating the rough shape or volume of the manifest, but for a read-only reference endpoint it is complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The parameter-free nature is consistent with a pure reference lookup.

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 exactly what the tool returns — the TrMD format spec and capabilities manifest — and enumerates its contents (row types, block directives, layout directives, segments, property tokens, paper sizes). It reads as a content list rather than a crisp verb+resource, but it clearly separates this reference tool from the action siblings (traceable_doc_read, traceable_block_write, etc.).

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 an explicit, prescriptive condition for when to call it, which is stronger than most tool descriptions. It stops short of naming specific alternatives or stating when not to use it, so it is 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?

With annotations only covering the safety profile (readOnly=false, idempotent=false, destructive=false), the description carries real behavioral detail: exactly what a template clone brings along (header/footer bands, title page, revision + signature scaffolding), what gets seeded when no template is given, what a controlled document should contain, and the [[test-plan]] placement syntax for test reports.

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 every sentence carries non-redundant information. It is dense, however, with long em-dash and parenthetical clauses that make the template-vs-no-template branch harder to scan than it needs to be.

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

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

No output schema exists, yet the description states the return value (documentId plus created rows with their row orders), and it covers the template, default-seeding, controlled-document composition, and test-plan placement cases. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains that templateId clones an org/system template and that trmContent then authors the body, and that without a template only default bands are seeded. That clarifies the templateId/trmContent interaction the schema only hints at.

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+scope: 'Create a document in a project.' An agent can immediately distinguish it from traceable_doc_update_meta, traceable_doc_read, and traceable_doc_delete, and the description names the sibling tools (traceable_workspace_templates, traceable_capabilities) that support it.

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 conditional guidance: pass templateId to clone a template, otherwise only default header/footer bands are seeded, and it routes the agent to traceable_workspace_templates for discovery and traceable_capabilities for documentComposition. It does not state when this tool should NOT be used or name a competing creation path, so it falls short of 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 destructiveHint=true and readOnlyHint=false, but the description adds genuinely new behavioral facts: the operation is IRREVERSIBLE, it cascades to child content, and it will fail unless the document was archived in the app first. It also discloses the error behavior, which annotations cannot express.

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

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

Four tight sentences with no filler; the irreversibility warning is front-loaded, followed by the precondition and the intended use case. Every sentence carries decision-relevant 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 single-parameter destructive tool with no output schema, the description covers the safety profile, the cascade effect, the precondition, and the failure mode — everything an agent needs to avoid an accidental or doomed call.

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

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

Schema coverage is 100% and the single parameter is already documented as 'The archived document UUID to delete'. The description reinforces the archival constraint but adds no syntax, format, or lookup guidance beyond what the schema states, 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 ('Permanently delete a document') plus the full cascade scope (items, columns, trace links, versions), which separates it from sibling mutations like traceable_doc_update_meta or traceable_doc_rename_prefix.

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

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

Gives an explicit precondition ('only a document that has been ARCHIVED may be deleted — archive it in the app first'), the consequence of ignoring it ('otherwise this returns an error'), and the intended scenario ('remove a superseded document after replacing it'). This is exactly when-to-use and when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: what full mode emits (TrMD with [[segment]], [[row N]] anchors, ID-grid structure) and the cost distinction between modes. It stops short of disclosing failure modes or size limits, keeping it from a 5.

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

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

A single dense paragraph, front-loaded with the core action and mode semantics, with no filler. Each clause carries operational information (default, format, bounding, template reuse).

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 must describe return content, and it does: metadata + heading outline + item counts for outline mode, and TrMD structure with anchors for full mode. An agent has enough to call the tool correctly with no open questions.

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

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

Schema coverage is already 100%, so the baseline is 3. The description meaningfully enriches this by clarifying that mode defaults to outline, that fromOrder/toOrder are row orders obtainable from the outline or a prior read, and that documentId may be a template UUID. That relationship between outline output and range parameters is not derivable from the schema alone.

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

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

States a specific verb (read) and resource (document or template), then distinguishes the two operational modes (outline vs full) and names the sibling tools it relates to (traceable_doc_create, traceable_workspace_templates). An agent can tell this apart from mutating siblings immediately.

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 mode=outline is the default when exploring and mode=full for content, plus when to bound a full read with fromOrder/toOrder and when to pass a template id (to inspect before cloning). This is when-to-use guidance with named alternatives, 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 the safety profile (destructive, idempotent, not read-only), but the description adds genuinely useful context the annotations cannot convey: the exact scope of the rewrite, that trace links are preserved while only visible ids change, and the draft-only prerequisite. It does not describe failure modes such as prefix collisions or uniqueness constraints.

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

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

Three sentences, front-loaded with the action and effect, followed by the 'no need to recreate' reassurance and the prerequisite. No filler and every clause carries information an agent needs.

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

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

For a destructive, non-read-only mutation with no output schema, the description covers scope, side effects on descendant rows, preservation of links, and eligibility. The main omission is any indication of what the caller gets back or how many rows are affected.

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

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

Schema description coverage is 100%, with the newPrefix format and documentId UUID pattern fully documented in the schema, so the baseline is 3. The description adds only the conceptual note that the prefix is the human-readable portion of the id, no syntax or constraint detail beyond the schema.

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

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

States a specific verb and resource ('Rename a document's TraceID prefix in place') and enumerates what gets rewritten (traceable rows, native-table trace cells, ID-grid id cells). However, it never distinguishes itself from the sibling traceable_trace_id_rename, which an agent could easily confuse with this tool.

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

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

Gives a clear when-to-use rationale ('you do NOT need to recreate the document to re-prefix it') and an explicit when-not via the prerequisite 'The document must be an editable draft (published documents are read-only).' It stops short of naming an alternative tool for the published-document case.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=true, so the write/idempotency profile is covered structurally. The description adds genuine behavioral context beyond that: patch semantics ('Only the fields you pass are changed'), the fact that prefix renaming re-derives existing ids, and the side effect of enabling numberedHeadings on future authoring. It does not explain why destructiveHint is set or what an update can clobber, which keeps it from a 5.

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

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

Front-loaded with the action and the affected fields, then useful constraints. Four sentences, all earning their place, though the numberedHeadings authoring aside is slightly tangential and could be folded into the capabilities note reference more tightly.

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

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

No output schema exists and annotations carry the safety profile, so the description's remaining burden is moderate. It covers scope, patch semantics, the sibling routing case, and one non-obvious side effect, but says nothing about failure modes (e.g., invalid group UUID) or whether type/number changes affect existing references.

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 and the schema already documents all six parameters. The description nonetheless adds meaning the schema lacks: the numberedHeadings workflow implication for authored heading text, and the patch-model clarification that unpassed fields are untouched. Only the groupId/documentType/documentNumber null-clearing semantics are left to the schema.

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

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

Specific verb+resource (update a document's metadata) with the exact editable fields enumerated, and it explicitly carves out what is NOT editable here (TraceID prefix) while naming the sibling that does it. An agent can distinguish it from traceable_doc_rename_prefix and traceable_doc_delete 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 positive usage guidance for numberedHeadings (turn it on, then author headings without numbers, with a pointer to the headingNumbering note in traceable_capabilities) and an explicit routing rule: use traceable_doc_rename_prefix for prefix changes because it re-derives existing ids. Both the when and the when-not 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?

The all-caps claim 'NON-DESTRUCTIVE' sits in direct tension with the annotation destructiveHint=true (setting a cell overwrites the previous value). The description does scope the term by saying identity and trace links survive, which limits the harm, but an agent skimming annotations versus the description gets conflicting signals about whether data is destroyed. On non-conflicting points it is rich (normalisation rules per column type, which cells are settable), but the destructive-wording conflict is a real inconsistency.

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 operation and the required identifiers, then adds behavioural detail. It is dense (one long paragraph with stacked clauses), but essentially every clause carries actionable information; minor tightening possible.

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

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

No output schema exists, and the description covers the mutation, its scoping, the identifier alternatives, and the 'not settable here' exclusion. It omits permissions/error behaviour, and the destructive-vs-non-destructive framing needs reconciliation with the annotations, so not quite complete.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes beyond it by explaining that row identity may be given as itemId or atOrder (one of the two), that colIdx is 0-based, and that the meaning of `value` varies by column type (raw for id/text, PASS/FAIL normalisation for test-result, true/yes/1/✓ for checkbox, chosen option for dropdown). That is meaningful value semantics the schema's generic 'The new cell value' 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?

States a specific verb+resource+scope: sets ONE cell of an ID grid, identified by id-ROW (itemId or atOrder) and a 0-based colIdx. It also explicitly distinguishes itself from siblings (traceable_segment_write for the id column, traceable_link for link cells), so an agent can tell it apart 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 routing rules: link cells are not settable here, use traceable_link instead; and contrasts with traceable_segment_write for the id column. The when-to-use condition (set a single cell value, including the visible TraceID, while keeping links) is unambiguous.

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

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

The description asserts the operation is 'NON-DESTRUCTIVE in every case: existing cells and trace links are preserved,' but the annotations declare destructiveHint=true (and readOnlyHint=false). This is a direct polarity conflict, and `set_type` ('converts each id-row cell to a new type') plausibly overwrites existing cell values/types, so the blanket non-destructive claim is not reconcilable with 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?

Front-loads the key facts (op selection and the preservation guarantee) and stays dense with no filler, organizing content by op. It is somewhat long for a single paragraph, but nearly every clause carries operational detail rather than repetition.

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

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

For an 8-parameter mutation tool it covers op routing, parameter requirements, the one-id-column constraint, and sibling escalation, which is most of what an agent needs. It does not describe return values or failure modes (no output schema exists), and the preservation claim is not qualified against the destructive annotation.

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

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

Schema coverage is already 100%, yet the description adds conditional semantics the schema cannot express: which parameters each `op` requires, that `insertAt` is 0-based and append-by-default, that `label` falls back to type defaults, that the grid is located by the HEADER row (itemId or atOrder), and concrete `config` payload examples for dropdown and calculation columns.

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 concrete verb+resource (add/rename/retype a column in an ID grid) and enumerates the three ops up front via the `op` selector. It explicitly distinguishes itself from `traceable_segment_write` (whole-grid replace) and `traceable_grid_cell` (cell values), so an agent can place it precisely among siblings.

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

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

Gives per-op routing (add vs set_label vs set_type) with the trigger for each, names the alternative for whole-grid replacement and for cell edits, and states a domain exclusion ('Only one id column is allowed per grid'). Nothing about when to use this vs. siblings 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?

Goes beyond the annotations by disclosing a real side effect: a Reference Table row is created at the end of the body if absent, and an existing [[reference-table]] marker is reused rather than duplicated. The idempotency claim is somewhat redundant with idempotentHint=true, and it doesn't cover permissions or failure modes, but the table-creation behavior is genuinely new information.

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

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

Dense and front-loaded, with the core action in the first clause and the alternative-placement caveat immediately after. The sentences are long and could be split, but essentially every clause carries actionable information, so little is wasted.

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

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

For a 4-parameter mutation tool with no output schema, the description covers side effects, idempotency, placement mechanics, and parameter exclusivity. It stops short of stating permission requirements or error behavior for an invalid REF code, which is the remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a real constraint not encoded in the schema: that code_or_id and targetDocumentId are mutually exclusive ('exactly one'). It also clarifies the REF-code-vs-UUID duality and the referencedVersion default, adding meaning over the field 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 ('Attach a Reference Library item — or another document — to this document's reference list') plus the side effect of ensuring a Reference Table row. It distinguishes itself from siblings like traceable_link and traceable_segment_write by naming them where their behavior overlaps.

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: pass exactly one of code_or_id (from traceable_library_search) or targetDocumentId, and use traceable_segment_write to place [[reference-table]] elsewhere. It routes the agent to the right sibling for the lookup and the alternate placement case, though it never states when this tool is the wrong choice versus traceable_link.

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

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

Beyond the annotations (which only declare write/idempotent/not-destructive), the description discloses that extraction runs locally, enumerates supported formats (docx, spreadsheets, CSV, text/markup), notes webpages are fetched, and defines the return payload (character count) plus a failure signal (unsupported=true for PDF/PPT/images). This is rich behavioral context that the structured fields 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?

Three sentences, front-loaded with the purpose, followed by the mechanism and then the return/exception behavior. The format list is compact and every clause carries information an agent needs.

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

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

With no output schema, the description correctly supplies the return semantics (character count, unsupported=true) and the supported/unsupported format boundary. Nothing essential for calling this one-parameter tool correctly is missing.

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

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

Schema coverage is 100% and the single parameter is already documented in the schema with a REF-code example. The description only restates "identified by its REF code or id," adding no syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ("Extract and persist the plain text of a Reference Library item") and names the exact mechanism it feeds (traceable_library_search). It clearly differentiates itself from the sibling search and read tools by describing the indexing/persistence act rather than retrieval.

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 implies the usage context well: the item becomes "searchable via traceable_library_search and cheap to read," which tells an agent this is the prerequisite step before searching or reading. It names the sibling tools but stops short of explicit when-not-to-use conditions or a direct alternative comparison.

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/openWorld, but the description adds real behavioral context: indexed text is returned when available, otherwise extraction happens on the fly without persisting, and unsupported types (PDF, PowerPoint, images) yield empty text with an explanatory note. This caching/persistence nuance is not derivable from the annotations.

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

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

Two dense sentences, front-loaded with the primary outcome and followed by the fallback and failure behavior. Every clause carries information an agent needs.

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

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

For a one-parameter read tool with no output schema, the description covers input identification, return content, the extraction fallback, unsupported-type behavior, and the escalation path to indexing. Nothing essential to 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 coverage is 100% for the single code_or_id parameter, so the schema already documents its type and meaning. The description only restates the accepted formats (REF code, id), adding no syntax or edge-case detail beyond the schema.

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

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

States a specific verb and resource ('Return the extracted plain text of a Reference Library item') plus the identifier forms accepted. It is clearly separable from sibling tools like traceable_library_search, traceable_library_index, and traceable_library_add_reference.

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 use condition (retrieve text by REF code/id) and routes to traceable_library_index for persisting supported text for search. It does not explicitly state when NOT to use this versus traceable_library_search, so it falls short of full when/when-not coverage.

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, and closed-world behavior. The description adds substantial behavioral context beyond them: the search is case-insensitive substring only, not semantic/embedding search; it returns a snippet around the first hit; listing returns specific item metadata including an indexed flag; and unindexed items are invisible until indexed.

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 scope, then cleanly splits with-query and without-query behavior, and ends with a practical troubleshooting note. Every sentence adds useful information with no filler.

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

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

With no output schema, the description adequately explains what listing returns and what search results contain. It also covers the critical operational limitation around indexed versus unindexed items, making it complete enough for an agent to call the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches the query parameter significantly by naming the searched fields (name, REF code, extracted text) and clarifying it is substring rather than semantic search. It also describes scope behavior, though it does not add parameter-specific meaning for organisationId beyond what the schema already says.

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

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

The description states a specific verb and resource: finding Reference Library items, with clear scope (org-scoped items plus projects the caller is a member of). It distinguishes its two modes of operation, with and without a query, and clearly sets it apart from indexing siblings by explaining that search only covers already-indexed 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?

It gives explicit when-to-use guidance for both modes: use with a query for keyword search, omit the query to list every accessible item. It also provides a concrete troubleshooting path for empty search results, naming traceable_library_index as the action that makes unindexed items visible.

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

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

Annotations only say idempotent/destructive; the description goes well beyond them, explaining that idempotency is on the unordered pair (F914), what happens on an opposite-direction collision (existingDirection, warning, no chip placed), what delete destroys (edge and chip), and the no-link-column fallback with its warning. This is rich, non-obvious behavioral 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?

Dense but front-loaded, opening with the create/delete scope and the shared addressing rule before the edge cases. Every clause carries decision-relevant information, though the run-on density pushes slightly against 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 naming the return signals an agent will see (existingDirection, warning, placedInColumn) and the failure modes. Nothing needed to call create or delete correctly appears to be missing.

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

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

Schema coverage is 100% and the schema already documents each field, so the baseline is 3. The description adds real meaning: toColumnIndex placement semantics and its default (first OUTPUT column) plus why the target is downstream, which the schema does not state.

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 pair (create/delete) and precise resource (a trace link between two TraceIDs). It distinguishes the edge from the sibling block/grid/segment tools by naming the exact objects addressed and the ops available.

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 for each op: create is idempotent on the pair, delete requires the pair to exist in the same direction. It does not name alternative sibling tools or explicit when-not-to-use cases, but the create vs delete framing is unambiguous.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, but the description adds what actually gets destroyed: rows are soft-deleted and existing links to them are marked broken, and it warns that writing to title_* content may not render until the page is enabled. This is meaningful context beyond the structured hints.

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 operation and the routing decision before the denser directive-syntax and title-page details. It is long and information-dense, but each sentence carries authoring or safety information an agent needs; slightly heavy but no filler.

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

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

For a destructive, no-output-schema mutation tool, the description covers the destruction model, the idempotent bulk-replace semantics, the incremental alternative, and the content format. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by documenting the TrMD directive syntax for trmContent (column bands, id-header/id-row grids, link cells taking whitespace-separated TraceID names) and the meaning of the title_* segment values. It adds real authoring semantics not present in 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+scope ('Replace a whole segment with the given TrMD — the primary bulk-authoring tool'), and explicitly positions itself against siblings by naming traceable_block_write/traceable_block_update for incremental edits. An agent can distinguish this from every other write tool without opening a schema.

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

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

States the alternative tools and the exact condition that selects them ('for incremental edits'), plus the title_* segment caveat about the title page being switched off. Both when-to-use and when-not-to-use are 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 declare destructive/write/idempotent but the description adds real behavior: values can be cleared with an empty string, result is derived from steps when the protocol has steps, resolution has a derived default, and the row is pushed to review. The agent-signature restriction is the single most valuable disclosure. It still doesn't spell out overwrite semantics for omitted columns.

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 instruction, then column semantics, then step behavior, then workflow notes. Dense but every clause carries semantic load; only the trailing review sentence is arguably peripheral.

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

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

For a nested, 5-parameter mutation with no output schema and destructive annotation, the description covers value vocabularies, step scoping, evidence routing, signature limits, and post-write review state. It omits only return/confirmation behavior and permission requirements.

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 goes well beyond it by enumerating the allowed values the schema itself does not constrain (decision include|exclude, result pass|fail|empty, resolution passed|failed|passed_with_deviation|failure_accepted|empty), documenting the per-line format of `equipment`, and redefining `step`'s scoped field set.

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') and immediately explains the payload shape. It distinguishes itself from traceable_test_plan_read (which supplies the entry id) and from traceable_test_plan_evidence, so an agent can route correctly 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 routes evidence to traceable_test_plan_evidence and states a hard when-not: the tester signature 'cannot be applied by an agent'. It also clarifies when to pass `step` versus entry-level columns. It stops short of stating prerequisites, such as needing entryId/protocol from a prior read, in a prescriptive when-to-use form.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnly=false, so the safety profile is covered. The description adds context those annotations cannot: the evidence is a Reference Library item the document references, it renders as a citation-format chip, and the Test Plan row is moved to review as a side effect. It does not say what happens when removing evidence that another step also uses, which is the remaining gap.

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

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

Front-loads the operation and scope, then the prerequisite, then the alternative, then the side effect. Every sentence routes the agent or warns it; nothing is restated from the title or 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 nested, six-parameter mutation tool with no output schema, the description covers prerequisites, the sibling alternative, and the review-state side effect. Combined with 100% schema coverage, an agent has everything needed to call it correctly on the first try.

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, and the description earns the raise by constraining the 'reference' parameter to an already-existing Reference Library item identified by REF code or item id rather than an arbitrary value. It also clarifies that evidence attaches either at entry level or at a numbered step, which explains why the optional 'step' parameter exists.

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 pair (add/remove) plus the resource (file evidence on a Test Plan entry or its test steps), and distinguishes itself from the two closest siblings by name. An agent can tell this apart from traceable_test_plan_evidence_upload and traceable_library_add_reference without opening any schema.

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

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

Explicit when-and-when-not routing: it names the prerequisite ('add the reference first with traceable_library_add_reference') and the alternative for a different case ('To upload a new image or file, use traceable_test_plan_evidence_upload'). Both conditions that select a sibling tool are stated rather than implied.

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

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

Adds substantial behavior beyond annotations: image types are detected from bytes not name and rendered inline, other files go to the Reference Library as a cited file chip, 3 MB per-file limit, and 'Calling it twice uploads twice' (consistent with idempotentHint=false). It also discloses the side effect that the Test Plan row goes to review, which no annotation conveys.

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 packs the high-value behavioral facts (image detection, library fallback, size cap, non-idempotency, review status) into tight clauses. Every sentence carries information; nothing is filler.

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

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

With no output schema, the description compensates by explaining the outcome (inline image vs. library reference and file chip) and the resulting state change. For a 6-param nested-schema mutation tool, the caller has enough 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 baseline is 3. The description reinforces that content is base64 with a name, but this largely repeats the schema's own 'base64-encoded' and naming docs, adding little new semantics about the nested row/entry selectors.

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: 'Upload a file as evidence on a Test Plan entry (or one of its test steps).' It is distinguishable from the read-oriented sibling traceable_test_plan_evidence because it states an upload action with targets (entry or step).

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

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

The description implies when to use it (to attach evidence to a Test Plan entry/step) but never names an alternative or states conditions/exclusions versus siblings like traceable_test_plan_evidence or traceable_library_add_reference. Usage is inferable but not 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 cover the safety profile (readOnlyHint=true, idempotentHint=true, openWorldHint=false), so the bar is lower, and the description adds real value by disclosing the return shape: per-entry protocol cells, the full column-value set, evidence, and conditional signature. With no output schema, that payload disclosure is the main behavioral contribution; it stops short of mentioning limits, pagination, or behavior for a non-existent row.

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 payload enumeration is front-loaded in one dense sentence followed by a short routing directive, and given the absence of an output schema the field list largely earns its place. It is a run-on enumeration, though, and the long parenthetical of column values is heavier than strictly necessary.

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

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

For a read-only tool with nested row identification and no output schema, the description is close to complete: it covers the returned payload, the signed/unsigned condition, and step numbering from 1. It omits error behavior (missing row, ambiguous itemId/atOrder) and any result-size or pagination caveat, which are the remaining gaps.

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

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

Schema description coverage is 100%: documentId, itemId and atOrder are all documented in the schema, including the 'pass one' constraint and the [[row N]] anchor meaning of atOrder. The description adds no format, default, or validation detail 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?

States a specific verb ('Read') and a precisely scoped resource ('a bound Test Plan row'), then enumerates the exact contents (plan, columns, entries, TraceID, evidence, signature, steps) so the agent knows what it gets back. It also names the sibling traceable_test_plan_entry, making it distinguishable from the other ~24 traceable_* 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 single directive 'Use it before traceable_test_plan_entry' gives one concrete sequencing cue, which is useful workflow context. However, it offers no when-not guidance and does not distinguish this read from other read paths (traceable_doc_read, traceable_grid_cell) or explain the itemId-vs-atOrder choice for locating the row.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds substantial context beyond them: the row keeps its database identity, all inbound/outbound links survive, an ID-grid row's id cell is synced, and cached link labels are refreshed project-wide. This is exactly the kind of side-effect disclosure a mutation tool needs.

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

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

Front-loaded with the core action, then side effects, then the delete-and-reinsert alternative, then the batch guidance. Dense but every sentence and parenthetical carries distinct, useful information.

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

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

For a 3-param mutation tool with no output schema, the description covers what changes, what is preserved, side effects, and whether a follow-up read is needed. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so documentId, fromItemId, and toItemId are fully documented in the schema. The description adds only marginal meaning (the 'anchor by TraceID' re-read guidance), so baseline 3 is appropriate.

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

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

States a specific verb (rename) and resource (a row's visible TraceID) and clarifies scope by naming the two row types it applies to (traceable row, ID-grid row). An agent can distinguish it from the doc-level sibling traceable_doc_rename_prefix, which renames a prefix rather than a single row's TraceID.

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 instructs to use this instead of delete-and-reinsert because that would break links, and explains the batch pattern for renumbering a grid (call once per row). It gives both when-to-use and the preferred alternative, leaving little 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 readOnly, idempotent, non-open-world, so the safety profile is covered. The description adds real value beyond that: default include and format modes, that output is Markdown by default for token efficiency, and that the link graph carries edge weights and one-to-many/external links. It stops short of noting size/rate limits or truncation behavior on large projects.

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, and the three include modes are covered in parallel order without repetition. The middle sentences are dense run-ons stacked with em-dashes, which costs a little scannability but every clause carries information.

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

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

No output schema exists, so the description carries the full burden of describing return values, and it does so for both modes plus the format switch. Combined with annotations covering safety and a fully documented schema, 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 schema already names all three params, but the description materially enriches two of them: include=structure/links/both is spelled out with the concrete contents of each mode, and format is tied to a tradeoff (Markdown token-efficient vs json structured). That is meaningfully beyond the one-line schema enum text.

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 ('Survey a project') plus resource, and it enumerates exactly what each mode returns: the group/document/outline tree with number, ID prefix, type, status, version, counts and H1-H6 headings, or the document-to-document trace graph. This clearly separates it from siblings like traceable_doc_read (opens one document) and traceable_workspace_projects (lists projects).

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

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

States the moment to use it ('before opening any document') and the decision it supports ('use it to decide what to read'), which is a clear context. It does not name a specific alternative tool or state an exclusion, so it falls short of the explicit when/when-not routing a 5 requires.

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 openWorldHint, so safety is covered. With no output schema, the description carries the return-shape burden and does so richly (per-org fields, empty projects arrays, projectsWithoutOrganisation). It stops short of auth/permission or pagination notes, but the behavioral disclosure is well above the annotation baseline.

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 result shape, then each clause adds routing or disambiguation value rather than filler. It is a dense, somewhat long run-on, but virtually every sentence earns its place, so only minor tightening is possible.

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 covers return values (both org and project fields, empty arrays, projectsWithoutOrganisation) and how to consume the resulting IDs. For a single-parameter listing tool with safety annotations in place, nothing an agent needs 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. The description goes beyond the schema's terse 'Only list this organisation and its projects' by explaining the parameter's purpose: narrowing to one organisation and disambiguating same-named projects. That added rationale is genuine value over the structured field.

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

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

States a specific verb and resource ('List' your workspace's organisations and their projects) and enumerates exactly what fields come back. It differentiates itself from siblings by naming traceable_workspace_map as the consumer of the returned projectId. An agent can tell what this does without opening the schema.

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

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

Explicitly says '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). When-to-use and downstream alternatives are both 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 cover the safety profile (readOnly, idempotent, closed-world), and the description goes beyond them by enumerating the returned fields — id, name, TraceID prefix, document type, band previews, body outline, organisation details. It also discloses that organisationId/organisationName are null for system templates, which is a real behavioral nuance. It stops short of describing ordering or volume behavior.

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

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

Two sentences, front-loaded with the action and then the field enumeration. The long list of returned fields is dense but justified given there is no output schema. No filler sentences.

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

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

For a zero-param, read-only list tool with no output schema, the description carries the return-value burden itself and does so completely, while annotations cover safety and the workflow to traceable_doc_create is spelled out. 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?

Zero parameters, so there are no argument semantics to clarify; the schema is empty and the baseline is 4. The description appropriately spends its budget on the return shape instead.

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

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

States a specific verb and resource ('List the document templates') plus the exact scope (system templates plus the caller's organisations'). It also routes the agent to the downstream sibling traceable_doc_create, so the tool is distinguishable from its neighbors 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 tells the agent what to do with the results ('Pass a template's id as templateId to traceable_doc_create to clone...'), giving a clear purpose context. It does not state when-not to use it, but there is no overlapping sibling that lists templates, so the missing exclusion is minor.

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