trident

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate safety. It adds meaningful behavioral context: 'Appears immediately for all collaborators' (real-time shared visibility) and 'Requires a valid editor access token' (authentication requirement). This goes beyond what the structured annotations convey, aiding the agent in setting expectations for side effects.

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

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

The description is three sentences, front-loaded with the core action. Every sentence earns its place: action, style variants with examples, use cases, collaboration behavior, and auth requirement. No redundant phrasing or filler.

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

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

Given the tool's complexity (nested annotation object with 15 optional properties), the high schema coverage means the description doesn't need to enumerate fields. It covers what the schema cannot: when to use which style, live collaboration visibility, and auth. The description gives a complete enough mental model for an agent to select and invoke the tool, though it doesn't mention the action_explanation parameter or the constraint on id formatting (both already in 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?

The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds value by explaining the semantic distinction between stickyNote and textBody styles and linking them to use cases (titles/labels vs. notes/callouts). This helps the agent choose appropriate parameter values, especially for the 'style' field, which is otherwise just an optional enum-like string.

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

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

The description opens with a specific verb+resource: 'Adds a text annotation to a live Trident document.' It clearly distinguishes this from sibling tools like add_node and add_connection by specifying text annotation, and further clarifies scope with two named visual styles. The intended uses (architectural notes, decision records, etc.) make the purpose unambiguous.

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

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

The description provides explicit use-case guidance: 'Ideal for architectural notes, decision records, section labels, or TODO markers.' It also gives context for choosing between the two styles, which serves as a 'when to use this variant' guideline. It doesn't explicitly mention when NOT to use this tool versus update_annotation/delete_annotation, but the phrasing implies annotation creation for live collaborative documents.

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=false, destructive=false, idempotent=false, openWorld=true. The description adds behavioral context the annotations don't carry: an editor token is mandatory, field rows are rejected as endpoints, and ERD pairs render as solid lines with crow's-foot markers. It does not mention return behavior or whether layout is reflowed, hence not 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?

Four sentences, front-loaded with purpose and then prerequisites and the ERD special case. Each sentence carries distinct information; only the ERD sentence is dense enough that it could be split for 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?

For a mutation tool with a nested schema and no output schema, the description covers purpose, prerequisites, auth, and the main structural pitfall (endpoint type). It omits what the call returns and whether auto-generated IDs are surfaced, which are minor given no output schema exists.

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

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

Schema coverage is 80%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains what a valid source/target is (container IDs, not field rows) and shows concrete enum-like values for type ("one_to_many", "one_to_zero_or_many"). It adds the semantics the schema's string fields leave open.

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

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

States a specific verb (adds) and resource (a connection/arrow/edge) with scope (between two nodes or containers in a live Trident document). This clearly distinguishes it from siblings like add_node, add_container, and delete_connection without requiring the schema.

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

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

Explicitly routes the agent through a prerequisite ("Use get_document_summary to get valid source and target IDs before calling this"), states the access requirement ("Requires a valid editor access token"), and gives a concrete when-to branch ("For ERD relationships, connect the two TABLE containers... set type to an ERD pair"). These are actionable conditions, not implied usage.

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=false and destructiveHint=false. The description adds real context beyond that: it requires a valid editor access token, warns about duplicate IDs, and explains auto-sizing behavior (rows stacked, table sized automatically, ERD height managed). It does not describe the response payload, but annotations carry the safety profile.

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

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

Purpose and duplicate-check guidance are front-loaded, but the trailing ERD tutorial is long and spans several sibling tools, making the definition read partly like workflow documentation rather than this tool's contract. It earns its place but is heavier than needed for a single call.

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-object, 5-parameter mutation tool with no output schema, the description covers auth, duplicate risk, sizing behavior, and the surrounding workflow well. Remaining gap is the return value/shape, which is minor given no output schema exists.

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

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

