Server Quality Checklist

Tool Scores

• scaffold_moduleA
  3.6/5.0
  Behavior5/5

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

  Discloses that calls return a 'capability_unavailable' message and that it is local-runtime only. Annotations already declare readOnlyHint=true, etc., but description adds specific error behavior and environment constraint.

  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, each serving a clear purpose: stating unavailability and redirecting. No wasted words; highly concise.

  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?

  Lacks details about the tool's actual function (scaffolding from existing data) and parameter roles. While the unavailability message is complete for this backend, a local-runtime agent would be left without guidance. Missing output schema info.

  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 information about any of the four parameters (name, state, table, source). The agent cannot infer parameter meanings or usage from the description.

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

  Purpose3/5

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

  The description does not explain what the tool does when available; it focuses on unavailability. The title hints at 'scaffold module from existing data' but the description omits this. The agent is told it's unavailable, so purpose is clear in that limited sense.

  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 states 'Not available on this backend' and directs to use 'design_workflow' instead. Provides clear when-not-to-use and an alternative, which is excellent guidance.

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

• get_module_schemaA
  3.9/5.0
  Behavior4/5

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

  Annotations already declare readOnly and idempotent hints. Description adds value by specifying what each tier returns, aiding behavior understanding without contradiction.

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

  Conciseness5/5

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

  Three sentences, front-loaded with purpose, followed by clear tier guidance. No unnecessary words, perfectly scoped.

  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 read-only, idempotent nature, complete param descriptions in schema, and absence of output schema, the description fully covers what an agent needs to use this tool correctly.

  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 100%, so baseline is 3. Description partially repeats schema info but adds usage context for tier, offering marginal additional value.

  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?

  Clearly states verb 'get' and resource 'canvas schema for a module'. However, does not explicitly differentiate from sibling tool 'get_module_canvas', which may cause confusion.

  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?

  Provides guidance on when to use each tier (basic vs extended) but does not address when to use this tool versus alternatives like get_module_canvas.

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

• get_entry_historyA
  4/5.0
  Behavior4/5

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

  Annotations already declare non-destructive read-only behavior. Description adds value by specifying output format (chronological list with field-level changes and AI traceability), going beyond annotations.

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

  Conciseness5/5

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

  Two concise sentences, front-loaded with verb and resource, no fluff. Every sentence adds value.

  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?

  Describes purpose and return content well. However, missing mention of pagination (page parameter) and required parameters (module, entryId). Schema covers them, but description could be more complete.

  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 covers all 4 parameters with descriptions (100% coverage). Description does not add further parameter details, but baseline 3 is appropriate since schema does the work.

  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?

  Clearly states it gets audit trail and comments for an entry, mentioning specific return content (chronological actions, field-level changes, AI traceability). Distinguishes from siblings like get_entry, which returns the current entry, not history.

  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?

  Implicitly suggests use when audit trail needed, but lacks explicit when-not or alternative tools. Among siblings, get_entry is for current state, but no direct comparison.

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

• list_entriesA
  4/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description doesn't need to repeat those. It adds valuable behavioral details: filtering operators, OR/AND logic, 'me' keyword for user fields, token control via 'fields', and that system fields are always returned. This goes beyond what annotations provide.

  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?

  Two paragraphs: first focuses on filtering core behavior, second on token control. Information is front-loaded (purpose clear immediately). Every sentence adds value, though a tiny bit redundant in the filter explanation. Overall efficient and well-structured.

  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?

  No output schema exists, but the description does not describe the return structure (e.g., pagination metadata, entry format). It covers filtering thoroughly but lacks details on response shape. With 10 parameters and nested filters, the missing output context is a notable gap.

  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 50%. The description adds significant semantic value for two key parameters: 'filters' (detailed operator explanation) and 'fields' (token control rationale). However, it does not cover undocumented parameters like state, sortBy, currentPage, sortDirection. The added explanation for the covered ones compensates somewhat, but not fully.

  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: 'Query entries with filters, sorting, pagination.' It uses a specific verb (query/list) and identifies the resource (entries). This distinguishes it from siblings like get_entry (single entry) and list_modules (modules).

  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 implicit usage context (e.g., token control tips) but does not explicitly state when to use this tool versus alternatives like get_entry for a single entry or other list tools. No 'when not to use' or direct comparisons to siblings.

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

