Server Quality Checklist

Tool Scores

• cancel_runB
  3.1/5.0
  Behavior2/5

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

  No annotations are provided, so the description must disclose behavior. It only states the action without detailing side effects, permissions, or whether cancellation is immediate or reversible. This is minimal information beyond the action itself.

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

  Conciseness5/5

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

  A single sentence that is front-loaded and contains zero wasted words. It conveys the verb and object clearly without filler or repetition.

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

  Completeness2/5

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

  For a mutation tool with no annotations, the description is too sparse. It does not mention prerequisites (e.g., the run must be running), what happens after cancellation, or potential errors. Sibling tools like run_and_wait and get_run_status suggest a workflow, but this description does not position itself within that context.

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

  Parameters1/5

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

  The input schema has two required parameters with 0% description coverage, and the description does not mention either parameter. The parameter names are self-explanatory, but the description adds no meaning and fails to compensate for the lack of documentation.

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

  Purpose5/5

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

  The description uses the specific verb 'cancel' and identifies the resource 'Hex project run', clearly distinguishing it from sibling tools like run_project or get_run_status. It unambiguously states the action.

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

  Usage Guidelines3/5

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

  The context 'running' implies the tool should be used when a project run is in progress and needs to be stopped. However, no explicit alternatives, exclusions, or when-not-to-use scenarios are mentioned.

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

• get_run_historyB
  3.2/5.0
  Behavior2/5

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

  No annotations are provided, so the description must carry the burden. The word 'Get' implies a read-only operation, but the description does not disclose behavior such as result ordering, whether the history is paginated, what constitutes 'recent', or any limitations. It adds minimal behavioral context beyond the function name.

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

  Conciseness5/5

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

  The description is two concise sentences with no filler. The main action is front-loaded, and the use case adds practical value without bloat.

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

  Completeness3/5

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

  Given an output schema exists and the tool is a simple read operation, the description covers the core purpose and a specific use case. However, it lacks parameter semantics and behavioral details like ordering or pagination, leaving gaps for a complete understanding. It is adequate but not comprehensive.

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

  Parameters1/5

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

  Schema description coverage is 0%, and the description does not mention the 'limit' or 'project_id' parameters. The schema provides types and default, but the description adds no semantic meaning, leaving the agent to infer that 'limit' controls the number of results and 'project_id' identifies the project. This is insufficient for low coverage.

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

  Purpose4/5

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

  The description uses the specific verb 'Get' with the resource 'recent run history' and identifies the scope 'for a project'. It clearly indicates a read operation distinct from sibling tools like run_project or cancel_run, though it doesn't explicitly name alternatives. The added purpose 'spotting patterns in recurring failures' reinforces its analytical intent.

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

  Usage Guidelines4/5

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

  The sentence 'Useful for spotting patterns in recurring failures' provides a clear context for when to use the tool, but it lacks explicit exclusions or references to alternative tools such as get_run_status. This is clear context without exclusions, placing it at a 4 rather than a 5.

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

• inject_pydeck_mapA
  3.6/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral burden. It discloses the dark map style, color fallback behavior, and that auto_run triggers run_and_wait. However, it does not clarify whether the existing cell content is overwritten or whether any permissions are required, which is notable for a mutation tool.

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

  Conciseness4/5

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

  The description is concise and front-loaded, leading with the main purpose and then using a compact bullet-style list for parameter details. No filler or redundant content appears, though some parameter specifics could be moved into the schema.

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

  Completeness3/5

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

  For an 11-parameter mutation tool with no annotations, the description covers the most crucial options and behavior, and an output schema exists. Still, it lacks prerequisites (e.g., dataframe_var must contain lat/lon columns) and full parameter semantics, leaving some gaps for a complex tool.

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

  Parameters3/5

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

  The description adds useful semantics for layer_type, color_col, elevation_col, and auto_run, partly compensating for the 0% schema description coverage. However, it omits context for required parameters like lat_col/lon_col and other options like radius/title, so parameter understanding is incomplete.

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

  Purpose5/5

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

  The description opens with a specific verb ('Write') and resource ('styled PyDeck map into a Hex Python cell'), immediately identifying the tool's function. Mentioning 'PyDeck map' clearly distinguishes it from sibling tools like inject_plotly_chart and inject_html_component.

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

  Usage Guidelines3/5

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

  The description implies a map-injection use case but provides no explicit guidance on when to choose this tool over the sibling inject_* tools. There are no exclusions or alternative recommendations, leaving usage to be inferred from the tool name and purpose.

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