Schema coverage is 80% so the baseline is 3, but the description adds interaction semantics the schema cannot express: kind:"erd" requires x/y (table centre), rows are passed via add_node with container:<table id> and no x/y, and ERD height must not be set. That meaningfully exceeds the schema's per-field prose.

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 ("Adds a new container (group/swimlane)") and immediately defines what a container is, distinguishing it from add_node/add_connection by scope. An agent can tell this creates grouping structures rather than content nodes.

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 names get_document_summary as the prerequisite check to avoid duplicate IDs, and lays out the full multi-tool ERD workflow (add one container per table, then add_node rows, then add_connection between tables). It states both when to use it and which sibling tools to sequence with 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 declare the safety profile (not read-only, not idempotent, open-world, non-destructive), and the description adds genuinely new behavior: the node is broadcast immediately to all live collaborators, an editor access token is required, and orphaned nodes cause visible churn. That is real collaboration/state 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?

Purpose is front-loaded in the first sentence and the prerequisite ordering reads cleanly. It is somewhat long, and the container warning is repeated in both the description and the schema, but no sentence is pure 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 live mutating tool with a nested payload and no output schema, the description covers prerequisites, ordering, container/ERD handling and the collaboration side effects. It stops short of describing failure modes (e.g. invalid token, duplicate id) which would be useful for a non-idempotent write.

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 nested node object is thoroughly documented field-by-field, so the schema already carries the parameter meaning. The description's container and 'set on THIS call' guidance largely restates the container schema description, adding sequencing advice but little new per-parameter semantics.

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

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

States a concrete verb and resource ('Adds a new node (entity)'), and immediately scopes it to a live Trident document, which cleanly separates it from add_container, add_connection and add_annotation. An agent can identify the operation 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 prescribes the prerequisites and ordering: call open_document to understand layout, call get_document_summary to gather entity IDs and avoid duplicates, and pass container on this call rather than reparenting later. It also names the alternative anti-pattern (create orphan then update_node) and why it is wrong.

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, readOnlyHint=false, and idempotentHint=true. The description adds the context that the document is live and that a token is required, but doesn't elaborate on side effects or irreversibility. This adds modest value but doesn't fully round out the behavioral picture.

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 compact and well-structured: the first sentence states the core action, the second gives a practical prerequisite and authentication note. No unnecessary words or 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?

Given the tool's simplicity, fully described schema, and rich annotations, the description covers the essential context: the operation, how to prepare (get IDs), and authentication. It lacks error-handling or return-value details, but these are not critical for a delete operation 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?

The input schema already provides 100% coverage with detailed descriptions for all 5 parameters. The tool description references annotation IDs and tokens but does not add semantic meaning beyond what the schema defines, so a baseline score 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?

The description clearly states the tool's function with a specific verb ('Removes'), resource ('text annotation'), and scope ('live Trident document'). This immediately distinguishes it from sibling tools like add_annotation, update_annotation, and delete_connection/container/node.

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

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

It provides actionable guidance: 'Use get_document_summary to get all annotation IDs before calling this' and notes the prerequisite of a valid editor access token. While it doesn't explicitly name alternatives or exclusions, the indicated workflow makes the appropriate usage context 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 destructiveHint and readOnlyHint, so the description need not repeat that. It adds context about operating on a 'live' document and requiring a 'valid editor access token', which is useful behavioral information. The 'find and remove' phrasing clarifies the matching logic when using source/target IDs.

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 three focused sentences, front-loaded with the main action. Every sentence adds value: what it does, how to identify the connection, and the prerequisite. No redundancy or filler.

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

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

For a destructive tool with no output schema, the description covers all necessary invocation details: identification modes, prerequisite data source, token requirement, and connection type. It is fully sufficient for an agent to select and execute the tool correctly in context.

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 all parameters have descriptions. The description adds critical relationship semantics by explaining that connectionId OR (source+target) are mutually exclusive alternatives for identifying the connection. This goes beyond what the schema provides and helps an agent correctly construct parameters.

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 ('Removes a connection from a live Trident document'), clearly distinguishing it from sibling tools like delete_node or add_connection. It also specifies the two main invocation modes, leaving no ambiguity about what the tool does.

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

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

