reports / tt1wg8d953
wtf
15 tools · specification 1.2 · requested 2026-11-11 11:55:51 UTC
Server
- Overall
- A3.8definitions 70% · coherence 30%
- Definition quality
- A3.6mean 3.8 · min 3.4 · 15/15 tools
- Coherence
- A4.3
The wtf server offers a coherent set of 15 tools for waveform analysis, with clear distinctions between querying, rendering, and session management. Naming is consistent in style, and the tool count is well-scoped. Minor overlaps exist between find/values and view/render/user_view, but descriptions mitigate confusion. The shadow candidate is not a real risk because workspace and values serve fundamentally different purposes.
- 4
- DisambiguationMost tools have distinct purposes: open/sessions manage workspaces, find/values/records query data, render/view/user_view describe state, and protocols/info/help provide reference. However, 'find' and 'values' both return signal data over time, and 'view'/'user_view'/'render' overlap in describing the workspace, though descriptions clarify their different output formats.
- 4
- Naming ConsistencyTool names are mostly short, lowercase verbs (command, find, open, render, view) with a few nouns (sessions, signals, records, protocols). The pattern is consistent in style (all lowercase, no underscores or camelCase), but the mix of verbs and nouns is slightly inconsistent, though still predictable.
- 5
- Tool Count Appropriateness15 tools is well within the ideal range for a complex waveform analysis tool. Each tool covers a distinct aspect: navigation, querying, rendering, session management, and reference. The count feels appropriate for the domain's breadth.
- 4
- CompletenessThe tool set covers core workflows: opening traces, querying signals, decoding protocols, managing sessions, and presenting results. Minor gaps include lack of explicit save/export functionality and no direct way to modify the waveform, but these are not essential for analysis. The presence of 'help' and 'protocols' ensures users can discover capabilities.
Shadowing risk
- workspace (cost 9) may be shadowed by values (cost 2): workspace sets up the entire workspace (rows, cursors, range, decodes) in one call, while values only returns signal values over a range. An agent needing to configure the workspace cannot achieve that with values, as values does not modify state. The purposes do not overlap; workspace is a setup operation, values is a query.
Tools
command
433343B3.4The description is effective for a command execution tool, with clear purpose and useful examples. However, it lacks explicit usage guidelines relative to sibling tools and could provide more detail on side effects beyond the annotation of destructiveness.
- 4
- Purpose Clarity · 25%The description clearly states it runs a `:` command on the workspace, listing examples like `decode`, `protocol`, and `rows`. It distinguishes from siblings by specifying it executes commands rather than querying or rendering, though it doesn't name exact sibling tools.
- 3
- Usage Guidelines · 20%It explains that it executes `:` commands and mentions `help commands` for more options, but provides no explicit guidance on when to use command versus alternatives like `protocols` or `records`, or when not to use it.
- 3
- Behavioral Transparency · 20%Annotations include destructiveHint=true and readOnlyHint=false, so the description adds that it answers with rows added or removed and that `undo` can revert a step. This is helpful but does not specify what could be destroyed or that `undo` has limits.
- 3
- Parameter Semantics · 15%Schema coverage is 100% and the parameter description provides examples of valid input. The tool description adds minimal extra meaning beyond giving context that it executes commands on the workspace, so baseline 3 is appropriate.
- 4
- Conciseness & Structure · 10%The description is concise, with two sentences front-loading the purpose and including examples and undo behavior. No redundant or filler text.
- 3
- Contextual Completeness · 10%As a command executor with few parameters and no output schema, the description covers the basics. It could benefit from clarifying what 'rows' it changes and any prerequisites (e.g., workspace state), but it is reasonably complete for a simple command runner.
- params
- 1 (1 required, 100% described)
- annotations
- readOnly=false destructive=true idempotent=false openWorld=false
- output schema
- no
- cost
- 1
- bytes
- 617
- hash
- 5c79db16fe981ec6
find
443344A3.7The description is well-crafted for a complex search tool, clearly explaining the core purpose and key behavioral nuances like clock sampling. It leverages the schema's 100% parameter coverage, so it doesn't need to repeat parameter details. Minor gaps include lack of explicit alternatives and return value documentation, but overall it's a solid, informative description.
- 4
- Purpose Clarity · 25%The description clearly states the tool finds times when a search expression holds, and distinguishes between two modes (with and without a clock prefix). It differentiates from siblings like 'values' and 'view' by focusing on search-based time matching, though it doesn't explicitly name alternatives.
- 4
- Usage Guidelines · 20%The description explains when to use the clock prefix and when not, and mentions 'help decode' for buses, implying usage context. It doesn't explicitly state when not to use this tool versus alternatives, but the context is clear enough for an agent to infer.
- 3
- Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, so the description doesn't need to state safety. It adds useful behavioral details like the meaning of matches with and without clock, and the reporting time (cycle start vs. edge). However, it doesn't mention potential performance implications or edge cases like overlapping matches, which would be valuable.
- 3
- Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all parameters. The description adds context for 'expr' (search expression semantics) and 'show' (table of transfers), but doesn't add much beyond the schema. Baseline 3 is appropriate.
- 4
- Conciseness & Structure · 10%The description is compact and front-loaded with the core purpose. It uses technical jargon efficiently, but the sentence structure is dense and might be hard to parse for an agent. It earns its place with no fluff, but could be slightly clearer.
- 4
- Contextual Completeness · 10%Given the tool's complexity (8 parameters, expression language, clock semantics) and the rich schema descriptions, the description covers the key behavioral aspects. It doesn't explain return values, but no output schema exists, so that's a gap. However, the description is sufficient for an agent to use the tool correctly in most cases.
- params
- 8 (1 required, 100% described)
- annotations
- readOnly=true openWorld=false
- output schema
- no
- cost
- 1
- bytes
- 1682
- hash
- cfa689461a481027
help
443354A3.8The description is clear and concise, effectively communicating the tool's purpose as a conceptual reference and providing usage guidance. It leverages the readOnlyHint annotation well, and the parameter semantics are adequately covered by the schema and description. Minor gaps include not explicitly naming alternatives, but overall it's a well-crafted description for a simple tool.
- 4
- Purpose Clarity · 25%The description clearly states the tool is a reference for one concept, covering specific topics like names, patterns, times, etc. It distinguishes itself from siblings by focusing on conceptual help rather than commands or data retrieval, though it doesn't explicitly name alternatives.
- 4
- Usage Guidelines · 20%It provides clear guidance on when to use: 'Call it when an argument's doc or an error isn't enough.' This implies it's a fallback for insufficient documentation, but it doesn't explicitly state when not to use it or mention alternatives.
- 3
- Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, so the description doesn't need to state safety. It adds context about listing topics when no topic is given, which is useful. However, it doesn't describe the output format or any side effects, but with readOnlyHint, that's acceptable.
- 3
- Parameter Semantics · 15%Schema coverage is 100% for the single parameter 'topic', which is described as 'A topic; none lists them.' The description adds a list of example topics, which provides some additional meaning beyond the schema, but it's not extensive.
- 5
- Conciseness & Structure · 10%The description is concise, two sentences, and front-loaded with the core purpose. Every sentence adds value: the first defines the tool, the second lists topics and usage guidance. No wasted words.
- 4
- Contextual Completeness · 10%Given the tool's simplicity (one optional parameter, no output schema, read-only), the description is complete enough. It covers the purpose, topics, and when to use it. The lack of output schema means the description doesn't need to explain return values, and the tool's behavior is straightforward.
- params
- 1 (0 required, 100% described)
- annotations
- readOnly=true openWorld=false
- output schema
- no
- cost
- 0
- bytes
- 541
- hash
- 063a1cb618097f00
info
433453A3.6The description is concise and clear about the tool's purpose, providing a good overview of the open waveform. It lacks explicit usage guidance and some behavioral context, but given the zero-parameter nature and read-only annotation, it is adequate. Minor improvements could include mentioning prerequisites or distinguishing from sibling tools.
- 4
- Purpose Clarity · 25%The description clearly states the tool provides an overview of the open waveform, including file, time range, signals, and protocol decode interfaces. It is specific about the resource (open waveform) and the type of information returned, but it does not explicitly distinguish it from sibling tools like 'signals' or 'protocols'.
- 3
- Usage Guidelines · 20%The description implies this is a general overview tool for the current session, but it does not explicitly state when to use it versus alternatives like 'signals' or 'protocols'. There is no mention of when not to use it or any prerequisites.
- 3
- Behavioral Transparency · 20%The annotations declare readOnlyHint=true, and the description aligns with that by describing an informational read operation. It adds context about the content (file, time range, signals, decode lines) but does not disclose any additional behavioral traits such as whether it requires an open file or what happens if no file is open.
- 4
- Parameter Semantics · 15%The tool has zero parameters, so the description does not need to explain parameter semantics. The baseline for zero parameters is 4, and the description appropriately focuses on the output content.
- 5
- Conciseness & Structure · 10%The description is a single, concise sentence that front-loads the key information. Every word contributes to explaining what the tool returns, with no redundancy or filler.
- 3
- Contextual Completeness · 10%Given the tool has no parameters and no output schema, the description provides a reasonable overview of the return content. However, it could be more complete by mentioning whether it requires an open file or how it relates to other tools like 'signals' or 'protocols'.
- params
- 0 (0 required, 100% described)
- annotations
- readOnly=true openWorld=false
- output schema
- no
- cost
- 0
- bytes
- 293
- hash
- 8e28f4512cace080
open
544344A4.1The description effectively clarifies the tool's purpose, distinguishes between opening a trace and a session, and adds key behavioral details like not re-reading files and responding with 'info'. While it could explicitly mention exclusions, it is well-structured and provides adequate guidance given the comprehensive schema. No contradictions with annotations.
- 5
- Purpose Clarity · 25%The description clearly states the tool opens a trace file or session to select the working context for other tools. It distinguishes between the two modes (trace vs session) and names the resources (waveform files, workspaces). It differentiates from siblings like sessions (which lists sessions) and info (which lists interfaces).
- 4
- Usage Guidelines · 20%The description explains when to use each parameter: use 'trace' to open a waveform, use 'session' to return to a workspace. It also notes that neither re-reads the file after simulation updates, which guides usage. However, it doesn't explicitly state when not to use this tool or reference alternative tools beyond implying sessions for listing.
- 4
- Behavioral Transparency · 20%The description explains that opening neither re-reads the current file after simulation rerun (keeping rows), and that the tool answers with 'info' listing interfaces. The annotations only state non-read-only and non-destructive, which the description clarifies by implying state changes (new workspace or making session current) without data destruction. It adds context about responses and state behavior not covered by annotations.
- 3
- Parameter Semantics · 15%The schema already provides detailed descriptions for each parameter, covering paths and session IDs, with 100% coverage. The description adds some framing (best absolute path, from `sessions`) but doesn't add deeper semantics beyond that, like format details for the trace argument. Baseline is 3 due to high schema coverage.
- 4
- Conciseness & Structure · 10%The description is a single sentence, front-loaded with the core purpose and uses backticks for code. It is efficient and includes essential caveats. Minor redundancy with schema descriptions but overall concise.
- 4
- Contextual Completeness · 10%Given the tool has two optional parameters and rich sibling context, the description explains the effect of each parameter and the response ('info'), but doesn't detail the return format further (since no output schema). The complexity is moderate, and the description covers the main behaviors and response type, which is sufficient.
- params
- 2 (0 required, 100% described)
- annotations
- readOnly=false destructive=false idempotent=false openWorld=false
- output schema
- no
- cost
- 0
- bytes
- 851
- hash
- 9eac6f7ce47d1864
present
434444A3.8The description is clear and concise, effectively communicating the tool's purpose and behavior. It provides sufficient context for an agent to know when and how to use it, with no contradictions to annotations. Minor improvements could include explicit usage guidelines and clearer differentiation from sibling tools, but overall it is well-crafted.
- 4
- Purpose Clarity · 25%The description clearly states the tool's purpose: to show the workspace to the user as evidence, with two specific behaviors depending on whether wtf windows are open. It distinguishes itself from siblings like 'view' and 'workspace' by focusing on the presentation to the user, though it could be more explicit about the distinction.
- 3
- Usage Guidelines · 20%The description implies when to use it (when you need to present evidence to the user) and describes the two scenarios, but it does not explicitly state when not to use it or mention alternatives. The context is clear enough for an agent to infer usage, but lacks explicit guidance.
- 4
- Behavioral Transparency · 20%The description discloses key behavioral traits: it replaces the view of every wtf window, and if none are open, it writes a specific file. This goes beyond the annotations, which only indicate idempotentHint=true and destructiveHint=false. The description adds context about the side effect of writing a file, which is valuable.
- 4
- Parameter Semantics · 15%The tool has zero parameters, so the description does not need to explain parameter semantics. The schema coverage is 100% (vacuously), and the description focuses on behavior rather than parameters, which is appropriate. A baseline of 4 is given for zero-parameter tools.
- 4
- Conciseness & Structure · 10%The description is a single sentence that is concise and front-loaded with the main purpose. It includes necessary details about the two scenarios without unnecessary fluff. It could be slightly more structured, but it is efficient and earns its place.
- 4
- Contextual Completeness · 10%Given the tool's simplicity (no parameters, no output schema), the description is complete enough. It explains the two possible outcomes and the file path. The annotations cover safety, and the description covers behavior. There is no missing critical information for an agent to use it correctly.
- params
- 0 (0 required, 100% described)
- annotations
- readOnly=false destructive=false idempotent=true openWorld=false
- output schema
- no
- cost
- 0
- bytes
- 418
- hash
- 964145c132ba68b0
protocols
433354A3.6The description is clear and concise, effectively communicating the tool's purpose and usage. It leverages the schema for parameter details and adds the key behavior of listing all protocols when no name is given. Minor gaps include lack of explicit alternatives, but overall it is well-suited for agent selection.
- 4
- Purpose Clarity · 25%The description clearly states the tool's purpose: to list or describe protocols, with optional detail on roles, params, streams, and fields. It distinguishes itself from siblings like 'command' and 'find' by focusing on protocol metadata, though it doesn't explicitly contrast with 'info' or 'help'.
- 3
- Usage Guidelines · 20%The description implies usage: call with no name to list all protocols, or with a name to get details. It does not explicitly state when to use this over 'info' or 'help', but the context of protocol discovery is clear. No exclusions or alternatives are mentioned.
- 3
- Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, so the description doesn't need to state safety. It adds that the tool can list all protocols or describe a specific one, which is useful. However, it doesn't disclose any potential output size or performance implications, but given the read-only nature, this is acceptable.
- 3
- Parameter Semantics · 15%Schema description coverage is 100%, so the parameter 'name' is already documented. The description adds that 'none lists them all', which clarifies the optionality and behavior when omitted. This adds value beyond the schema, but not extensively.
- 5
- Conciseness & Structure · 10%The description is a single, compact sentence that packs essential information: what can be decoded, and what details are available with a name. It is front-loaded and every word earns its place.
- 4
- Contextual Completeness · 10%Given the tool's simplicity (one optional parameter, no output schema), the description is sufficient. It covers the main use cases: listing all protocols and getting details for a specific one. The read-only annotation covers safety, so no further behavioral disclosure is needed.
- params
- 1 (0 required, 100% described)
- annotations
- readOnly=true openWorld=false
- output schema
- no
- cost
- 0
- bytes
- 441
- hash
- d5cd3eef5ac82e0c
records
433344A3.5The description is clear and concise, effectively conveying the tool's purpose of listing decoded stream records. It leverages the schema for parameter details and provides adequate context for usage, though it could be improved by explicitly distinguishing from sibling tools and providing more behavioral details like default count and time unit handling.
- 4
- Purpose Clarity · 25%The description clearly states the tool lists records of a decoded stream as a table with specific columns (n, start, end, fields). It distinguishes from siblings by focusing on record listing, though it doesn't explicitly contrast with similar tools like 'values' or 'view'.
- 3
- Usage Guidelines · 20%The description implies usage for querying decoded stream records, and mentions filtering options like `where`, `group_by`, `count_only`. However, it does not explicitly state when to use this tool versus alternatives like 'values' or 'view', nor does it provide exclusions or prerequisites.
- 3
- Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, so the description doesn't need to repeat safety. It adds context about the table structure and time fields, but does not disclose details like default count (20) or time unit behavior, which are in the schema. No contradiction with annotations.
- 3
- Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all parameters. The description adds a brief mention of `where`, `group_by`, `count_only` but does not add meaning beyond what the schema provides. Baseline 3 is appropriate.
- 4
- Conciseness & Structure · 10%The description is a single sentence, front-loaded with the core purpose, and includes references to help commands. It is concise and structured, though it packs many details into one sentence, which slightly reduces readability.
- 4
- Contextual Completeness · 10%Given the tool's moderate complexity (9 params, 1 required) and full schema coverage, the description is sufficient. It explains the output format (table with n, start, end, fields) and mentions key filtering options. No output schema exists, but the description covers the return structure adequately.
- params
- 9 (1 required, 100% described)
- annotations
- readOnly=true openWorld=false
- output schema
- no
- cost
- 1
- bytes
- 1682
- hash
- 1d752481a595d5b5
render
433353A3.5The description is concise and clear about the tool's purpose, but it lacks explicit usage guidance and behavioral details beyond what annotations provide. It is a minimal viable description that does not contradict annotations, but it could be improved by adding when-to-use guidance and more context on output format.
- 4
- Purpose Clarity · 25%The description clearly states the tool's purpose: to draw signals over a time range as text, similar to wtf's screen, and to show the workspace when no signals are given. It distinguishes from siblings like 'view' and 'values' by specifying the text-based rendering and the fallback to workspace. However, it could be more explicit about the output being a textual representation, but it is clear enough.
- 3
- Usage Guidelines · 20%The description implies usage: when you want to see signals as text over a time range, or the workspace if no signals. It does not explicitly state when not to use it or mention alternatives like 'view' or 'values'. The context of 'as wtf's screen does' gives some hint, but there is no explicit guidance on choosing this over siblings.
- 3
- Behavioral Transparency · 20%Annotations indicate idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description does not contradict these, but it also does not add much beyond what annotations provide. It mentions the fallback to workspace when no signals, which is a behavioral trait not covered by annotations, but it does not disclose other aspects like whether it modifies state (though idempotent suggests it doesn't). Given the annotations, the description adds some value but not extensive.
- 3
- Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all parameters. The description does not add much beyond the schema; it mentions 'signals' and 'workspace' but does not elaborate on parameter semantics. Since coverage is high, baseline is 3, and the description does not significantly enhance understanding of parameters.
- 5
- Conciseness & Structure · 10%The description is extremely concise, one sentence, and front-loaded with the core action. It conveys the essential purpose without any fluff. Every word earns its place, making it highly efficient.
- 3
- Contextual Completeness · 10%Given the tool's moderate complexity (5 parameters, no output schema), the description is minimal but sufficient for a simple rendering tool. It does not explain return values, but since there is no output schema, the description could have provided more context on what the output looks like. However, the reference to 'wtf's screen' gives some idea. The description is adequate but not rich.
- params
- 5 (0 required, 100% described)
- annotations
- readOnly=false destructive=false idempotent=true openWorld=false
- output schema
- no
- cost
- 0
- bytes
- 972
- hash
- eb954eab12133e36
sessions
433444A3.6The description is clear and concise, effectively communicating the tool's purpose of listing open sessions. It leverages the read-only annotation and provides enough context for an agent to understand its use, though it could be more explicit about when to use it over sibling tools. Overall, it is a well-crafted description for a simple tool.
- 4
- Purpose Clarity · 25%The description clearly states that the tool lists open sessions (user's windows and agents' workspaces) with IDs and traces, and marks the user's own. It distinguishes from siblings by focusing on session listing, though it doesn't explicitly name alternatives.
- 3
- Usage Guidelines · 20%The description implies usage for viewing open sessions and mentions that 'open' starts or switches between them, but it does not explicitly state when to use this tool versus alternatives like 'view' or 'workspace'. It provides some context but lacks explicit exclusions.
- 3
- Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, so the description's read-only nature is covered. The description adds that it marks the user's own sessions and includes traces, which is useful context. However, it does not disclose details like whether the list is sorted or if there are any side effects, but given the read-only annotation, this is acceptable.
- 4
- Parameter Semantics · 15%The tool has zero parameters, so the description does not need to explain parameters. The baseline for 0 params is 4, and the description provides a clear overview of what the tool returns, which is sufficient.
- 4
- Conciseness & Structure · 10%The description is concise, two sentences, and front-loaded with the main purpose. The second sentence adds a hint about the 'open' command, which is relevant but not essential. No wasted words.
- 4
- Contextual Completeness · 10%Given the tool has no parameters, no output schema, and read-only annotations, the description is fairly complete. It explains what the tool lists and marks, and hints at related functionality. It could mention the format of traces or IDs, but for a simple listing tool, it is adequate.
- params
- 0 (0 required, 100% described)
- annotations
- readOnly=true openWorld=false
- output schema
- no
- cost
- 0
- bytes
- 320
- hash
- 91310554a900caf3
signals
544354A4.2The description is concise and effective, clearly explaining the tool's purpose and regex syntax. It leverages the schema well and adds useful behavioral details like case-insensitivity and the 'none' case. Minor gaps include lack of explicit usage guidance versus siblings, but overall it's a strong description.
- 5
- Purpose Clarity · 25%The description clearly states the tool searches the waveform's design, scopes, and signals using a regex pattern, with a specific example of grep-like syntax. It distinguishes itself from siblings like 'find' and 'values' by focusing on signal path search.
- 4
- Usage Guidelines · 20%The description explains the regex syntax and provides examples, but does not explicitly state when to use this tool versus alternatives like 'find' or 'values'. However, the context of searching signal paths is clear enough for an agent to infer appropriate usage.
- 4
- Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, so the description doesn't need to repeat that. It adds useful behavioral details: the regex is case-insensitive, matches anywhere in the path, and the 'none' pattern lists all signals folded to fit. This goes beyond the schema's parameter description.
- 3
- Parameter Semantics · 15%The schema description covers 100% of the parameter, including regex syntax and examples. The description adds a bit of context (grep-like, case-insensitive) but mostly reiterates what the schema already provides. Baseline 3 is appropriate.
- 5
- Conciseness & Structure · 10%The description is a single, dense sentence that packs in the purpose, syntax, and behavior without wasted words. It is front-loaded with the core action and includes examples inline.
- 4
- Contextual Completeness · 10%Given the tool's simplicity (one optional parameter, no output schema), the description is complete enough. It covers the search behavior, regex format, and the 'none' case. It could mention the return format, but that's not critical for a search tool.
- params
- 1 (0 required, 100% described)
- annotations
- readOnly=true openWorld=false
- output schema
- no
- cost
- 0
- bytes
- 623
- hash
- 9c8727d50e42ed1a
user_view
444344A3.9The description effectively communicates the tool's purpose and the optional 'adopt' behavior, with clear guidance on when it changes state and how to undo. It leverages the schema for parameter details and adds useful behavioral context beyond the annotations. Minor clarity issues in phrasing prevent a higher score, but overall it is a well-crafted description for a simple tool.
- 4
- Purpose Clarity · 25%The description clearly states the tool shows what the user is looking at in their 'wtf window' on the trace, and it distinguishes itself from the sibling 'view' tool by focusing on the user's perspective. It also mentions the optional 'adopt' behavior, which adds specificity. However, the phrasing is somewhat cryptic ('wtf window', 'view words the workspace'), which may reduce clarity for an agent unfamiliar with the domain.
- 4
- Usage Guidelines · 20%The description implies when to use this tool: to see the user's current view, and it explicitly notes that it changes nothing unless 'adopt' is set. It also mentions that 'command undo' can revert the adoption, providing a clear context for usage. However, it does not explicitly contrast with sibling tools like 'view' or 'workspace', so the guidance is not fully explicit.
- 4
- Behavioral Transparency · 20%The description discloses that the tool is read-only by default ('Changes nothing unless adopt'), and that adopting replaces the workspace's rows, cursors, and range, dropping the agent's own, with an undo step available. This goes beyond the annotations, which already indicate destructiveHint=true and idempotentHint=true, by explaining the specific destructive action and recovery mechanism. No contradiction with annotations.
- 3
- Parameter Semantics · 15%The schema already provides a detailed description for the 'adopt' parameter, covering its effect and the undo step. The tool description adds a brief mention of 'adopt' but does not add significant new meaning beyond the schema. Since schema coverage is 100%, a baseline of 3 is appropriate.
- 4
- Conciseness & Structure · 10%The description is a single, dense sentence that packs a lot of information, but it is not overly long. It front-loads the core purpose and then explains the optional behavior. However, the phrasing is somewhat convoluted ('worded as `view` words the workspace'), which could be simplified for better readability, but it is still concise overall.
- 4
- Contextual Completeness · 10%Given the tool's simplicity (one optional parameter, no output schema), the description covers the essential aspects: what it shows, when it mutates, and how to revert. The annotations provide additional safety hints. The description is sufficient for an agent to use the tool correctly, though the cryptic terminology might require domain knowledge.
- params
- 1 (0 required, 100% described)
- annotations
- readOnly=false destructive=true idempotent=true openWorld=false
- output schema
- no
- cost
- 0
- bytes
- 760
- hash
- f30ebfd82398f2e5
values
544354A4.2The description is well-crafted, clearly stating the tool's purpose and usage context, and it adds valuable behavioral details beyond the annotations. It effectively distinguishes itself from the sibling 'find' tool. Minor gaps exist in explicit usage exclusions and return value details, but overall it is a strong description.
- 5
- Purpose Clarity · 25%The description clearly states the tool's purpose: it returns values of signals over a time range, with specific behavior for a single time point and for structs/arrays. It distinguishes itself from the sibling tool 'find' by explicitly noting that 'find' is for when something happens, while this tool is for values.
- 4
- Usage Guidelines · 20%The description provides clear context on when to use this tool (to get signal values over time) and explicitly mentions an alternative ('find') for event-based queries. However, it does not explicitly state when not to use this tool or provide exclusions beyond that single alternative.
- 4
- Behavioral Transparency · 20%The description adds behavioral details beyond the readOnlyHint annotation: it explains the output format (time value lines), the inclusive nature of 'to', the behavior for structs/arrays (listing fields), and the special case of omitting 'to' for a single time. This is valuable context that the annotation does not provide.
- 3
- Parameter Semantics · 15%The schema already provides detailed descriptions for all parameters (100% coverage), including units, radix, and signal path hints. The description adds minimal extra meaning beyond what the schema states, but it does clarify the output format and the special case of omitting 'to', which is not fully captured in the schema. Baseline 3 is appropriate.
- 5
- Conciseness & Structure · 10%The description is concise and front-loaded: it starts with the core purpose, then explains the output format, and ends with a pointer to an alternative. Every sentence adds value, and it is appropriately sized for the tool's complexity.
- 4
- Contextual Completeness · 10%Given the tool's moderate complexity (5 parameters, no output schema), the description covers the essential behavior: output format, time range semantics, and struct/array handling. It does not explain return values in detail, but since there is no output schema, the description could be more explicit about the exact structure of the response. However, the provided details are sufficient for most use cases.
- params
- 5 (2 required, 100% described)
- annotations
- readOnly=true openWorld=false
- output schema
- no
- cost
- 2
- bytes
- 1020
- hash
- 8819ffe933d895d5
view
433354A3.6The description is clear and concise, effectively distinguishing the tool from its siblings. It leverages annotations well and provides adequate context for a simple read-only tool. Minor gaps exist in explicit usage guidelines, but overall it is well-crafted.
- 4
- Purpose Clarity · 25%The description clearly states the tool's purpose: to describe the workspace in words, including rows, cursors, and visible range. It distinguishes itself from siblings by explicitly contrasting with 'render' (drawn) and 'user_view' (user's window), which helps differentiate it from similar tools.
- 3
- Usage Guidelines · 20%The description implies usage by contrasting with 'render' and 'user_view', but it does not explicitly state when to use this tool versus alternatives. It provides some context (e.g., it's a textual description) but lacks explicit when-to-use or when-not-to-use guidance.
- 3
- Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, so the description doesn't need to state that it's read-only. The description adds context about what it describes (rows, cursors, visible range) and the time between cursors, which is useful. However, it doesn't disclose any other behavioral traits like output format or potential limitations, but given the annotations, this is adequate.
- 3
- Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents the 'unit' parameter. The description does not add any additional meaning beyond what the schema provides, so the baseline of 3 is appropriate.
- 5
- Conciseness & Structure · 10%The description is extremely concise, with two sentences that pack in the core purpose and sibling differentiation. Every word earns its place, and it is front-loaded with the main action.
- 4
- Contextual Completeness · 10%Given the tool's simplicity (one optional parameter, no output schema, read-only annotation), the description is complete enough. It explains what the tool does and how it differs from related tools, which is sufficient for an agent to use it correctly.
- params
- 1 (0 required, 100% described)
- annotations
- readOnly=true openWorld=false
- output schema
- no
- cost
- 0
- bytes
- 474
- hash
- 9f53e29e591039ad
workspace
Shadowing Risk543354A4.0The description is clear and concise, effectively distinguishing the tool from siblings by emphasizing its bulk setup role. It leverages the schema well, with 100% parameter coverage, and provides adequate usage context. Minor gaps exist in behavioral transparency regarding destructive effects, but annotations partially cover this. Overall, a well-crafted description for a complex tool.
- 5
- Purpose Clarity · 25%The description clearly states the tool's purpose: 'Set up the whole workspace in one call' and lists the key components (rows, cursors, range, decodes). It distinguishes itself from siblings like 'view' by noting it answers 'as view does' but sets up the workspace, implying a broader scope. The verb 'Set up' is specific and the resource is the workspace.
- 4
- Usage Guidelines · 20%The description implies usage: it is for setting up the whole workspace in one call, as opposed to individual tools like 'view' or 'decode'. It references 'help workspace' for more details, but does not explicitly state when not to use it or name alternatives. The context is clear enough for an agent to infer it is a bulk setup tool.
- 3
- Behavioral Transparency · 20%Annotations indicate destructiveHint=true and idempotentHint=true, but the description does not mention that this tool may overwrite existing workspace state or that it is idempotent. It does add context that it sets up 'the whole workspace' and answers as 'view' does, but does not disclose potential side effects like resetting the view or replacing existing decodes. With annotations present, the bar is lower, but the description could add more about what gets replaced or reset.
- 3
- Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all parameters. The description adds a high-level summary of what the parameters do (rows, cursors, range, decodes) but does not add detailed semantics beyond the schema. For example, it does not explain the interaction between 'scope' and 'rows' or the default behavior of 'range'. Baseline 3 is appropriate given the schema's thoroughness.
- 5
- Conciseness & Structure · 10%The description is two sentences, front-loaded with the main purpose, and includes a helpful pointer to 'help workspace'. Every word earns its place, and it is concise without being under-specified.
- 4
- Contextual Completeness · 10%Given the tool's complexity (7 parameters, nested objects, no output schema), the description is reasonably complete. It covers the main components and points to help for details. However, it does not explain the return value or the effect of the 'scope' parameter, but the schema covers parameter details. The description is sufficient for an agent to understand the tool's role and invoke it correctly.
- params
- 7 (1 required, 100% described)
- annotations
- readOnly=false destructive=true idempotent=true openWorld=false
- output schema
- no
- cost
- 9
- bytes
- 3868
- hash
- 6db4eabb63f38357
Deterministic findings
- warningworkspace shadow-candidateworkspace (invocation cost 9) may be shadowed by values (cost 2): if both can answer the same question, an agent tends toward the cheaper call. Only the coherence evaluation can confirm the purposes overlap; if they do, make them disjoint and say so in both descriptions, or collapse the pair.
- infocommand no-output-schemacommand has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
- infofind no-output-schemafind has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
- infohelp no-output-schemahelp has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
- infoinfo no-output-schemainfo has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
- infoopen no-output-schemaopen has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
- infopresent no-output-schemapresent has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
- infoprotocols no-output-schemaprotocols has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
- inforecords no-output-schemarecords has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
- inforender no-output-schemarender has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
- infosessions no-output-schemasessions has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
- infosignals no-output-schemasignals has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
- infouser_view no-output-schemauser_view has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
- infovalues no-output-schemavalues has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
- infoview no-output-schemaview has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
- infoworkspace no-output-schemaworkspace has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
Automate
The same check from a terminal, a CI job or a script, with an API key from your account. Submitting spends one of the account's daily calls; reading the result spends nothing.
The exit code is the verdict, so the command is the gate. A stdio command or a server URL can stand in for the file.
export TDQS_API_KEY=tdqs_...
# exit code 1 below B, so the command is the gate; uvx runs the same command from PyPI
npx mcp-tdqs score --file tools.json --hosted https://tdqs.dev --fail-under BSubmitting answers at once with the report's address. Its score is null until the status is completed, and the overall tier is on the server score.
curl https://tdqs.dev/api/v1/reports \
-H 'Authorization: Bearer tdqs_...' \
-H 'Content-Type: application/json' \
-d @tools.json
# poll the report it names until "status" is "completed"; this one is
curl https://tdqs.dev/api/v1/reports/tt1wg8d953 \
-H 'Authorization: Bearer tdqs_...'The package submits the definitions and polls until the report is done; what comes back is the same object the API returns. The scorer itself is exported too, for a model of your own.
import { requestHostedReport } from 'mcp-tdqs';
const report = await requestHostedReport({
apiKey: 'tdqs_...',
hostedUrl: 'https://tdqs.dev',
serverName: 'wtf',
tools, // the tools/list result
});
if (report.score === null || !['A', 'B'].includes(report.score.serverScore.overallTier)) {
throw new Error(`TDQS ${report.score?.serverScore.overallTier ?? 'failed'}: ${report.url}`);
}The same helper for Python: it submits the definitions, polls until the report is done, and returns the report as a pydantic model. The scorer itself is exported too, for a model of your own.
from tdqs import parse_tool_definitions, request_hosted_report
parsed = parse_tool_definitions(tools_list) # the tools/list result
report = request_hosted_report(
api_key="tdqs_...",
hosted_url="https://tdqs.dev",
server_name="wtf",
tools=parsed.tools,
)
tier = report.score.server_score.overall_tier if report.score is not None else None
if tier not in ("A", "B"):
raise SystemExit(f"TDQS {tier or 'failed'}: {report.url}")