• get_run_statusA
  3.7/5.0
  Behavior3/5

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

  No annotations are provided, so the description must carry the transparency burden. It adds value by enumerating the possible status values and advising to check elapsedTime and error details on ERRORED runs. However, it does not disclose whether the operation is read-only, has rate limits, or any other side effects. For a simple polling tool, the provided details are helpful but not exhaustive.

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

  Conciseness5/5

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

  The description is concise (three sentences) and front-loaded with the core purpose. The second sentence provides a compact enum of status values, and the third gives a practical tip for handling errors. Every sentence earns its place, with no redundant details.

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

  Completeness4/5

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

  Given the tool's low complexity, the presence of an output schema (which covers return values), and the description's inclusion of status enum and error-handling guidance, the description is largely complete. The only gap is the lack of explicit guidance on when to use this polling tool versus alternatives like run_and_wait, but this does not severely hinder a capable agent.

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

  Parameters2/5

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

  Schema description coverage is 0% and the description does not explain the meaning or format of run_id and project_id. While the names are self-explanatory, the description should compensate for the lack of schema documentation, and it does not. The tool description adds no semantic value beyond the parameter names themselves.

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

  Purpose5/5

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

  The description clearly states the tool's action ('Poll the status of a project run') and identifies the resource (project run). It distinguishes from siblings by focusing on status polling rather than execution (run_project), cancellation (cancel_run), or history (get_run_history). Listing the specific status values reinforces this unique purpose.

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

  Usage Guidelines3/5

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

  The description implies usage for checking run status by saying 'Poll the status', but it does not explicitly state when to use this over alternatives like run_and_wait (which likely waits for completion) or get_run_history (which lists past runs). No when-not-to-use guidance is provided, making this merely implied rather than explicit.

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

• list_projectsA
  3.8/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden and accurately states the read-only listing behavior and returned fields. It does not disclose limit semantics, ordering, or edge cases, but for a simple list operation this is acceptable though not rich.

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

  Conciseness5/5

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

  Two short sentences, front-loaded with the main action, and no filler. Every sentence adds value: the first states scope, the second explains optional filtering and return value relevance.

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

  Completeness4/5

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

  The description is complete for a simple list tool, especially with an output schema already covering return structure. It adds the key context that returned IDs/URLs are needed for other tools, but does not mention the meaning of 'limit' or pagination behavior.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description must compensate. It explains 'search' as a name substring filter, which is helpful, but 'limit' is only recognizable from its name/schema default and is not described in text.

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

  Purpose5/5

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

  Description uses a specific verb ('List') and resource ('Hex projects in the workspace'), clearly indicating a collection operation. It distinguishes from siblings like get_project by emphasizing plural projects and returning IDs/URLs for use by other tools.

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

  Usage Guidelines3/5

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

  The description implies when to use the tool: when you need project IDs, names, or app URLs for other tools, and optionally filtering by name substring. However, it does not explicitly contrast with get_project or 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.

