UDS Toolbox

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

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds substantial process detail beyond them: ISO-TP reassembly, request/response pairing including 0x78 responsePending, P2/P2* timing, session and security-access tracking, RequestDownload/TransferData reconstruction with CRC32, and DID extraction. This tells the agent exactly what the analysis performs.

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

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

Front-loads the purpose in the first sentence, then packs the accepted formats and analysis steps into a single dense second sentence where every clause names a concrete capability. No filler or restated boilerplate.

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

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

No output schema exists, and the description compensates by stating the return: a root-cause finding with the supporting frames plus an interactive timeline. Combined with the input-format guidance, an agent has everything needed to call and expect results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by mapping formats to parameters: text formats (candump, ASC, TRC, CSV) go in 'trace' or 'file', while binary formats (BLF, pcap/pcapng, MF4) require 'file' upload. That clarifies which parameter each format belongs in.

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: 'Analyze a whole CAN trace of a UDS diagnostic or flash session and say what went wrong.' The scope word 'whole trace/session' distinguishes it from the frame-level decoders (decode_isotp, decode_uds) in the sibling set.

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?

Implies usage by scoping to an entire diagnostic/flash session rather than individual frames, which steers agents away from the single-frame decoders. However, it never explicitly names an alternative or states when NOT to use it, so routing rests on inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is covered. The description usefully adds output shape ('hex with an annotated breakdown') and the input convention that numeric strings are hex, both of which go beyond the structured fields.

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

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

Two sentences, purpose front-loaded, no filler. The 16-service enumeration duplicates the schema enum and occupies most of the text, a minor redundancy in an otherwise tight definition.

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

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

For a 23-parameter tool without an output schema, the description compensates by stating the output format and the hex-string input convention. It lacks per-service guidance on which parameters combine, though the schema descriptions cover most of that ground.

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 87%, so per-parameter meaning is largely documented in the schema. The description adds one genuinely valuable cross-cutting convention ('Numeric strings are hex') that applies to many string parameters and is not itself in the schema.

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

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

States a specific verb and resource ('Build a UDS request as hex with an annotated breakdown'), plus the full set of supported services. The builder framing distinguishes it from the decode_* siblings, though it never names them explicitly.

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

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

The enumerated service list implies when the tool is applicable, but there is no explicit when-to-use, when-not, or routing to alternatives such as decode_uds or uds_reference. Usage is inferable rather than stated.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: the tool works in both directions, and supplying a status byte triggers per-bit explanation of the 8 DTC status bits.

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

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

Two dense sentences that front-load the primary transformation and then add the optional status-bit behavior. No filler, no repetition of the tool name.

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

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

With no output schema, the description carries the return-value burden and largely does so, naming the SAE J2012 code plus failure type byte and the status-bit breakdown. Exact output formatting (field names, layout) is still left implicit, which is the only gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by clarifying the accepted input forms for dtc and by explaining what the optional status byte actually produces (per-bit decoding), which the schema only labels as 'Optional status byte'.

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

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

States a precise verb (Convert) plus resource (3-byte UDS DTC) and both directions of the transformation, with concrete examples of each format. An agent can distinguish this DTC-specific tool from generic siblings like decode_uds without opening any schema.

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

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

Usage is implied by the input forms described ('01 23 45' or 'P0123-45'), but there is no explicit statement of when to reach for this versus decode_uds, decode_isotp, or uds_reference. The bidirectional nature is clear; the routing context is not.

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

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

With annotations covering the safety profile (readOnly, idempotent, non-destructive), the description still adds substantial behavioral detail: the specific report contents (SF/FF/CF/FC frame types, BS/STmin flow control, sequence-number errors, interrupted messages, padding, N_Bs/N_Cr timing warnings) and the condition under which timing analysis appears. It does not describe behavior on malformed or truncated input, which is the main remaining gap.

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

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

Two dense sentences with no filler, front-loading the core reassemble-then-decode action before output details. The second sentence is a long enumeration but each item earns its place by naming a distinct diagnostic class.

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

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

For a 3-parameter tool with no output schema, the description carries the return-value burden and does so by enumerating the diagnostic categories reported, plus both accepted input formats. It is nearly complete; only preconditions for timing analysis depth and malformed-input handling are left implicit.

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

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

Schema description coverage is 100%, so the meaning of each parameter (frames, padding, decodeUds) is already documented in the schema; the description only reinforces that timestamped input unlocks timing warnings. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific compound action (reassemble ISO-TP messages from CAN frames per CAN id, then decode as UDS) with the exact protocol standard, which unambiguously separates it from decode_uds (single payload) and build_uds_request (constructs requests). Verb+resource+scope are all present in the first clause.

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

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