• create_moduleA
  4.1/5.0
  Behavior4/5

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

  Annotations indicate readOnlyHint=false, destroyingHint=false. The description adds that it validates internally and returns structured errors without creating anything if validation fails, plus role requirements, going beyond the annotations.

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

  Conciseness5/5

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

  The description is concise (3 sentences) with front-loaded purpose, then requirements, validation behavior, and reference. No unnecessary words.

  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 a complex tool with 8 parameters and nested structures, the description covers essential aspects but does not mention the return value (e.g., created module object) or provide exhaustive parameter details.

  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 coverage is 88% (high), so baseline is 3. Description adds a reference to external docs for field types and clarifies that certain arrays are omitted for record list modules, but does not deeply explain each parameter.

  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 creates a new module and specifies two types (workflow and record list), distinguishing it from siblings like update_module or scaffold_module.

  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 explicitly lists required roles and notes that validate_design is optional, providing good context for when to use, but does not explicitly state when not to use or provide direct alternatives.

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

• download_fileA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying that a pre-signed S3 URL with 1hr TTL is returned, which is useful behavioral context beyond the annotations.

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

  Conciseness5/5

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

  The description is two sentences with no wasted words. The main purpose is front-loaded, and each sentence adds essential 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?

  For a simple read-only file download tool returning a URL, the description is complete. It covers operation, input hints, and output format. No output schema is needed, and the tool is well-documented for its complexity.

  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 coverage is 100%, so baseline is 3. The description adds context about how 'guid' and 'fileName' construct the URL path, but does not significantly enhance the parameter meanings beyond the schema descriptions.

  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: 'Download a file by module name' and explains that it returns a pre-signed S3 URL. It distinguishes from sibling tools like upload_file by focusing on download and URL generation.

  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 implicit usage context (construct URL from field.path) but does not explicitly state when to use this tool versus siblings like upload_file or confirm_upload. No direct alternatives or exclusions are mentioned.

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

• get_entryA
  4.2/5.0
  Behavior4/5

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

  Annotations already provide readOnly, idempotent, and non-destructive hints. The description adds value by specifying the exact return data: current field values, state, audit metadata, and available activities. No contradictions.

  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 efficient sentences: one for purpose, one for return. No redundant information. Every word contributes to clarity.

  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?

  For a single-entry read tool, the description covers purpose and return content. No output schema, but description compensates. Missing error handling or permission details, but adequate given annotations.

  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 coverage is 100% with clear descriptions for each parameter. The description adds no additional meaning beyond the schema, which is acceptable given high coverage, but no extra semantic value.

  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 (Read), resource (single entry), and method (by its ID). It also lists specific return data, distinguishing it from siblings like list_entries and get_entry_history.

  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 implies use for retrieving a single entry, and sibling names (list_entries, get_entry_history) provide context for alternatives. However, it does not explicitly state when not to use or provide direct compared to similar tools.

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

• get_module_canvasA
  4.2/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: 'The output is round-trippable — modify and send back via update_module' and instructs to load inistate://schema before modifying. No contradictions with annotations.

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

  Conciseness5/5

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

  The description is concise with two sentences covering purpose and workflow, plus a resource instruction. Every sentence adds value with no wasted words.

  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 no output schema, the description adequately conveys that the output is the full module definition and round-trippable. It covers how to use it in a workflow and prerequisites. Could mention return format but not essential for a getter.

  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 100% with clear descriptions for both parameters. The description does not add additional meaning beyond the schema, so baseline score of 3 applies.

  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 retrieves the full module definition with stable IDs, using the verb 'get' and specifying 'full module definition'. It distinguishes from siblings like list_modules (which lists) and get_module_schema (likely different scope) by emphasizing round-trippability and the modify workflow.

  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 advises using this tool when modifying a module to preserve IDs and provides a modify workflow. It gives clear context but does not explicitly state when not to use it, though the workflow implies a sequence.

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