• run_and_waitA
  3.8/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden and does a good job: it says it polls until completion or error, returns final run status with error details, and causes automatic app refresh. It does not mention timeout behavior or potential side effects of executing code, but core behavior is clear.

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

  Conciseness5/5

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

  The description is three concise sentences, front-loaded with the primary purpose, followed by the usage scenario and expected outcome. Every sentence earns its place with no informational redundancy or fluff.

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

  Completeness3/5

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

  The description clearly conveys purpose and outcome, and the output schema likely covers return values. However, it lacks parameter explanations, timeout behavior, and explicit guidance on when to use sibling tools, leaving gaps for an agent deciding how to invoke it.

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

  Parameters1/5

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

  Schema description coverage is 0% and the description provides no parameter details. It does not explain inputs, timeout_seconds, or project_id beyond the generic phrase 'Run a Hex project.' The output schema exists but does not compensate for the lack of parameter semantics.

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

  Purpose5/5

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

  The description uses a specific verb and resource ('Run a Hex project'), states the polling behavior, and positions itself as 'the primary tool for pushing notebook changes to the app view,' which distinguishes it from sibling tools like run_project and get_run_status.

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

  Usage Guidelines4/5

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

  It gives clear usage context: call after updating cells and the app will automatically reflect new results. It does not explicitly mention when to use alternatives like run_project or get_run_status, so it falls short of full when/when-not guidance.

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

• create_cellA
  3.9/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the behavioral disclosure burden. It discloses the append-to-end behavior for insert_after_cell_id and the conditional requirement for data_connection_id, but it lacks important behavioral context such as whether the cell is automatically executed, permissions needed, or error semantics. This is a moderate gap.

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

  Conciseness5/5

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

  The description is concise and well-structured: a one-sentence purpose statement followed by a bullet-style parameter list. Every line adds value, and there is no redundant or extraneous text.

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

  Completeness3/5

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

  The description covers most parameter semantics and placement behavior, but it omits guidance on sourcing project_id and does not clarify whether creating a cell triggers execution. Given the presence of run_project and run_and_wait siblings, this missing execution context is a notable gap, though the output schema reduces the need to explain return values.

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

  Parameters4/5

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

  Despite 0% schema description coverage, the description explains the meaning and allowed values for five of six parameters, including the cell_type enum values, the purpose of data_connection_id, and the optionality of label and insert_after_cell_id. However, it omits explicit documentation of project_id, a required parameter, and does not provide value formats for all IDs.

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

  Purpose5/5

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

  The description states 'Create a new cell in a Hex project' with a specific verb and resource, clearly distinguishing it from siblings like update_cell_source, delete_cell, and get_cell_source. This is a precise and unambiguous purpose statement.

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

  Usage Guidelines3/5

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

  The description provides some contextual guidance, such as 'data_connection_id is required for SQL cells' and insert placement semantics, but it does not explicitly state when to use this tool versus alternatives like update_cell_source or delete_cell. The usage context is implied rather than explicitly contrasted.

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

• get_projectA
  3.9/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It accurately indicates a read operation ('Get full details') and specifies return content (all cells, type, source, position). However, it does not explicitly state read-only behavior, error handling, or permissions, which are relevant for a tool with zero annotation coverage.

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

  Conciseness5/5

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

  Two sentences with zero waste. The first sentence states the purpose, the second provides usage context. Every word serves a function.

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

  Completeness4/5

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

  The tool is simple (1 param) and has an output schema, so return value details are already structured. The description covers what is returned, why to use it, and when to use it. It does not mention potential performance implications of fetching all cells, but this is minor given the output schema.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate. It does not explain the project_id parameter at all—only the tool name implies it. The description adds no format, example, or identifier guidance beyond the schema's 'string' type.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Get full details of a Hex project including all cells with their type, source, and position.' The verb 'Get' and resource 'Hex project' are specific, and it distinguishes from siblings like list_projects (which lists projects) and get_cell_source (which gets a single cell).

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

  Usage Guidelines4/5

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

  The description provides clear context: 'Use this before editing to understand the current notebook structure.' This implies the tool is a prerequisite for editing, but it does not explicitly mention alternatives or when not to use it, so it stops 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.

