Server Quality Checklist

Tool Scores

• catalog_load_flow_configA
  4.1/5.0
  Behavior4/5

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

  Beyond the annotations (idempotent, not read-only, not destructive), the description discloses that the tool caches the configuration server-side and returns a cache_key because the config is 'far too large to read directly.' This adds useful behavioral context about side effects and storage that annotations do not capture.

  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 primary action and resource, and each clause earns its place. It efficiently explains what the tool does, what it returns, and why the caching design exists.

  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?

  The description covers the purpose, the caching behavior, the return value (summary + cache_key), and the rationale. An output schema exists to document the exact return shape, so the description is complete for an agent to select and invoke the tool correctly.

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

  Parameters3/5

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

  The input schema already provides full descriptions for both parameters (flow_id and session_id) at 100% coverage. The description does not add parameter-specific meaning beyond the schema, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description names a specific action ('Fetch and cache') and a distinct resource ('mock-runner configuration for a flow'), and elaborates on what the configuration contains (per-step generation, validation, requirement, save-data logic). This clearly distinguishes it from sibling tools like flow_start or flow_get_status.

  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 the tool is used before executing a flow (it 'drives' the flow and the config is cached 'for later execution'), but it does not explicitly state when to use this tool vs alternatives or any exclusions. No sibling tool is mentioned, leaving usage guidance largely implied.

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

• catalog_describe_flowA
  4.3/5.0
  Behavior4/5

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

  Annotations already cover read-only and idempotent behavior. The description adds valuable context beyond annotations by explaining the meaning of actor tags ('mock' vs 'np'), listing inputs per step, and mentioning parallel/unsolicited steps. 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?

  The description is two sentences, immediately states the core purpose, and then adds only meaningful specifics. No redundant phrases or unnecessary detail.

  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 describe tool with an output schema, the description sufficiently covers the content of the response: sequence, actor semantics, inputs, parallel/unsolicited steps. The highlights and annotations fill any remaining context 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 description coverage is 100% for both parameters; each has a clear description. The tool description doesn't need to add parameter details, and doesn't, so the baseline 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 the tool's function: 'The full ordered sequence of one flow' with specific detail about actor tags, inputs, and parallel/unsolicited steps. This distinguishes it from siblings like flow_get_status (status only) and catalog_list_flows (list of flows).

  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 when to use this tool: when a complete, step-by-step breakdown of a flow is needed. It doesn't explicitly name alternatives or provide exclusion criteria, but the clear contextual detail makes the use case evident. Slight improvement would be explicitly pointing to alternatives for status-only checks.

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

• catalog_list_buildsA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety and side-effect behavior are covered. The description adds valuable behavioral context by warning that 'use-case names are case- and space-sensitive and must match exactly,' which is important for downstream session creation. This goes beyond the annotations, though it doesn't describe output volume or pagination.

  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: the first states the purpose, the second gives actionable usage guidance. Every word earns its place, and the key information is front-loaded.

  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?

  This is a simple listing tool with one optional parameter, strong annotations, and an output schema. The description covers what it does, when to use it, and the critical exact-match caveat. All necessary context for invocation is present, making it complete for the agent.

  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%, and the schema already fully describes the one parameter 'domain' with a clear explanation and example. The description adds no parameter-specific semantics beyond what the schema provides, so baseline 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific verb and resource: 'List every domain, version and use-case published by the ONDC config-service.' This unambiguously defines what the tool does and implicitly distinguishes it from sibling catalog tools like catalog_list_flows by focusing on 'builds' (domain/version/use-case) rather than flows.

  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 explicit when-to-use guidance: 'Call this before session_create when the exact domain code, version or use-case name is uncertain.' It also explains the case/space sensitivity. However, it does not explicitly mention when not to use it or name alternative tools, 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.

