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 indicate readOnlyHint=false and destructiveHint=false. The description adds that it operates on a 'live' document and requires a valid token, but does not elaborate on side effects, reversibility, or failure behavior. It does not contradict annotations and adds some context, but could disclose more about mutation consequences.

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 concise sentences that front-load the action and include a prerequisite and requirement. No redundant phrasing, every sentence contributes.

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 add operation with a nested object and no output schema, the description covers the essential use case: purpose, prerequisites, and access requirements. It could mention how to obtain the token or what happens with invalid IDs, but the schema and context (live document) make it 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 80% (only the nested 'connection' object lacks an explicit description). The description adds the meaning 'arrow/edge' and references source/target IDs, but the schema already explains most parameters. The added value is marginal, 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 clearly states the tool's action: 'Adds a connection (arrow/edge) between two nodes in a live Trident document.' This uses a specific verb (adds) and resource (connection) and distinguishes it from siblings like add_node and add_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?

Provides a clear prerequisite: 'Use get_document_summary to get valid source and target node IDs before calling this.' It also notes the requirement for a valid editor access token. While it doesn't explicitly discuss alternatives or when not to use the tool, the guidance is actionable and contextually grounded.

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 readOnlyHint=false and openWorldHint=true, so the mutation aspect is clear. The description adds value by specifying the operation targets a 'live' document and requires an editor access token, which are not in the annotations. It also hints at duplicate concerns, though it doesn't describe the exact behavior on duplicate 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 concise, informative sentences. It delivers the core purpose, a practical pre-check tip, and an authorization requirement with no filler or redundant phrasing.

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 covers the tool's main purpose, the container concept, a useful pre-check workflow, and auth requirements. With no output schema and only moderate complexity, this is a solid but not exhaustive explanation. It could have described return values or duplicate-handling behavior, but it's adequate for an add operation.

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

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

Schema description coverage is 80%, so the input schema already documents most parameters. The description adds context about containers and suggests checking IDs, but does not elaborate on the meaning or format of parameters like agentId, userName, or action_explanation beyond what the schema provides. This aligns with the baseline for high 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 'adds a new container (group/swimlane) to a live Trident document' and explains that containers 'visually group related nodes.' This specific verb+resource+scope distinguishes it from sibling tools like add_node, add_connection, and add_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?

It explicitly advises using get_document_summary to check existing container IDs before adding to avoid duplicates, which serves as an alternative-tool recommendation and a precondition. It also notes the requirement for a valid editor access token. However, it does not explicitly state when to avoid adding or what to do if a duplicate exists, so it's not fully exhaustive.

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 reveals behavior beyond annotations: nodes appear immediately for all collaborators, a valid editor access token is required, and orphaned nodes create visual churn. This adds context about side effects that annotations alone (readOnlyHint=false, openWorldHint=true) do not convey. 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 longer than average but every sentence carries essential operational guidance: action, live visibility, auth requirement, prerequisite calls, the container warning, and the orphaned-node consequence. It is front-loaded with the core purpose and then proceeds to actionable guidance without 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?

For a mutating tool with a nested node object and no output schema, the description covers prerequisites, auth, side effects, and critical parameter timing. It does not need to explain return values since no output schema exists. The tool is well-contextualized within the sibling toolset.

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. The description adds valuable parameter-level guidance beyond schema, such as 'Set this NOW if you know the parent — do not create the node orphaned', and 'Set on THIS call — do not add the node and recolor it later'. This enriches parameter semantics, but some parameter details (like icon or shapeType) are not further elaborated, so a 4 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 'Adds a new node (entity) to a live Trident document' with a specific verb and resource. It distinguishes itself from sibling tools like add_connection and add_container, and includes immediate effects ('node appears immediately for all collaborators').

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 when to use this tool: call open_document and get_document_summary before adding nodes, and provides a strong when-not-to-use warning about creating orphaned nodes and reparenting later via update_node. It also gives clear guidance about setting container and color on this call instead of updating later.

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 convey readOnlyHint=true and openWorldHint=true, indicating a safe, non-mutating informational tool. The description adds behavioral context by noting the output is 'LLM-optimized' and listing the specific content domains, which helps the agent anticipate the response nature beyond the raw annotation flags.

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

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