• inject_plotly_chartA
  3.9/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context such as 'Design system (dark theme, color palette, typography) is applied automatically' and 'auto_run: if True, immediately triggers run_and_wait to push to app view.' However, it does not clarify whether writing the chart overwrites existing cell content or how it handles errors, leaving key behavioral aspects undisclosed.

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

  Conciseness5/5

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

  The description is efficient and well-structured. It opens with a clear one-sentence purpose, adds a single sentence about automatic styling, and then presents a concise parameter list in a scannable format. No redundant phrases or filler text are present.

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

  Completeness3/5

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

  Given the tool's complexity (11 parameters, 0% schema coverage), the description covers the essential parameters and environment. However, it omits critical context about whether the chart code replaces or appends to the cell's existing source, and what happens when the cell is run (beyond the auto_run flag). The presence of an output schema lessens the need to describe return values, so the gaps around cell mutation behavior are the main deficiency.

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

  Parameters4/5

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

  The schema provides zero description coverage, so the description compensates by explaining the key functional parameters: chart_type (with allowed values), dataframe_var, x_col/y_col, color_col, extra_kwargs (with an example), and auto_run. It does not explain title or height, but those are relatively self-explanatory. The description adds substantial meaning beyond the raw schema for the parameters that matter most.

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

  Purpose5/5

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

  The description opens with 'Write a fully styled Plotly chart into a Hex Python cell,' which is a specific verb+resource combination. It clearly distinguishes from sibling inject tools like inject_pydeck_map and inject_html_component by explicitly naming Plotly as the chart library and Hex Python cell as the target environment.

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

  Usage Guidelines3/5

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

  The description implies usage through the list of supported chart types and the note that the design system is applied automatically. However, it does not explicitly state when to use this tool over alternatives like inject_pydeck_map or inject_html_component, nor does it mention any exclusions or prerequisites beyond needing an existing DataFrame variable.

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

• apply_workspace_paletteA
  4.1/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states that admin permissions are required and that the action affects all Chart cells in the workspace, providing meaningful context about side effects and prerequisites. It stops short of describing reversibility or the fate of existing custom styling, but for a simple palette apply operation, this is reasonable.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core purpose, and every sentence adds value. No filler or repetition.

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

  Completeness4/5

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

  Given the tool's simplicity (one param), the description covers the main action, the scope of effect, and the permission requirement. An output schema exists, so return values don't need explanation. The only notable gap is the lack of parameter semantics, but overall the description is adequate for an agent to understand when and how to use the tool.

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

  Parameters2/5

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

  The description does not explain the role of project_id, which is the only parameter and is required. The schema provides minimal info (just 'string'), and the description fails to clarify that project_id likely identifies the target workspace. With 0% schema description coverage, the description should have compensated but did not.

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

  Purpose5/5

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

  The description clearly states a specific action ('Apply the design system color palette') and the resource ('Hex workspace custom styling'), with additional detail about setting the active chart color palette for all Chart cells. This distinguishes it from sibling tools like get_design_system, which is a getter rather than a setter.

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

  Usage Guidelines4/5

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

  The description provides clear context: it is used to apply a palette and sets the active palette for all Chart cells. It does not explicitly name alternatives or exclusions, but the sibling tool list makes it obvious that get_design_system is for retrieval, so the usage context is fairly clear.

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