• record_get_payloadA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable context beyond annotations: payloads are held server-side, can be very large, and the result includes a truncation indicator. This helps the agent understand performance and response characteristics, though it doesn't cover exhaustive edge cases.

  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 practical guidance. No wasted words; 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 presence of an output schema, rich parameter descriptions, and annotations, the description provides sufficient operational context: handle source, large-payload warning, jsonpath recommendation, and truncation notice. It is complete for an agent to select and invoke the tool correctly.

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

  Parameters3/5

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

  The input schema covers all parameters with descriptions (100% coverage). The description repeats the jsonpath example but does not add new meaning beyond the schema. Per the baseline rule, with high schema coverage a 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 opens with a specific verb and resource: 'Fetch a payload this session sent or received, by the handle reported in flow_get_status or flow_await.' It clearly distinguishes the tool from sibling record_* tools by focusing on payloads and specifying the handle source.

  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 tool to retrieve payloads using handles from flow_get_status or flow_await. It also gives practical advice to prefer jsonpath slicing for large payloads. However, it does not explicitly name alternative tools or state when not to use this tool.

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

• session_getA
  4.3/5.0
  Behavior4/5

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

  Annotations already establish read-only and idempotent behavior. The description adds the error case (unknown/expired session) and specifies the contents of the response, going beyond the structured 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, front-loaded sentences convey purpose, return value, and error behavior 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?

  With an output schema present and low complexity (single parameter, read-only), the description covers the essential purpose, return contents, and error semantics. No significant 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?

  The input schema already provides a description for session_id ('Session returned by session_create'). With 100% schema coverage, the description adds no additional semantics for the parameter, meriting a baseline 3.

  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 fetches a session by ID and enumerates the returned fields (participant, role, build, expiry). This distinguishes it from session_create and other siblings.

  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 for when to use the tool (retrieving a session by its ID) and what it returns, but does not explicitly mention alternatives or exclusions. Since no other sibling tool directly competes, it earns a 4.

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

• flow_startA
  4.4/5.0
  Behavior5/5

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

  Beyond the annotations (readOnly=false, openWorldHint=true, idempotent=false), the description surfaces critical gotchas: the returned callback URL must be reachable by the participant or callbacks never arrive; invalid flows are rejected before anything is sent; and transaction_id is null because it belongs to the first action sender. This is rich, non-obvious behavioral context that will help an agent avoid mistakes.

  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 the core purpose and then spends a few dense sentences on essential caveats. Every sentence carries meaningful information, though the callback URL explanation is slightly lengthy; overall it is well-structured for the tool's complexity.

  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?

  The description covers the return value (callback URL, null transaction_id), failure preconditions, and the handoff to flow_proceed/flow_await. Since an output schema exists, it doesn't need to enumerate return fields, and the provided context is sufficient for correct invocation.

  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% and every parameter already has a detailed description, so the description doesn't need to compensate. It does reinforce transaction_id's null behavior, but adds little meaning beyond what the schema already provides.

  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+resource: 'Open a run of one flow and report what its first step needs.' It clearly distinguishes itself from siblings by naming flow_proceed and flow_await as the follow-up tools for driving the run, making the initiation role 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 gives clear context for when to use the tool: to start a new flow run, and it points to flow_proceed and flow_await as the next steps. It also states preconditions ('Fails immediately if the flow has no mock config or any step with no owner') that help an agent decide if the tool is applicable. It does not explicitly say 'use X instead when...' but the guidance is sufficient.

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