The description explicitly explains how to use the tool: either provide connectionId or source and target IDs. It also recommends using get_document_summary to list connection IDs first, and states the token requirement. This gives clear actionable guidance and covers the primary usage scenario, even though it does not list when-not-to-use cases.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds valuable nuance beyond annotations: the default detach behavior ('nodes inside are detached (kept on the diagram without a container)') and the deleteNodes escalation path. It also mentions the token requirement, though that is already in the schema. This adds meaningful behavioral context without contradicting 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 sentences, all information-dense and non-redundant. The main verb+object appears in the first sentence, followed by behavior, option, prerequisite, and auth. No filler or repetition. This is an exemplar of concise, front-loaded tool documentation.

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 tool with robust annotations and no output schema, the description covers the essential aspects: what it does, the default vs optional escalation, how to obtain required IDs, and the token requirement. The only notable gap is the absence of return-value information, but for a mutation tool this is minor. Given the tool's moderate complexity (6 params, container-node relationship), the description is sufficiently 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. The description elevates this by clarifying the containerId acquisition process ('Use get_document_summary to get all container IDs') and reinforcing the deleteNodes default semantics ('Pass deleteNodes: true to remove the container's nodes as well'). These additions go beyond the schema's property descriptions, but do not fully compensate for all parameter nuances (e.g., token/agentId/userName are left to schema).

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

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

The description opens with 'Removes a container from a live Trident document', a specific verb+resource combination that unambiguously distinguishes this from sibling tools like delete_node or delete_annotation. The scope is clear and the action is immediately understandable.

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 provides a clear prerequisite ('Use get_document_summary to get all container IDs before calling this') and explains the default behavior vs the deleteNodes option, which guides when to use each mode. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it falls just short of a 5.

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

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

The description goes beyond the annotations by disclosing that all connections to/from the node are removed automatically, that the action is reversible via Ctrl+Z, and that a valid editor access token is required. These are valuable behavioral details not present in the annotations, especially 'what gets destroyed' and 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?

The description is three concise sentences, front-loaded with the primary action. Every sentence adds value: the core behavior, side effects, prerequisite, reversibility, and auth requirement. There is no redundancy or 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?

Given the tool's destructive nature and lack of output schema, the description adequately covers the key aspects: what is removed, what else changes, how to prepare, reversibility, and auth. It provides a complete mental model for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful guidance for the nodeId parameter by instructing the agent to obtain it via get_document_summary, which helps prevent errors. It does not elaborate on other parameters, but schema already covers them.

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

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

The description clearly states the action: 'Removes a node from a live Trident document.' This is specific and distinct from sibling tools like delete_connection or delete_annotation, which target different resources. The phrase 'live Trident document' adds operational context.

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 provides a clear prerequisite: 'Use get_document_summary to get all node IDs before calling this.' It also notes that the action is reversible (Ctrl+Z), giving the agent confidence in using it. It doesn't explicitly mention alternatives or when not to use it, but it offers sufficient contextual 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?

The description goes beyond the readOnlyHint annotation by disclosing that a valid access token is required, that the explanation appears attributed to the agent, and that the tool automatically pauses 3–15 seconds before returning. It also warns against adding artificial delays—all valuable behavioral context not captured in annotations.

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

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

The description is well-structured and front-loaded with the core purpose. Each sentence adds unique value: purpose, usage, non-mutation, auth, and delay behavior. The IMPORTANT note is clearly highlighted, making the message easy to parse without wasted words.

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 tool with no output schema, the description adequately explains the effect (UI attribution, non-mutation) and the unique delay behavior. It also covers prerequisites (token) and usage constraints (no artificial delays). All key aspects are addressed given the tool's complexity.

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

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

Schema coverage is 100%, so every parameter already has a rich description. The tool description adds only minimal extra context (e.g., anchoring to a node matches entityId, auth requirement matches token), which does not meaningfully supplement the schema. 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?

The description clearly states the tool delivers an explanation payload to human collaborators, with specific use cases ('explain what a diagram element represents, why it exists, or how it relates to other parts of the system'). It explicitly differentiates from mutation tools by noting it does NOT mutate the diagram and is for use 'without suggesting a change', distinguishing it from siblings like make_suggestion.

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 provides explicit when-to-use context ('Use this when you want to explain...') and a when-not ('without suggesting a change'). It also includes practical guidance about not adding artificial delays. However, it does not explicitly name alternative sibling tools for scenarios like suggesting changes, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, and the description consistently describes a read-only return of example content. The description adds context about what is included but does not disclose additional behavioral traits like output size or formatting, which is acceptable given the tool's simple nature.

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

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