• diagnose_notebookA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full transparency burden. It uses non-mutating verbs ('reads', 'pulls', 'identifies', 'flags') and lists specific diagnostics, clearly indicating a read-only analytical tool. It does not explicitly state 'does not modify anything' or discuss return format, but it describes the scope of inspection in enough detail to set expectations. This goes beyond a simple one-liner, earning a 4.

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

  Conciseness5/5

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

  The description is concise and well-structured, starting with a clear opening line, followed by a bulleted list of diagnostic actions, and ending with usage guidance. Each line provides distinct information without redundancy, and the length is appropriate for the tool's complexity. It is easy to scan and front-loaded with the most important information.

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

  Completeness4/5

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

  The description covers the tool's purpose, what it reads, what issues it flags, and when to use it. Since an output schema exists, it doesn't need to explain return values in detail. The main gap is explicit parameter definitions, but the prose implies their roles. Overall, it provides sufficient context for an agent to select and invoke the tool correctly, meriting a 4.

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

  Parameters3/5

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

  The input schema has 0% description coverage, so the description must compensate. It says 'most recent (or specified) run' implying run_id identifies a run, and 'Hex notebook' implies project_id identifies the notebook. However, it does not explicitly name or define the parameters, leaving some ambiguity. The prose offers partial semantic clues, but not full compensation, so a 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool's purpose as a 'Full diagnostic sweep of a Hex notebook' and enumerates specific diagnostic actions like reading cell sources, pulling run error details, identifying failed cells, and flagging common issues. This distinguishes it from sibling tools such as get_cell_source (which reads a single cell) and run_project (which executes the notebook). The verb 'diagnose' plus the resource 'notebook' is specific and unambiguous.

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

  Usage Guidelines4/5

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

  The description provides explicit usage scenarios: 'Use this whenever a notebook fails to load, shows blank charts, or behaves incorrectly when filters are applied.' This gives clear context for when to use the tool, but it does not include exclusions or mention alternative tools like inspect_filter_behavior. Therefore, while it offers clear context, it lacks a full when/when-not/alternatives structure, warranting a 4.

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

• inject_html_componentA
  4.2/5.0
  Behavior3/5

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

  With no annotations, the description carries the transparency burden. It discloses that components render in the published app and require no Python, and it details the component types and their prop structures. It does not mention side effects like overwriting existing cell content, permissions needed, or the impact of the auto_run parameter, leaving some behavioral ambiguity.

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

  Conciseness5/5

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

  The description is two sentences of prose followed by a compact, scannable list of component types and their props. Every line adds essential information, and the list structure makes it easy to parse. There is minimal redundancy and no fluff.

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

  Completeness4/5

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

  The tool has multiple required parameters and nested props, but the description thoroughly covers the two most complex parameters (component_type and props). An output schema exists, so return-value explanation is not needed. Missing details like auto_run behavior and the prerequisite of an existing HTML cell are minor given the sibling tool context and available schema.

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

  Parameters4/5

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

  The schema has zero description coverage, so the description must compensate. It does so effectively for component_type by listing all five values and their expected props, and it enriches props with example structures like metrics=[{label, value, delta, delta_type}]. It does not explain project_id or auto_run, but those are fairly self-evident from their names and the tool's context.

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

  Purpose5/5

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

  The description clearly states the action ('Write') and the target resource ('a styled HTML component into a Hex HTML cell'). It then enumerates concrete component types, which distinguishes it from sibling injection tools like inject_plotly_chart and inject_pydeck_map. The phrasing is specific and non-tautological.

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

  Usage Guidelines4/5

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

  The description provides clear context: it is for HTML components that render in the published app without Python, and the component type list gives practical usage scenarios. However, it does not explicitly state when to choose this over the plotly or pydeck injection siblings, nor mention any exclusions. The context is clear but there is no explicit alternative comparison.

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