• catalog_list_flowsA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds useful context beyond those: it details what the list contains (server vs. participant step expectations) and scopes it to the session's build. That is helpful behavioral context without contradicting the annotations.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the action and resource, and every clause adds value. The pointer to the sibling tool replaces additional explanation, so it is both concise and structured well.

  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?

  The tool is simple (1 parameter, output schema exists). The description states what the list contains (flows with step counts) and directs to a sibling for the full sequence. Given the output schema covers return structure, nothing essential is missing.

  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%, and the only parameter session_id is fully described in the schema. The tool description doesn't add extra meaning about the parameter beyond mentioning 'session's build,' which is already implied. Baseline 3 is appropriate because the schema does the heavy lifting.

  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 ('List'), names the resource ('flows published for the session's build'), and specifies the exact data returned (number of steps for this server vs. expected from the participant). It clearly distinguishes from the sibling catalog_describe_flow, so purpose is unambiguous.

  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?

  It explicitly points to catalog_describe_flow as the alternative for the full sequence, implying this tool is for the summarized list with step counts. This gives 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.

• feedback_submit_reportA
  4.5/5.0
  Behavior4/5

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

  Beyond annotations, the description reveals that 'values are stripped either way' and that the tooling_gap field 'changes the tools you are given next time'. These behavioral details are not exposed by the annotations (which only cover read-only, open-world, idempotency, and destructiveness) and add meaningful context for the agent.

  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 composed of five concise, purposeful sentences, each adding distinct value: what it does, when to call, why failures are useful, the key field, and the JSONPath rule. No fluff or repetition; the structure is efficient and front-loaded with the core purpose.

  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 submit-report tool with a rich schema, output schema, and annotations, the description covers the essential context: the trigger (ISSUE_OPEN event), timing, desired content, and a crucial formatting rule. It does not need to repeat return-value details since the output schema exists. The guidance is complete 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.

  Parameters4/5

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

  The description adds significant meaning for tooling_gap calling it 'the most valuable field' and explaining its effect. It also instructs to reference JSONPath instead of pasting values, which applies to all parameters. Schema descriptions cover most fields, but this extra guidance goes 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's purpose: 'Record your account of an incident this session opened'. It specifies the resource (an incident report) and the action (record/submit). It also distinguishes from sibling feedback_list_reports by focusing on submission rather than listing.

  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 when-to-use guidance: 'Call it AFTER you have tried to resolve the problem' and explains that it should be called whether or not the attempt succeeded. It does not explicitly name alternatives or exclusion cases, but the context is clear enough for an agent to decide when to invoke it.

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

• flow_get_statusA
  4.5/5.0
  Behavior4/5

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

  Annotations already mark the tool as read-only and idempotent. The description adds meaningful behavior: "State is derived from the recorded exchanges on every call, so this is always current," and reveals that the response includes a `next` action recommendation. This goes beyond the safe-read hint without contradicting it.

  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 densely packed sentences, front-loaded with the core purpose. No filler words; every sentence adds a unique piece of information (what it reports, why it's current, how to address it, when to use it).

  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 rich annotations (read-only, idempotent) and presence of an output schema, the description covers the what, when, how-to-call, and expected outcomes (statuses, off-sequence exchanges, next action). There are no significant gaps for an agent to invoke this 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 100%, so the baseline is 3. The description adds extra guidance on parameter selection: "Name the run by flow_id (or transaction_id once it has one)" and clarifies that session_id is the required context. This supplements the schema's own field 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 opens with a vivid, specific explanation: "Where a run has got to: every step with its status and who owes it, any exchanges that arrived off-sequence, and what the loop needs next." It clearly names the resource (a flow run) and distinctively positions it against sibling tools like flow_proceed and flow_await.

  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 a clear usage cue: "Read it whenever you lose track; `next` says exactly which tool to call." It also advises which identifier to use (flow_id vs transaction_id). It stops short of explicitly listing exclusions or alternatives, but the context is strongly differentiated.

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

• form_submitA
  4.5/5.0
  Behavior4/5

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

  The description discloses that the tool 'posts them to the participant' and 'reads back the submission id', revealing a network side effect not captured by annotations. It also explains that the id is saved for the next step, adding useful stateful context. It does not cover error conditions or idempotency nuances, but annotations already handle the basic safety profile, so this is solid.

  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 the core purpose, and every sentence adds meaningful detail. No redundancy or filler. Ideal structure for an AI agent to quickly parse.

  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?

  The description covers the full workflow: what triggers the tool, the two usage modes, what the participant receives, and how the output is consumed by the next step. The output schema exists to explain return values, and annotations cover side-effect safety. No critical information is missing for an agent to select and invoke this tool confidently.

  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% with good field descriptions, so baseline is 3. The description adds value by explaining the conditional use of `fields` vs `submission_id` based on session mode, and links `fields` names to form_fetch. This goes beyond simply restating the schema, justifying a 4.

  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: 'Complete the form step and advance the flow.' It distinguishes this from sibling tools like flow_proceed by focusing specifically on form submission, and it explains the two modes (llm_auto and manual), 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?

  The description gives explicit when-to-use guidance for both session types ('In llm_auto sessions pass fields... In manual sessions pass submission_id...'). It references form_fetch for field names, providing a workflow hint. However, it does not explicitly state when not to use this tool or mention alternatives like flow_proceed, so it falls just short of a 5.

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

• receiver_startA
  4.5/5.0
  Behavior5/5

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

  With annotations already indicating idempotentHint and non-read-only, the description adds substantial context: it explains that under HTTP the receiver is already mounted and only reports the address, while on stdio it binds a listener. It also warns about reachability from the participant and recommends setting RECEIVER_PUBLIC_URL for remote cases, which goes beyond any annotation.

  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 slightly long but every sentence adds value: setup purpose, ordering, transport-specific behavior, idempotency, and remote configuration. It is well-structured front-loaded with the core purpose and then expands into necessary details 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?

  Given the simple schema (one optional param) and presence of an output schema, the description fully covers necessary context: when to call, transport differences, idempotency, and remote reachability. It also mentions the output ('report the URL') even though an output schema exists, so the agent is well-equipped.

  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 schema covers the sole parameter session_id with 100% coverage, including its behavior ('Include a session to get its exact callback URL back. Omit for just the base URL.'). The description itself does not add further parameter-specific meaning, so the baseline of 3 applies without needing compensation.

  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 with a specific verb and resource: 'Make sure this mock can receive the participant's callbacks, and report the URL it must use.' It distinguishes from siblings like receiver_stop and session_create by emphasizing its role as an initialization step ('Call it once before session_create').

  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 timing: 'Call it once before session_create.' It also gives context about transport differences and remote participant configuration. However, it does not explicitly state when not to use the tool or compare it directly with alternatives like receiver_stop, so it lacks full when/when-not/alternatives coverage.

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

• receiver_stopA
  4.5/5.0
  Behavior4/5

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

  Annotations already indicate destructiveness and idempotency, and the description adds valuable behavioral context: the tool is a no-op under HTTP rather than failing, and it clarifies the relationship with the server's port. This goes beyond the structured annotations without contradicting them.

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

  Conciseness5/5

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

  The description is a single focused sentence, front-loaded with the primary action ('Close the standalone inbound listener') followed by necessary context. Every clause adds value, with no fluff or repetition.

  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 zero-parameter tool with an output schema and strong annotations, the description is complete. It clarifies the key edge case (HTTP transport) and the tool's role relative to the server lifecycle, leaving no significant 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?

  The input schema has zero parameters, so schema coverage is vacuously 100%. The description adds operational meaning beyond the schema by explaining the transport-dependent behavior, which is more relevant than parameter 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 clearly states the action: 'Close the standalone inbound listener.' It uses a specific verb and resource, and distinguishes from siblings like receiver_start by noting transport-specific behavior. The addition of the HTTP context clarifies scope.

  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 clear context for when the tool is meaningful: 'Only meaningful on the stdio transport; under HTTP the receiver shares this server's port and stops with it.' It implies when not to use it, though it does not explicitly name alternative tools or provide exclusionary guidance beyond the transport condition.

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

• feedback_list_reportsA
  4.7/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds valuable behavioral context: the 'derived state', whether the item 'still needs your account', and the fact that include_body renders the fully-redacted report exactly as it would be uploaded. This is honest and 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.

  Conciseness5/5

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

  Two sentences, no filler. The first sentence states the core function; the second explains a key parameter and its purpose. Front-loaded and efficient.

  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?

  With an output schema present and three straightforward parameters, the description covers the essential behavior (list reports, include_body variant). It is complete enough for the tool's complexity.

  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 only 33% (only include_body has a description), so the description compensates by elaborating on include_body: passing it shows the fully-redacted report, framed as 'the honest answer' for user transparency. limit and session_id are not discussed, but they are self-explanatory and typical.

  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 every incident report opened in this session, including derived state and whether action is still needed. This goes beyond the title by specifying the exact scope (session) and output content, and it is clearly differentiable from siblings like feedback_submit_report.

  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 usage context: when you need to see all incidents for the session, and specifically for answering a user's privacy question ('what is being sent about them?'). It does not explicitly name alternatives or exclusions, but the context is clear enough for selection.

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

• flow_restartA
  4.7/5.0
  Behavior5/5

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

  Beyond annotations, the description discloses critical behavioral traits: "Nothing recorded is destroyed" (non-destructive despite a restart), the abandoned attempt remains readable, and transaction_id comes back null for the new attempt. It also explains the compliance rationale, which is valuable context not present in 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 a well-structured paragraph that front-loads the core purpose, then explains rationale, key behaviors, and alternatives. Every sentence adds value with no fluff or redundancy, making it efficient and appropriately sized for the tool's complexity.

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

  Completeness5/5

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

  The description covers all key aspects: when to use, what happens (including output semantics like null transaction_id), what does not happen (nothing destroyed), and why it's preferred over alternatives. It is complete for a tool with this complexity, especially given the presence of output schema and 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?

  The input schema already describes all three parameters with 100% coverage, so the baseline is 3. The description does not add significant parameter-specific semantics beyond what the schema provides, although it does mention the return behavior of transaction_id. Since the schema covers everything, 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 function with a specific verb and resource: "Abandon this run's current attempt and open a fresh one of the same flow, in the same session." It distinguishes itself from flow_start (which resumes) and from creating a second session, making its 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 Guidelines5/5

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

  The description gives explicit when-to-use guidance: "Use it when a run has gone wrong and you want another go." It also explains why flow_start is not appropriate (it would resume) and why a second session is discouraged, providing clear alternatives and exclusions.

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

• payload_validateA
  4.7/5.0
  Behavior5/5

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

  Beyond the annotations (readOnly, idempotent, openWorld), the description adds that it runs L0 and L1 validation, returns rule codes with JSONPath on failure, and that a valid verdict only covers layers in 'checked'. This provides meaningful behavioral context about validation scope and error output, which the annotations do not.

  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 a few sentences, each with a distinct purpose: what it does, what validation layers run, how to use it, its non-requirement in the flow, and the scope of the verdict. It is front-loaded with the core purpose and contains no filler or 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?

  Given the tool's complexity, existing output schema, and sibling tools, the description is complete. It covers the validation scope, error reporting format, usage intent, and relationship to flow_proceed, enabling an agent to select and invoke it correctly without needing additional context.

  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 the baseline is 3. The description does not add new parameter-specific information beyond what the schema already states (e.g., action defaults to the payload's context.action). It does not compensate for any gaps because none exist; the schema carries the semantic load.

  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 'Check a protocol payload against the ONDC spec for this session's build, without sending it anywhere,' which uses a specific verb and resource, and immediately distinguishes it from sending tools. It clearly identifies the tool's validation role and its non-side-effect nature.

  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?

  It explicitly states 'Use it to inspect a body before committing to it, or to understand a refusal' and notes that 'flow_proceed already gates what it sends, so this is not a required step in the loop.' This gives clear when-to-use context and names an alternative, making it easy for an agent to decide.

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

• record_get_dataA
  4.7/5.0
  Behavior5/5

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

  Annotations already mark the tool as read-only and idempotent, so the description adds high-value behavior: large values are listed under 'omitted' rather than returned, and users can request them by name. It also clarifies that values are as saved by the mock config, which is non-obvious and useful.

  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 focused sentences: what the data is, when to read it, and how omitted values behave. Every sentence adds unique value with no filler or repetition.

  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 presence of an output schema and comprehensive annotations, the description provides the essential behavioral context: it explains the data source, the likely use case, and a notable limitation (omitted large values). This is sufficient for an agent to select and invoke the tool correctly.

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

  Parameters4/5

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

  The input schema covers all parameters with descriptions, so the baseline is 3. The description adds meaningful semantics by explaining that large values are omitted and can be retrieved by using the 'keys' parameter ('ask for one by name'), and by giving examples of value types. This goes beyond the schema but does not fully carry parameter 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 clearly identifies the tool as reading a transaction's accumulated business data, with concrete examples (provider IDs, order IDs, form submission IDs). It also distinguishes this from related tools like record_get_payload by noting this data is what the next step's payload is generated from.

  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 states when to use this tool: 'read it when a step reports missing requirements.' It also explains the relationship to payload generation, providing useful context. It does not explicitly name alternatives or state when not to use it, but the guidance is clear enough.

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

• record_get_eventsA
  4.7/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial context beyond these: the non-consuming behavior, the piggyback delivery model, and the fact that reading cannot consume what is still pending. This goes well beyond the structured fields, enhancing 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?

  Despite its length, every sentence earns its place. The description front-loads the core purpose, then justifies when to use it and clarifies a subtle behavioral detail (cursor movement). It is dense yet efficient, with no filler words.

  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 existence of an output schema, return values need not be described. The description thoroughly covers the tool's context—normal usage, exceptional cases, and the critical cursor behavior—making it complete for a 3-parameter tool with no nested objects.

  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 all three parameters (limit, since_seq, session_id) already documented. The description does not add meaning beyond what the schema provides, so the baseline score of 3 is appropriate—schema does the heavy lifting.

  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 verb and resource: 'Read this session's event journal without consuming it.' It differentiates from siblings by emphasizing the non-consuming, re-read nature, which distinguishes it from other record_get_* tools and the piggyback delivery mechanism.

  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?

  Explicit guidance is provided: 'You do not normally need this' states the default, while 'Reach for it when a result said `more` was outstanding, when you want to re-read something already delivered, or to recover a delta lost to an error' gives clear triggers. It also explains that reading never moves the cursor, which is crucial for choosing this tool.

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

• session_createA
  4.7/5.0
  Behavior5/5

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

  The description reveals non-obvious behaviors: the server automatically takes the opposite role, an unknown use-case is rejected (not silently empty), and the callback_url must be given to the participant. These are valuable insights beyond the annotations (readOnlyHint=false, openWorldHint=true) and significantly improve the agent's understanding of side effects and failure modes.

  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?

  Four sentences, each serving a distinct purpose: action, role selection, published-combo requirement, and callback_url handoff. There is no fluff or repetition; the most important info is front-loaded in the first sentence.

  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 params, 5 required) and the existence of an output schema, the description covers the operation's purpose, a critical prerequisite (validating builds), an error condition, and an operational follow-up (giving callback_url to the participant). This is complete enough for an agent to invoke the tool correctly without consulting siblings.

  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% so parameters are already documented, but the description adds relational meaning: it explains that np_type determines the mock's opposite role, and that domain/version/usecase must form a published combination. This goes beyond the schema's individual field descriptions, enriching the agent's ability to choose valid parameter values.

  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 and resource: 'Open a session against a network participant under test and list every flow available for its build.' This clearly states the action (create session) and the immediate outcome (list flows), and it distinguishes itself from sibling tools like flow_start or catalog_list_builds by focusing on session creation.

  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 provides clear contextual guidance, including the prerequisite step 'call catalog_list_builds first if unsure' and a practical note about handing the callback_url to the participant. It does not explicitly say 'use this before flow_start' or contrast with alternatives like flow_get_status, but the context is strong enough to infer when it applies.

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

• flow_proceedA
  4.9/5.0
  Behavior5/5

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

  The description discloses key side effects beyond annotations: it POSTs to the participant, records payloads and saved step data, does not send with dry_run, patches payloads via payload_overrides without bypassing validation, and mints transaction_id on first action. This is substantial behavioral context that annotations alone do not provide.

  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 dense yet each clause adds essential operational detail: return states, dry-run behavior, side-channel steps, payload overrides, and transaction_id creation. It is front-loaded with 'The loop driver' and remains efficient despite covering a high-complexity tool.

  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?

  With an output schema present, the description covers behavioral states (INPUT_REQUIRED, WAITING), dry_run, trigger_extra, payload_overrides, and transaction_id lifecycle. It is complete for a tool of this complexity, addressing edge cases like blocked non-compliant payloads and providing the needed resolution path.

  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%, providing baseline 3. The description adds meaningful context for `inputs` (flat shape, becoming sessionData.user_inputs) and `payload_overrides` (escape hatch for wrong flow config, not validation bypass, applies to this call only), raising the value beyond the schema. It does not elaborate on every parameter, but the schema already does.

  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 'The loop driver' and explicitly states it 'takes the next step this mock owns, checks its preconditions, generates its payload... and POSTs it to the participant.' It clearly distinguishes itself from siblings by referencing flow_await for participant-owned moves and flow_start/restart via transaction_id minting context.

  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 actionable guidance: 'call again with `inputs`' for INPUT_REQUIRED steps, 'call flow_await' when WAITING, use 'dry_run: true' to inspect without sending, and use 'trigger_extra' for side-channel steps. It also explains when 'payload_overrides' is needed, giving explicit alternatives and conditions.

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

• form_fetchA
  4.9/5.0
  Behavior5/5

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

  Even though annotations already mark readOnlyHint, openWorldHint, and idempotentHint, the description adds valuable behavioral context: it 'screens for active content', returns fields 'ready to fill', explains the mock-host behavior ('the answer says so'), and clarifies manual-mode returns a link instead. This goes well beyond the annotations without contradicting them.

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

  Conciseness5/5

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

  The description is three concise sentences, front-loaded with the core action ('Read the form a flow is waiting on') and then expanding into conditional scenarios. Every sentence earns its place, with no redundant filler or repetition of schema/annotation content.

  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?

  The description covers all major usage modes (participant-hosted, mock-hosted, manual-mode), the next step (form_submit), and the optional step_key behavior. With an output schema present and annotations providing safety and idempotency info, the description fully addresses the tool's complexity.

  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% with descriptions for all parameters. The description adds extra meaning to step_key by explaining the omission behavior ('use whichever form the flow is currently waiting on'), which is not in the schema's property description. Session_id and transaction_id are already well-defined in the schema, so no further elaboration is needed.

  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 'Read the form a flow is waiting on' – a specific verb and resource. It distinguishes the tool from siblings by explaining its role as a precursor to form_submit and differentiates from flow_get_status/flow_await by focusing on fetching and returning fields.

  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 across three contexts: participant-hosted (fetches fields, then call form_submit), mock-hosted (nothing to do but wait), and manual-mode (returns a link to hand to a person). It also instructs on omitting step_key to use the current form, giving clear when-to-use and what-to-do guidance.

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

• flow_awaitA
  5/5.0
  Behavior5/5

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

  Beyond the readOnlyHint and openWorldHint annotations, the description discloses blocking semantics, timeout behavior (timed_out: true means nothing happened, call again), seq bookkeeping to avoid duplicates, and that filtered events are still delivered but do not end the wait. This significantly enriches behavioral understanding without contradicting annotations.

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

  Conciseness5/5

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

  The description is well-structured with a clear lead sentence, bolded scope separation, and no redundant content. It is dense but every sentence adds operational value, covering scopes, filtering, seq, timeout, and preference over polling. It remains focused despite its length.

  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 (multiple scopes, filtering, seq semantics, timeout), the description covers all necessary usage aspects. It mentions key return concepts like runs and timed_out, and with the output schema available, it does not need to detail every return field. This is complete for effective use.

  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?

  While the schema already has 100% parameter description coverage, the tool description adds cross-parameter semantics: after_seq is used to avoid duplicates in run scope and ignored in session scope, kinds/flow_ids filter only wake conditions but not reporting, and transaction_id is learned when the first action arrives. This goes beyond simple field definitions.

  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: 'Block until something happens, then report it.' It distinguishes two scopes (named flow/transaction vs. whole session) and contrasts with sibling flow_get_status by instructing 'Always prefer this over polling flow_get_status.' This provides a specific verb, resource, and behavior that sets it apart.

  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 tells when to use which scope: name a flow_id to wait on that run, name neither to wait on the whole session and 'use when you have nothing to do.' It also says to prefer this over flow_get_status, and explains filtering with kinds/flow_ids and re-calling on timed_out. This is comprehensive guidance with clear alternatives.

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