The description is a single, focused sentence that entirely fits its purpose. It front-loads the action and resource, then enumerates example contents without redundancy.

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 simplicity (no parameters, no output schema, read-only hint), the description fully covers what the tool does and the content of the returned example. It provides all necessary context for an agent to select and 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?

The tool has zero parameters, so the semantic baseline is 4. The description doesn't need to explain parameters, and it adds context about the content returned without conflicting with the empty schema.

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

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

The description clearly states the tool 'Returns a comprehensive Trident example' and lists specific features it covers, which distinguishes it from sibling tools like get_quick_start or get_trident_spec. The verb and resource are explicit and the scope is well-defined.

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 phrase 'Use this to see all features in action' provides clear guidance on when to use the tool. It does not explicitly mention alternatives or exclusions, but the context is sufficient for selecting it as a learning/reference resource.

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 and openWorldHint, and the description adds valuable context about the data source (Yjs session vs Firestore), the bypassing behavior, and the return format (base64-encoded PNG). This goes beyond the annotations and helps the agent understand the tool's freshness promises.

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

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

The description is two sentences, front-loaded with the core action and output format. The usage guidance is succinct and relevant, with no wasted words or redundant information.

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

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

This is a simple tool with one parameter, no output schema, and clear annotations. The description covers the core functionality, the return format, and the intended use case, making it sufficient for an agent to select and 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% with a clear description of the token parameter. The description adds no extra parameter semantics, but this is acceptable since the schema already explains the token's role and document ID embedding.

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 uses the specific verb 'Renders' with a clear resource ('live Trident document') and specifies the output ('PNG image'). It distinguishes itself from sibling tools like get_document_summary by emphasizing visual rendering from the live Yjs session.

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 explicitly states the intended use case: 'Use this to visually verify that diagram edits look correct before or after making changes.' It also provides rationale for choosing this over Firestore-backed approaches by noting Firestore may be stale. However, it does not name alternative tools or explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds valuable behavioral context: never truncated regardless of diagram size, always returns every entity ID, and requires a valid access token. This goes beyond the annotations without contradicting them.

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 sentences, all front-loaded: a clear purpose statement, then usage guidance, an alternative, and an auth requirement. Every sentence earns its place with no redundancy or filler.

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

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

For a single-parameter read-only tool with no output schema, the description fully covers what it returns (entity IDs, labels, counts), when to use it, and the alternative. The context is complete and sufficient for an agent to select and invoke the tool correctly.

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

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

The schema has one parameter (token) with 100% coverage explaining it embeds the document ID. The description only restates the token requirement ('Requires a valid access token'), adding no new meaning beyond the schema. Baseline of 3 applies due to high schema coverage.

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

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

The description clearly states the tool returns a complete structured summary of a Trident document as JSON with specific entity ID types and counts. It explicitly distinguishes this from open_document for human-readable diagrams, making the purpose specific and differentiating it 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 provides explicit usage guidance: 'Use this for PROGRAMMATIC OPERATIONS', 'Use this before any bulk update, delete, or enumeration task', and directs to open_document for human-readable reading. This is clear when-to-use and when-not-to-use with a named alternative.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered; the description adds the useful behavioral context that this is a static reference loadable ahead of bulk generation versus an in-session editing flow. It does not describe size or format of the returned content, so it stops short of full transparency.

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

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

Three sentences, front-loaded with what is returned and then the usage constraint. The 'especially Y-axis!' parenthetical is informal but signals a genuinely high-value rule; every sentence earns its place 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 carries the burden of explaining the return value, and it does so by enumerating the guide's sections. For a parameterless read-only reference tool, the definition is complete enough to select and invoke correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter claims are made that conflict with the empty 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 — 'Returns LLM-optimized instructions for generating Trident diagrams' — and enumerates the content (quick reference, rules, spacing, patterns, colors, checklist). It does not explicitly distinguish itself from sibling guide-like tools such as get_quick_start, get_trident_spec, and get_comprehensive_example, which leaves some ambiguity about which reference to load.

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

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