• update_cell_sourceA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It explains that source is wrapped in the correct API structure based on cell_type, and that changes are only pushed after calling run_and_wait. It also notes the auto-refresh behavior, adding useful context beyond a simple mutation statement. It does not mention permissions or side effects like overwriting existing source.

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

  Conciseness5/5

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

  The description is compact and front-loaded with the primary action. Each sentence delivers relevant information: the purpose, cell_type semantics, the necessary follow-up call, and the auto-refresh behavior. There is no filler or redundancy.

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

  Completeness4/5

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

  Given the tool's mutation nature and lack of annotations, the description covers the core workflow and clarifies the most ambiguous parameter. It omits error conditions and permission requirements, but since an output schema exists, return value details are not necessary. The guidance to call run_and_wait provides essential context for successful use.

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

  Parameters3/5

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

  The description adds explicit meaning to cell_type by listing accepted values (CODE | SQL | MARKDOWN) and its default, which is not present in the schema. However, it does not explain source, cell_id, or project_id beyond what their names imply. With schema description coverage at 0%, this partial compensation for one of four parameters is insufficient to fully cover the gap.

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

  Purpose5/5

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

  The description opens with 'Write new source code to a cell (Python, SQL, or Markdown)', which clearly identifies the action and target resource. It distinguishes itself from sibling tools like create_cell or get_cell_source by emphasizing the update aspect and specific cell types.

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

  Usage Guidelines4/5

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

  The description provides explicit follow-up guidance: 'After updating cells, call run_and_wait to push changes to the app view.' This clarifies the intended usage workflow, though it does not explicitly contrast with alternative tools or 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.

• get_design_systemA
  4.3/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It discloses that the tool returns the 'active' design system tokens and specifies the token categories (colors, fonts, chart defaults). However, it does not mention potential side effects (likely none), authentication needs, or whether the token set is complete or partial. It is adequate but could add more detail for full transparency.

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

  Conciseness5/5

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

  The description is two sentences: the first front-loads the primary purpose, and the second gives a practical usage hint. Every word is useful; no redundancy or fluff.

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

  Completeness5/5

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

  Given that there are no parameters and an output schema exists, the description covers the essentials: what the tool returns and when to use it. It is complete for a read-only getter in the context of sibling tools.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema is fully self-explanatory. The description adds no parameter information, but none is needed. The baseline of 4 applies because there are no parameters to clarify.

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

  Purpose5/5

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

  The description clearly states it returns active design system tokens, explicitly listing colors, fonts, and chart defaults. The verb 'return' plus the resource (design system tokens) makes the purpose unambiguous, and it is distinct from sibling tools like inject_plotly_chart or apply_workspace_palette.

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

  Usage Guidelines4/5

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

  The description gives explicit context: 'Use this to stay consistent when writing custom chart code.' This tells the agent when to use it, though it does not mention when not to use it or name alternative tools. Since the tool is a simple getter, the lack of exclusions is acceptable.

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

• run_projectA
  4.3/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the burden. It discloses that the tool is non-blocking (returns a run_id for polling) and implies it initiates a run. It does not mention potential side effects or required permissions, but given the nature of the tool, the key behavior is covered. A slight deduction for not detailing what happens to the run after triggering.

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

  Conciseness5/5

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

  The description is exactly two sentences, front-loaded with the primary action and a clear pointer to an alternative. No wasted words, ideal size and structure.

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

  Completeness4/5

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

  The description covers the immediate use case: it tells what it returns (run_id) and how to use an alternative for blocking. It doesn't mention error conditions or setup prerequisites, but given the tool's simplicity and the existence of an output schema, it is reasonably complete. A minor gap is not explaining the 'inputs' parameter, but it's not essential for the core purpose.

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

  Parameters2/5

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

  Schema description coverage is 0%, and the description does not explain the parameters beyond the action. It does not clarify what 'inputs' represents or how 'project_id' is used specifically. The schema provides types and requiredness, but the description adds minimal value for parameter understanding.

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

  Purpose5/5

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

  The description uses a specific verb 'Trigger' and resource 'Hex project run', clearly stating the action. It distinguishes itself from the sibling tool run_and_wait by noting it returns a run_id for polling, making its purpose distinct.

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

  Usage Guidelines5/5

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

  Explicitly tells the user when to use this tool vs an alternative: 'Use run_and_wait instead if you want to block until completion.' This provides clear when-to-use and 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.