• design_workflowA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing resource loading (inistate://schema and inistate://design-guide) and the pipeline nature, which are not conveyed by annotations.

  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?

  Three sentences with no redundancy: first states purpose, second gives usage trigger, third provides pipeline and prerequisites. Every sentence adds unique value and is front-loaded.

  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 no output schema, the description explains the output type ('scaffolded ModuleSchema template') and its role in a larger workflow. Resource loading and pipeline context provide sufficient completeness for agent invocation.

  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?

  Input schema descriptions cover both parameters fully (100% coverage), but the tool description enhances them by specifying the industry mapping behavior and providing detailed guidance on what to include in the 'description' parameter, plus resource loading instructions that affect parameter usage.

  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 explicitly states it generates a 'scaffolded ModuleSchema template' from natural language, uses a specific verb ('Generate'), and distinguishes from siblings by outlining the workflow pipeline (design_workflow → validate_design → create_module → get_module_schema).

  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?

  Clearly says 'Use when the user wants to create a new module or workflow' and provides a pipeline for subsequent steps. Lacks explicit 'when not to use' or direct alternatives, but the context is sufficient for decision-making.

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

• request_upload_urlA
  4.4/5.0
  Behavior5/5

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

  Discloses key behavioral traits beyond annotations: file size limit (500MB), upload URL expiration (~1 hour), Content-Type matching requirement with specific 403 error from S3, and the full flow including confirm_upload dependency. Adds significant context not present in annotations.

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

  Conciseness4/5

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

  The description is concise and packed with information in a single paragraph. The numbering of steps aids clarity. Slightly dense but no wasted words; could be improved by breaking into bullet points but not necessary.

  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 tool's complexity (5 params, flow with subsequent steps, no output schema), the description is remarkably complete. It covers the entire upload process, expiry, and dependencies. No gaps identified.

  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 coverage is 100% with descriptions for all 5 parameters. The description adds marginal value by framing the purpose of module and contentType in the flow, but does not substantially enhance understanding beyond the schema. Baseline 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?

  Clear verb+resource: 'request upload URL' explicitly states the tool's function. Distinguishes itself from sibling 'upload_file' by stating this is the default path and upload_file is a fallback, providing clear differentiation.

  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?

  Provides explicit when-to-use: 'DEFAULT upload path for every file' and when to use alternative: 'upload_file is only the fallback if this flow fails.' Also gives a step-by-step flow. Does not explicitly state when not to use, but context is clear.

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

• set_workspaceA
  4.4/5.0
  Behavior4/5

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

  Annotations declare idempotentHint=true and destructiveHint=false; description adds behavioral detail: response includes module list. No contradictions, but could mention session state changes more explicitly.

  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?

  Well-structured with main purpose upfront, followed by workflow sequences. Slightly verbose but each sentence adds value. Good front-loading.

  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 low complexity (1 param, no output schema), the description is complete: explains effect, response contents, and usage patterns. No gaps.

  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 coverage is 100% with a clear description of workspaceId. Description adds little beyond schema; baseline 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 'Set the active workspace for the current session,' using a specific verb and resource. It distinguishes itself from siblings like list_workspaces and switch_mode by implying context setting.

  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?

  Provides explicit usage guidance: use this to set workspace, then follow recommended workflows (Design, Execute, etc.). Also advises when to prefer passing workspaceId directly (stateless/remote mode).

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

• validate_designA
  4.4/5.0
  Behavior4/5

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

  Annotations already indicate read-only and idempotent behavior. The description adds that it runs the same checks as create_module/update_module and is a non-submitting validation, reinforcing safety. However, it could mention the return value (e.g., validation errors) 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?

  Two sentences: first states core purpose, second provides usage guidance. No wasted words, front-loaded, and easy to scan.

  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?

  For a simple validation tool with good annotations and schema, the description covers the essential purpose and usage context. It could mention the output (e.g., success/error response) but overall is sufficiently complete.

  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 coverage is 100%, so description adds limited value beyond schema. It does provide extra guidance on workspaceId (omit if set via env or set_workspace) and reiterates mode semantics, which is helpful but not extensive.

  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 validates a module schema without submitting, and distinguishes it from create_module and update_module by positioning it as a dry-run for iteration. The verb 'validate' and resource 'module schema' are specific and distinct from sibling tools.

  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 explains when to use this tool (iterating on a draft, before partial update_module) and when it is optional (create_module already runs these checks). It provides clear alternatives and context.

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

• confirm_uploadA
  4.5/5.0
  Behavior5/5

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

  The description goes beyond annotations by detailing the server-side verification in S3, the exact return fields (url, filename, mimeType, size), and error conditions (400 if file not in S3). This provides rich behavioral context.

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

  Conciseness5/5

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

  The description is concise, with two sentences that front-load the core action. Every sentence adds value and there is no redundancy.

  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?

  Despite lacking an output schema, the description fully explains the return values and error condition. For a simple confirmation step with no nested objects or enums, this is complete and sufficient.

  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 coverage is 100% with clear parameter descriptions. The description adds no new information about parameters beyond what the schema already provides, so baseline score of 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: confirming a presigned upload after a successful PUT. It explicitly distinguishes from sibling tools like request_upload_url and upload_file by specifying the exact step in the upload workflow.

  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 specifies when to use the tool (after the PUT to uploadUrl succeeded) and notes a critical precondition (ensuring the PUT completed first). It does not mention alternative tools or when not to use it, but the context is clear.

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

• get_formA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety profile. Description adds context about schema stability within a session and the nature of returned data (fields, values, options), going beyond annotations to inform agent behavior.

  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?

  Three sentences front-loaded with main purpose, followed by concise usage advice and error handling. Every sentence adds value without redundancy.

  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 read-only tool with no output schema, the description covers purpose, invocation pattern, behavior, and error guidance. It references sibling tools appropriately and provides enough context for an agent to use the tool correctly.

  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 100%, so baseline is 3. The description does not add significant new meaning beyond what the input schema already provides for each parameter, but it reinforces usage patterns related to entryId and activity.

  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 function: retrieving form fields, current values, and options for a module activity. It distinguishes from siblings like get_entry by specifying that per-entry current values come from those tools, providing a clear verb-resource-usage scope.

  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 advises calling before the first submit_activity per (module, activity) pair, notes schema stability and reuse, and explains how to handle unmatched values and uncertainty. This provides comprehensive 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.

• submit_activityA
  4.5/5.0
  Behavior5/5

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

  Discloses critical behaviors beyond annotations: the ai object is required, confidence gating suppresses transitions and flags entries, and server-side guard rules may block. No contradiction with annotations (destructiveHint, readOnlyHint). References external resources for guardrails and input shapes.

  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 front-loaded with purpose and workflow, followed by key rules and references. Every sentence adds value, but it is somewhat long and could be trimmed without losing essential information. However, for a complex tool, this level of detail is justified.

  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 12 parameters, nested objects, and no output schema, the description covers prerequisites (get_form), key input requirements (ai, confirmed), constraints (confidence threshold), and edge cases (guardrails). It references external documentation for full details, which is appropriate. Minor omission: no guidance on error handling or response format.

  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 83% (good), and the description adds significant value by explaining the ai object requirement, confidence threshold effect, and compound field shapes (User, Module, etc.). It provides context that the schema alone does not, such as the workflow for get_form and guardrails.

  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 'Perform an activity on a module entry' and lists standard activities (create, edit, delete, etc.) plus custom ones. It distinguishes itself from siblings like submit_activities (plural, likely bulk) and get_form, making the purpose unambiguous.

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

  Usage Guidelines4/5

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

  Provides clear when-to-use guidance: call get_form before first submission per (module, activity) and reuse its schema. Warns about server-side guard rules and references inistate://guardrails. However, it does not explicitly contrast with sibling submit_activities for bulk operations, which would strengthen the guidance.

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

• upload_fileA
  4.5/5.0
  Behavior4/5

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

  Annotations are minimal (readOnlyHint=false, destructiveHint=false). Description adds substantial behavioral details: base64 upload, return fields, max size, blocked extensions. No contradiction with annotations.

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

  Conciseness5/5

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

  Three sentences, front-loaded with fallback warning, no unnecessary text. Every sentence provides essential 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?

  Covers return values (no output schema needed), constraints, relationship with siblings (request_upload_url, confirm_upload), and parameter context. Fully adequate given tool complexity.

  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 coverage is 100% with clear descriptions for all 5 parameters. The description adds minimal additional meaning beyond the schema, only noting workspaceId omission context. Baseline 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 uploads a file via base64 as a fallback, its return values, and how the output is used. It distinguishes from siblings by specifying it's the fallback when the presigned flow fails.

  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 says 'FALLBACK ONLY — use request_upload_url + confirm_upload first; call this only after that presigned flow has actually failed.' Also provides constraints (max 50MB, blocked file types) and return usage instructions.

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

• switch_modeA
  4.6/5.0
  Behavior5/5

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

  Annotations already mark the tool as idempotent and non-destructive. The description adds crucial behavioral context: it reveals that the tool/resource list refreshes via 'list_changed' after the call and clarifies what tools/resources are available in each mode. No contradictions with annotations.

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

  Conciseness4/5

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

  The description is a single paragraph with no wasted sentences, but it is slightly verbose. It front-loads the core action and then lists modes and their contents efficiently. Minor room for tightening, but overall strong.

  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 single-parameter schema, no output schema, and informative annotations, the description fully covers the tool's behavior: what it does, the effect of each mode, and a side effect (list refresh). It leaves no obvious gaps.

  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 100% and the description expands on each enum value beyond the schema's single-word labels. For example, it explains that 'configure' includes entry CRUD and design tools, while 'frontend' adds the inistate://frontend-guide resource. This adds meaningful clarity.

  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 phrase 'Switch tool surface' and lists the three modes (configure, runtime, frontend) with their distinct feature sets. This clearly differentiates it from sibling tools, which are all separate resource or action tools.

  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 explains what each mode enables and explicitly advises using 'frontend' when the user wants a custom UI. It does not explicitly state when not to use the tool, but the mode descriptions provide enough context to select appropriately.

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

• list_modulesA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnly, idempotent, non-destructive. Description adds context: modules are 'discoverable', and behavior depends on workspace state (stateless vs stateful via set_workspace). No contradiction, and supplements annotations with usage-specific behavior.

  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: first states purpose, second provides usage guidance. Front-loaded and efficient with no 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 1 optional parameter, high schema coverage, no output schema, and clear annotations, the description fully covers what an agent needs: purpose, when to use, and parameter semantics. No gaps.

  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 covers workspaceId with description. Description adds conditional semantics: 'Omit if set via env or set_workspace; required in stateless/remote mode', which clarifies when the parameter is needed beyond schema constraints.

  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 clearly states 'List all discoverable modules in the current workspace', specifying verb (list) and resource (modules). It distinguishes from sibling set_workspace by noting that set_workspace already returns this list, avoiding redundancy.

  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 states when to use: 'call this only to refresh it or when operating stateless without set_workspace'. Provides clear context and alternative, guiding appropriate invocation.

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

• list_workspacesA
  4.7/5.0
  Behavior5/5

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

  Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds critical behavioral details: auto-selection of a single matching workspace and return of its module list. This informs the agent of side effects without repetition of annotations.

  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 no wasted words. Purpose is front-loaded, and each sentence adds distinct value: purpose, typical usage, and conditional behavior.

  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 tool with one optional parameter and rich annotations, the description covers all necessary context: session-first usage, auto-selection logic, and relationship to siblings. No output schema needed as return value is implied.

  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 coverage is 100% for the sole optional parameter 'search', and the description does not add additional meaning about it. Baseline 3 is appropriate as the schema already documents the parameter.

  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 lists workspaces accessible to the current user, distinguishes it from sibling tools by explaining the automatic selection behavior when only one workspace matches, eliminating the need for set_workspace or list_modules.

  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 states it is typically the first call of a session and provides clear guidance: if exactly one workspace matches, no further action needed; otherwise call set_workspace next. This effectively tells when to use this tool versus alternatives.

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

• submit_activitiesA
  4.8/5.0
  Behavior5/5

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

  The description reveals important behaviors: per-item ai wholly replaces default, fail-soft execution (one failure does not abort rest), per-item outcomes in results, and guardrails at batch level. Annotations already mark destructiveHint=true, which aligns with the write nature, but the description adds significant context beyond annotations.

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

  Conciseness4/5

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

  The description is compact but dense with information. It uses three sentences with clear structure: first defines the tool, second explains fail-soft and results, third covers guardrails and limits. Slightly verbose but efficient given the complexity.

  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?

  Covers purpose, usage, behavioral details (fail-soft, guardrails), and parameter semantics. No output schema, but mentions return of results with per-item outcomes. Could include more on error format or specific field behaviors, but adequate for the tool's complexity.

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

  Parameters5/5

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

  The schema has parameter descriptions for many fields (67% coverage). The description adds meaning beyond schema: e.g., 'A per-item ai wholly replaces the top-level default (no partial merge)' and 'use clientRef to correlate' results. This enhances understanding of parameter behavior.

  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 is the 'Bulk variant of submit_activity' and describes its function: 'one module + one activity applied to many entries, each item with its own input.' It distinguishes from the sibling submit_activity by noting it is for bulk operations and uses 'Use instead of N sequential submit_activity calls.'

  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 when to use: instead of N sequential calls. Also gives limitations: 'Max 100 items; chunk beyond that.' Provides clear guidance on guardrails: 'actor="human" rejects the whole batch; actor="hybrid", activity="changeStatus", or any state override requires confirmed: true.'

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

• update_moduleA
  4.9/5.0
  Behavior5/5

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

  Description discloses behavioral traits beyond annotations: sections are replaced entirely, omitted sections are unchanged, id matching enables renaming, and prerequisite calls are mandatory. No contradiction with annotations (destructiveHint true), and adds context about validation behavior.

  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?

  Efficient four-sentence structure: first sentence states purpose, second explains replacement behavior, third gives prerequisite, fourth provides validation guidance. No redundant information, 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?

  Given the tool's complexity (9 parameters, nested objects), the description is thorough: covers purpose, modus operandi, prerequisites, validation, and id handling. No output schema exists, but return value is implied. Contextual completeness is high for the domain.

  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 high (89%), but description adds meaningful context: importance of id from get_module_canvas, replacement semantics for sections, id behavior for renaming, workspaceId omission context. Baseline 3, but description adds significant value beyond schema descriptions.

  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?

  Clearly states 'Update an existing module' with specific verb and resource. Distinguishes from siblings like create_module by noting that it modifies an existing module and requires get_module_canvas first. The replacement semantics for sections and prerequisites further differentiate it.

  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?

  Provides explicit guidance: 'Always call get_module_canvas first' and for partial payloads 'validate the merged canvas with validate_design first.' Also explains when to include items (keep) and omit (leave unchanged), and distinguishes validation rules for full vs. partial payloads.

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