Explicitly states when to use it ('before generating Trident markup'), when it is not needed ('not needed up front in a live session that edits a document'), and names the alternatives (add_node / add_connection). It even scopes the exception case to domain conventions (BPMN/UML/flowchart, ERD, C4).

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 include readOnlyHint=true, so the read-only behavior is disclosed. The description adds context about the content brevity ('condensed 2-minute guide') and scope (minimal examples, core syntax), which helps set expectations about the return value. 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?

The description is two sentences: the first states the primary function and content, the second provides usage context. It is front-loaded with the main verb and contains no unnecessary 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 simple, zero-parameter read-only tool, the description adequately covers both the return content and the intended use case. However, it does not explicitly mention how this relates to other guides (e.g., get_comprehensive_example), which could provide more complete orientation for an agent.

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

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

The tool has zero parameters, and the schema is empty. With no parameters to document, the description is not required to explain them. The baseline score of 4 applies, and the description's mention of content type is sufficient.

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

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

The description clearly states the tool returns a 'condensed 2-minute quick-start guide' with specific content components (minimal working examples, core syntax, key concepts). The verb 'Returns' specifies the action, and the term 'condensed' distinguishes it from more comprehensive sibling tools like get_comprehensive_example.

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 provides explicit usage guidance: 'Use this for rapid learning when you need to generate simple diagrams quickly.' This implies a context of quick, simple tasks, but does not explicitly name alternative tools like get_comprehensive_example or get_generator_guide, so it lacks a direct exclusion statement.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds extra behavioral context: the document must be 'live', each entry includes authorship and timestamp, and a valid access token is required. This goes beyond the annotations without contradicting them.

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 three sentences, each serving a distinct purpose: stating the action, describing the value, and noting the requirement. There is no redundancy or unnecessary detail, and the most important information is front-loaded.

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

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

The tool is a read-only history query with a well-documented schema and clear return content described at a high level. There is no output schema, but the description indicates what each entry contains. It lacks details on pagination/error handling, but for this simple tool with good annotations, the description is sufficiently complete.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters. The description does not add detail beyond the schema, such as format constraints or examples. It mentions the token requirement but that is already in the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Returns') and resource ('recent change history for a live Trident document'), clearly distinguishing it from sibling tools like get_document_summary and get_document_png. It also specifies the content of each entry (who, what, when), leaving no ambiguity about the tool's function.

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 provides clear context: it is useful for understanding edits made by AI agents or human collaborators. While it does not explicitly state exclusions or alternatives, the intended use case is evident, and the sibling list offers related tools for 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 readOnlyHint=true and openWorldHint=true. The description adds value by disclosing the specific contents of the returned specification, which is useful behavioral context. It does not contradict annotations and provides sufficient transparency for a read-only getter.

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

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

The description is two sentences, front-loaded with the primary action, and every word earns its place. It is concise without losing key details.

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

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

For a simple, parameterless read-only tool without an output schema, the description fully covers what the tool does, what it returns, and when to use it. No additional context is needed.

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

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

The tool has zero parameters, so the description bears no obligation to explain parameter syntax or meaning. The baseline for 0-parameter tools is 4, and the description does not hinder parameter understanding in any way.

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 uses a specific verb 'Returns' and resource 'complete Trident 2D specification', enumerating contents (grammar, syntax, coordinate system, etc.). It clearly distinguishes itself from siblings like get_quick_start or get_comprehensive_example by emphasizing 'deep understanding'.

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 phrase 'Use this when you need deep understanding of the Trident DSL' provides clear context for when to use the tool. However, it does not explicitly name alternatives or state when not to use it, so it lacks the explicit exclusions that would earn 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?

The description adds significant behavioral details beyond annotations: the suggestion appears as a visible 'SUGGESTION:' callout with a radar pulse animation on the presence dot for 10 seconds, and it does not mutate the diagram. This complements the annotations (e.g., destructiveHint=false) and helps the agent understand the impact on the UI.

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 compact (roughly three sentences), front-loaded with the core purpose, and includes only necessary details. Each sentence contributes value—purpose, usage context, and behavioral transparency—without redundancy or filler.

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

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

For a relatively simple tool with no output schema, the description covers the essential context: what it does, when to use it, how it appears to collaborators, and the required access token. The parameter schema handles field-level details, so no additional context is needed.

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 input schema has 100% description coverage for all parameters, including detailed meanings for token, agentId, entityId, userName, and suggestion. The tool description itself does not add parameter-specific semantics beyond what the schema already provides, so the baseline score 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?