• inspect_filter_behaviorA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It clearly states that the tool runs the project, waits for completion, and surfaces errors specific to the inputs. This is meaningful behavior transparency, though it does not mention potential side effects like data mutations or external impacts from running the project.

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

  Conciseness5/5

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

  The description is three sentences with no waste. It front-loads the purpose, then gives usage details with an example, and closes with behavior. Each sentence earns its place.

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

  Completeness4/5

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

  Given the tool's moderate complexity and the presence of an output schema, the description covers the core aspects: purpose, parameter example, execution behavior, and error surfacing. It is not exhaustive about edge cases like timeouts or side effects, but it is reasonably complete for an agent to use correctly.

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

  Parameters4/5

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

  Schema coverage is 0%, so the description must compensate. It explains filter_inputs with a clear example and describes the dictionary format for widget names and values. The project_id parameter is not described, but its purpose is inferable from the tool context and parameter name.

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

  Purpose5/5

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

  The description clearly states the tool triggers a run with specific filter input values to diagnose why a particular filter combination causes incorrect data or blank charts. This is a specific verb+resource+scope and distinguishes it from generic run tools by emphasizing diagnostic intent.

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

  Usage Guidelines4/5

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

  The description explicitly tells when to use it (when a filter combination causes incorrect data or blank charts) and gives a concrete example of how to pass filter_inputs. It does not mention when not to use it or name alternatives, so it stops 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.

• delete_cellA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses the critical destructive behavior: 'irreversible' and 'Use with caution.' This is significant context beyond the schema. It lacks details on permissions or impact on dependents, but the core risk is clearly communicated.

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

  Conciseness5/5

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

  The description is two sentences with no fluff. The action and caution are front-loaded: 'Delete a cell from a Hex project. Use with caution — this is irreversible.' Every sentence earns its place.

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

  Completeness5/5

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

  For a simple delete tool with an output schema, the description is complete. It gives purpose, safety guidance, and a workflow prerequisite. It doesn't over-explain return values (output schema exists) and covers the one parameter's context adequately.

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

  Parameters4/5

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

  The schema has 0% coverage, but the description adds meaning by telling the agent to 'confirm the cell ID' via get_project(), which indicates that cell_id should be a validated identifier. This is a useful semantic hint that the identifier must match an existing cell.

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

  Purpose5/5

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

  The description uses a specific verb and resource: 'Delete a cell from a Hex project.' It clearly distinguishes from sibling tools like create_cell and update_cell_source, which are the other CRUD operations on cells.

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

  Usage Guidelines4/5

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

  The description gives an explicit usage guideline: 'Always get_project() first to confirm the cell ID and contents before deleting.' This tells the agent when to use the tool and provides a necessary precondition, though it does not explicitly contrast with alternatives.

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

• get_cell_sourceA
  4.5/5.0
  Behavior4/5

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

  Without annotations, the description carries the transparency burden. It explicitly says 'Read,' disclosing the non-mutating nature, and 'full source code' indicating no truncation. It does not mention permissions or side effects, but for a simple read operation this is adequate.

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

  Conciseness5/5

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

  Two sentences: the first states the action, the second provides usage guidance. No redundant or extraneous information.

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

  Completeness5/5

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

  Given the simple tool complexity, an output schema, and clear usage guidance, the description is complete. It mentions cell types and read scope, adequately covering what the agent needs to know.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description must compensate. The parameter names (project_id, cell_id) are self-explanatory, and the description adds context about supported cell types. However, it does not elaborate on parameter formats or relationships beyond the schema.

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

  Purpose5/5

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

  The description clearly states the tool reads the full source code of a specific cell and specifies supported cell types (Python, SQL, or HTML). This distinguishes it from sibling tools like update_cell_source and get_project.

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

  Usage Guidelines5/5

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

  The description explicitly instructs 'Use this before updating to understand what's already there,' giving a clear when-to-use scenario and implying update_cell_source as the alternative.

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