The description implies when it applies by defining the accepted inputs (frame list or candump dump) and the precondition for timing warnings (timestamps in ms), but it never explicitly routes the agent between this tool and its siblings decode_uds or build_uds_request. Usage is inferable rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description adds real behavioral value: it enumerates what gets resolved (service, sub-function, suppressPosRsp bit, DID/RID fields, NRC with meaning and typical cause) and discloses graceful handling of unknown SIDs/NRCs (labelled, not rejected).

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

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

Three tightly packed sentences with zero filler; the core action is front-loaded and each clause conveys distinct decoding behavior. Nothing is redundant with the title or annotations.

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

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

There is no output schema, so the description must carry the return-value burden, and it does by enumerating every field returned for request, positive and negative responses. An agent has everything needed to call and interpret the tool.

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

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

Schema description coverage is 100% and both parameters (hex, direction) are documented there, including accepted byte formats and the enum values. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource: decode a UDS (ISO 14229-1) PDU from hex, covering request, positive and negative responses. This clearly separates it from the sibling build_uds_request (construction) and decode_dtc/decode_isotp (different protocol layers).

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

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

Usage is implied by the decode framing and the schema note that input has no ISO-TP header, which routes an agent toward decode_isotp for framing. However, the description never explicitly states when to use this over siblings or that direction is only an optional disambiguation hint.

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

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

Annotations already declare readOnlyHint/idempotent/destructiveHint=false, so the safe read nature is covered, and the description is consistent with that. Beyond annotations it adds genuinely useful behavior context: license terms (free noncommercial vs commercial) and the transport limitation (ISO-TP over CAN/CAN-FD, no DoIP), which pre-empts a wrong assumption about protocol support.

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

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

The purpose and deliverable list are front-loaded in the first sentence, and the second sentence adds only high-value constraint information. It is dense but every clause earns its place; no filler 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?

With no output schema, the description does partially compensate by listing what the plan contains (repo files, config hints, init skeleton, example, license), which tells an agent what it will get back. However, it omits any relationship between the input parameters and the result, leaving a real gap for a five-parameter 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 schema coverage at only 40%, the description is expected to compensate, yet it never explains any of the five parameters. Three enum parameters (role, rtos, transport) have no schema descriptions, and nothing in the prose clarifies how role/rtos/target/features shape the plan output.

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

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

The description names a specific verb and resource ('Plan how to integrate the UDSLib C stack') and enumerates the concrete deliverables (repo files, Kconfig hints, init skeleton, closest example, license terms), which is far more specific than a tautology. It is clearly distinguishable from the decode/build siblings, though it never explicitly contrasts itself with them.

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

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

Usage is only implied: an agent can infer this is the planning/research entry point for adopting UDSLib, but there is no 'use this when' statement or comparison to uds_reference. The line 'DoIP is not supported' functions as a soft when-not constraint, which is the main piece of routing guidance present.

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

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

Annotations already declare this a safe, idempotent, closed-world read, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the content is paraphrased rather than verbatim standard text, and unknown topics degrade gracefully to a topic list rather than erroring — both important for an agent deciding whether to trust or retry.

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

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

One dense paragraph, front-loaded with what the tool is and followed immediately by the accepted inputs and the fallback behavior. Every clause maps to a real decision the caller must make; nothing is padding.

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

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

For a single-parameter, no-output-schema reference tool, the description covers purpose, input vocabulary, and failure mode. The main remaining gap is that it does not characterize the depth or shape of the returned clause pointers, though 'short' and 'paraphrased' set expectations reasonably.

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 0% and the single parameter has no description, so the description carries the full burden — and it does, giving concrete accepted forms for every topic class (0x27 or name, 0x78 or "nrc 78", F190, FF00, p2, p2*, s3, reprogramming_sequence). An agent can construct a valid call without opening the schema.

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

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

States a specific resource ('UDS reference with ISO 14229-1 clause pointers') and enumerates the exact topic space it covers, which separates it cleanly from the build/decode siblings. It never names a sibling explicitly, but the 'reference/lookup' framing makes the distinction obvious.

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 topic enumeration implies when to reach for this tool (concept lookup during UDS work) and 'Unknown topics return a topic list' hints at how to recover from a miss. However, there is no explicit statement of when NOT to use it versus build_uds_request or decode_uds, leaving routing to inference.

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