The description states a specific verb ('posts'), a clear resource ('a visible suggestion to human collaborators'), and a key distinguishing constraint ('WITHOUT making any changes to the diagram'). It clearly differentiates this from sibling tools that modify the diagram.

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 explicitly states when to use this tool ('when you observe something worth flagging — a potential mistake, an improvement, or a question') and clarifies that it is for flagging rather than acting. It does not explicitly name alternative tools or provide when-not-to-use scenarios, but the 'WITHOUT making changes' implies when not to use it.

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

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

Annotations already provide readOnlyHint and openWorldHint, so the bar is lower. The description adds valuable behavioral context: the returned DSL 'can be very large' and output 'may be truncated,' which is a significant caveat for the agent. It also uses 'live' to indicate dynamic content, reinforcing openWorldHint without contradicting annotations.

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

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

The description is compact and front-loaded: the first sentence immediately states the core function, the second clarifies intended use, and the third adds a critical caveat and alternative. Every sentence earns its place without redundancy or fluff.

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 characterizes the return value (Trident DSL, contents) and important constraints (large/truncated, live). It also covers the main usage distinction and access requirement. Given the tool's simplicity and strong schema/annotation support, the description is complete for an agent to decide and invoke 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% for all three parameters, so the schema does the heavy lifting. The description adds no new parameter-level details beyond saying a 'valid access token' is required, which is already implied by the schema description. Baseline 3 is appropriate.

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

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

The description states a specific verb+resource: 'Opens a live Trident document and returns its full contents as Trident markup DSL.' It clearly distinguishes the tool from siblings by contrasting with get_document_summary and framing this as the 'READ and UNDERSTAND' tool, not for enumerating IDs.

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 explicitly tells when to use this tool ('to READ and UNDERSTAND the diagram') and when not to ('Do NOT rely on this to enumerate entity IDs'), and points to a specific alternative (get_document_summary). It also emphasizes the requirement for a valid access token, giving clear usage context.

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

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

Beyond the annotation-provided write/idempotent/destructive hints, the description discloses partial-update semantics ('Only the fields you provide are changed') and the need for a valid editor access token. It does not describe side effects on collaborators or failure behavior, but adds meaningful context beyond annotations.

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

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

The description is four short sentences, each delivering distinct value: purpose, partial-update semantics, ID retrieval prerequisite, and auth requirement. No wasted words or repetition of schema 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?

The description provides the essential workflow (obtain IDs first, valid token, partial updates) and is sufficient given that the schema documents all parameters and annotations cover safety. It could mention return behavior or error conditions, but overall it is complete enough for a well-scoped update 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?

With 100% schema description coverage, the schema already documents each parameter. The description adds practical guidance by instructing the agent to obtain annotation IDs via get_document_summary, which directly clarifies the source of the annotationId parameter. It also reinforces the token requirement, slightly enhancing parameter semantics.

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

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

The description uses a specific verb ('Updates') and clearly scopes to 'an existing text annotation in a live Trident document,' distinguishing it from add_annotation and delete_annotation. It also clarifies partial-update behavior, leaving no ambiguity about its purpose.

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 instructs the agent to call get_document_summary first to obtain annotation IDs, which is essential prerequisite guidance. It also states the token requirement. While it doesn't explicitly list when not to use this tool, the context makes the usage scenario 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds key behavioral context: the coordinate system ('The position at (x, y) is the TOP-LEFT corner'), the live document effect, and the prerequisite of a valid token. This adds value without contradicting the annotations.

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

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

The description is a compact block of three sentences with a logical flow: what it does, how to get prerequisites, and a concrete use case. It is slightly verbose but every sentence carries actionable information, and the important usage note is front-loaded.

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

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

For a tool with a nested object and 6 params, the description covers the essential context: prerequisites, coordinate system, and intended use case. No output schema exists, but the description doesn't need to explain return values. It could mention error conditions or side effects, but overall it is sufficiently 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 input schema already provides 100% coverage with detailed parameter descriptions, including 'New top-left X position' etc. The description mostly repeats this information, though it reinforces the meaning of x/y via the top-left note and suggests scaling up width/height for usability. Since the schema does the heavy lifting, a baseline 3 is appropriate.

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

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