The description is a single, front-loaded sentence that efficiently enumerates the included sections without unnecessary filler. Every clause adds value, and the imperative 'Use this before generating any Trident diagram' is a clean closing guideline.

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 guide tool with no parameters and no output schema, the description fully covers what the tool returns and when to use it. The tool's simplicity does not require additional return-value documentation, and the guidance is sufficient for agent selection.

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 schema provides no burden. The description adds no parameter semantics, but with no parameters, a baseline of 4 is appropriate per the rubric (0 params = baseline 4).

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 LLM-optimized instructions for generating Trident diagrams, with an explicit inventory of content (quick reference, critical rules, spacing, patterns, colors, checklist). This specific verb+resource combination distinguishes it from sibling guide tools like get_quick_start and get_trident_spec by emphasizing its role as a comprehensive pre-generation 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?

The description explicitly directs when to use the tool: 'Use this before generating any Trident diagram.' This is a clear usage context, though it does not mention alternatives or when not to use it, which would be needed for a perfect score.

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 already indicate non-read-only (readOnlyHint=false), non-destructive (destructiveHint=false), and idempotent (idempotentHint=true). The description adds meaningful behavioral context: 'Only provided fields are changed' clarifies the idempotent partial-update behavior, and 'live Trident document' plus the token requirement provide additional 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?

Three concise sentences with no fluff. The main action is front-loaded, followed by partial-update semantics and a practical prerequisite. Every sentence earns its place, and the description is appropriately sized for the tool's complexity.

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

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

The tool has 6 parameters, a nested object, no output schema, and moderate complexity. The description covers the core action, partial update behavior, prerequisite for obtaining container IDs, and auth requirement. It does not explain error handling or return values, but given the idempotent and non-destructive annotations, it is reasonably complete. A 4 is appropriate.

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 83% (baseline 3), and the description adds important meaning to the 'changes' parameter by stating 'Only provided fields are changed.' This directly clarifies the semantics of the nested changes object, which lacks a schema description. It also references containerId via the prerequisite, adding context.

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 'Updates properties of an existing container in a live Trident document', which is a specific verb+resource combination. It distinguishes itself from sibling tools like update_node and update_annotation by explicitly targeting containers, and additionally clarifies the partial-update semantics with 'Only provided fields are changed.'

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

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

The description gives a clear prerequisite: 'Use get_document_summary to get all container IDs before calling this.' It also requires a valid editor access token. However, it does not explicitly state when to use this tool over alternatives (e.g., update_node for nodes), so it lacks full 'when-not-to-use' 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?

Adds key behavior beyond annotations: partial-update semantics ('Only the fields you provide are changed; others are preserved') and auth requirement ('Requires a valid editor access token'). Annotations already cover readOnly/destructive hints, so description enriches context.

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

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

Three concise sentences each add value: purpose, partial-update behavior, and prerequisite/auth. No 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?

For a moderate-complexity tool with a nested changes object and no output schema, the description covers core usage, precondition, and auth. It doesn't explain failure behavior or return values, but with annotations and schema, this is adequate.

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 3. The description adds a small hint about obtaining nodeId via get_document_summary, but most parameter meaning is already in the schema; no significant extra 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?

Clearly states a specific verb ('Updates'), resource ('properties of an existing node'), and context ('live Trident document'). Distinguishes from siblings like add_node, update_annotation, and update_container by specifying 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?

Provides a clear prerequisite ('Use get_document_summary to get all node IDs') but does not explicitly contrast with alternatives like update_annotation or update_container. The context implies usage for existing node property updates.

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.