The description starts with a specific verb and resource: 'Repositions or resizes a background image (canvas graphic) in a live Trident document.' This clearly distinguishes it from sibling tools like update_node or add_annotation, which target different elements.

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

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

Explicit guidance is provided: 'USE THIS BEFORE placing many geographically-positioned nodes...' and 'Use open_document to get the canvas graphic ID and current dimensions.' It also notes the token requirement. However, it does not explicitly mention when not to use or name alternatives, so it falls short of a 5.

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

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

Annotations dispose of the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds non-obvious context the annotations lack: only provided fields are mutated, and an editor token is required. It does not cover failure modes for a bad containerId, so it stops short of a 5.

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

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

Four sentences, front-loaded with the core action, then prerequisites, then the resize special case. Efficient, though the parenthetical about edges at x±width/2 restates what the schema already says and could be trimmed.

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 annotations covering mutability and no output schema to explain, the description supplies what an agent needs: prerequisites, partial-update semantics, and the resize workflow. It lacks any statement about error behaviour or what a successful call returns, which 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 coverage is 83%, so the schema carries most parameter meaning. The description nonetheless adds real semantics for the resize case — that width/height must be enlarged to fit member nodes and x/y adjusted to keep the container centred over them — which the schema entries only hint 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?

States a specific verb and resource ('Updates properties of an existing container in a live Trident document') and goes further to name the two behaviours that matter most — partial update and resizing. The 'container' resource cleanly separates it from sibling update_node and update_annotation.

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: 'Use get_document_summary to get all container IDs before calling this', states the auth requirement ('Requires a valid editor access token'), and gives the condition for using the resize path ('whenever you add or move nodes outside a fixed-size container'). When-to-use and prerequisites 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?

The description discloses the key behavioral trait that this is a partial update ('Only the fields you provide are changed; others are preserved'), which goes beyond the annotations. It also mentions the live document context and the need for a valid editor access token. The annotations already indicate non-read-only, non-destructive, and idempotent behavior, so the description adds complementary value without 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?

The description is three concise, purposeful sentences. The main action is front-loaded, followed by the critical merge behavior and then the prerequisite and authentication note. No filler or redundant repetition of schema content is present.

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

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

For a mutating tool with no output schema, the description provides the essential context: what the tool does, how it behaves (partial update), how to obtain valid node IDs, and what authentication is required. It does not describe the return value or error behavior, but the schema and annotations cover most remaining operational details.

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 parameters. The description's emphasis on partial updates reinforces the meaning of the 'changes' object, but does not add new parameter-specific semantics beyond what the schema provides. This aligns with the baseline for high schema coverage.

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

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

The description clearly states the tool's function: 'Updates properties of an existing node in a live Trident document.' The phrase 'existing node' distinguishes it from add_node and delete_node, and the additional detail 'Only the fields you provide are changed; others are preserved' clarifies the exact scope of the operation.

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 guidance on prerequisites: 'Use get_document_summary to get all node IDs before calling this' and states the token requirement. It does not explicitly name alternatives or when not to use the tool, but the context is sufficient for an agent to select the correct sibling in most cases.

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 indicate read-only and open-world hints; the description adds that the tool returns a checklist (not an actual validator) and that the optional diagram parameter tailors tips to the specific diagram. This enriches the annotations with useful 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?

The description is two sentences with no redundant content. It front-loads the resource and coverage, then adds a concise usage directive. Every word earns its place.

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

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

For a read-only tool with one optional parameter and no output schema, the description covers the tool's purpose, content categories, and usage context. It could mention the checklist's format, but the provided information is sufficient for an agent 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?

The input schema fully documents the optional 'diagram' parameter, including its purpose (to include context-specific validation tips). The description adds no further parameter details beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns a comprehensive validation checklist for Trident diagrams, covering syntax rules, semantic rules, best practices, and common mistakes. This specific verb ('returns') and resource ('validation checklist') distinguishes it from sibling tools like get_trident_spec or explain.

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 explicitly advises to use this tool after generating a diagram to verify correctness, providing a clear usage context. It does not name alternatives or exclusions, but the guidance is sufficient for a read-only utility tool.

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