Server Quality Checklist

Tool Scores

• tracer-executeB
  3/5.0
  Behavior3/5

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

  Annotations already convey the destructive nature (destructiveHint: true, readOnlyHint: false), so the description carries a lighter burden. It adds the behavioral nuance that discovery must precede execution, echoing the openWorldHint. However, it does not disclose what happens on mutation, whether confirmMutation/mutationReason gating behaviors exist, or consequences of actions beyond the annotation flags — no contradiction, but no added depth either.

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

  Conciseness3/5

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

  The description is just two sentences but wastes the first on the near-tautological 'Execute Tracer API actions.' The second sentence is more useful, conveying the discover-first workflow. This is under-specification dressed as brevity — short but not optimally 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?

  With 8 parameters, 100% schema coverage, no output schema, and a meaningful destructive annotation, the description sits at the minimum viable level. It points to tracer-discover for operational details, which is a sensible pattern for an execute-all endpoint, but does not mention mutation safety requirements or the confirmMutation/critical-params gating that an agent might need to know about before invoking. Adequate for the discover/execute pattern, nothing more.

  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?

  Parameter descriptions are already informative (each param has a description with examples for action), giving 100% schema description coverage and thus no heavy lifting is demanded from the tool's prose. The description adds no parameter syntax, format, or workflow detail beyond the schema. Baseline 3 is appropriate given the easy-to-parse property descriptions and the generic discover-then-call nature of this tool.

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

  Purpose2/5

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

  The phrase "Execute Tracer API actions" merely restates the tool name 'tracer-execute' as a sentence, which is a tautology. The second sentence shifts to telling the agent to use tracer-discover, offering no concrete statement of what this tool actually executes or produces. It fails the verb+resource test with specificity.

  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 sequencing guidance by naming the sibling tool tracer-discover and instructing to use it 'first... before calling this tool.' It also lists what the discover step inspects (rule/limit transitions, validation bodies, audit filters, operational endpoints), giving actionable context on how to engage with the tool. It could be clearer about when to prefer other execute siblings, but the alternative is explicitly named.

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

• midaz-executeA
  3.5/5.0
  Behavior2/5

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

  Annotations already indicate destructive=true, readOnly=false, and idempotent=false. The description adds no further behavioral context—no mention of authentication, rate limits, error handling, or what happens on mutation (e.g., requiring confirmation). The only extra info about mutations appears in the schema (mutationReason, confirmMutation), not the description. Thus, the description adds minimal value 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?

  Two concise sentences, front-loaded with the core action ('Execute Midaz API operations'). It efficiently states the primary workflow (discover first) and scope without fluff. Could be slightly improved by including a brief example, but it's appropriately sized for a generic executor.

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

  Completeness2/5

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

  For a generic tool with 7 parameters, nested objects, and no output schema, the description is minimal. It doesn't mention response formats, error behaviors, or the requirement for mutation confirmation (which is in the schema but not the description). It relies heavily on midaz-discover to fill in details, making it adequate for a wrapper but incomplete as a standalone description, especially since it lacks any guidance on return values or failure modes.

  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%: every parameter (resource, action, body, pathParams, queryParams, mutationReason, confirmMutation) has a description in the schema. The tool description does not add any parameter-specific meaning beyond what the schema provides. It only hints that discover is needed to determine parameters. Baseline is 3 for high coverage, and this tool meets that baseline without adding extra.

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

  Purpose4/5

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

  The description states it executes Midaz API operations and lists supported resource types (organizations, ledgers, assets, etc.), giving a clear purpose. It distinguishes from the discover tool by explicitly directing to use midaz-discover first, but doesn't differentiate from sibling executors (e.g., fetcher-execute) beyond the Midaz domain, so it's clear but not deeply specific.

  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 midaz-discover first to find the right resource+action and required parameters, then call this tool to execute.' This clearly tells when and how to use it, and implies when not to (i.e., discovery should be done via midaz-discover, not here). It also mentions support for all CRUD operations, covering the scope of use.

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

• fetcher-executeA
  3.7/5.0
  Behavior3/5

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

  Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description doesn't need to repeat that. It adds context about requiring confirmMutation and mutationReason for mutating actions, which is useful. However, it doesn't disclose other behavioral traits like rate limits or error handling, and the description doesn't contradict 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 single, focused sentence that front-loads the purpose and immediately directs to the discover tool. No wasted 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?

  Given the tool has 9 parameters, nested objects, and no output schema, the description is somewhat thin. It relies heavily on fetcher-discover to fill gaps, which is a reasonable pattern but leaves the agent without direct knowledge of return values or edge cases. The description is adequate but not rich.

  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 the schema already documents all parameters. The description adds minimal extra meaning beyond pointing to fetcher-discover for context. It doesn't explain parameter relationships or provide examples, so it's at baseline 3.

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

  Purpose4/5

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

  The description clearly states the tool executes Fetcher manager API actions, with a specific verb ('Execute') and resource ('Fetcher manager API'). It distinguishes from siblings by referencing fetcher-discover for context, but doesn't explicitly contrast with other execute tools (e.g., midaz-execute).

  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 instructs to use fetcher-discover first to inspect required context, which is a clear usage guideline. However, it doesn't provide when-not-to-use or alternatives beyond the discover step, so it's not a full 5.

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

• flowker-executeA
  3.7/5.0
  Behavior3/5

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

  Annotations already cover destructive, non-read-only, non-idempotent behavior. The description adds some useful context by referencing auth expectations, Idempotency-Key requirements, and webhook method/path behavior, but it does not describe consequences, required confirmations, or error/response behavior beyond what annotations and schema already imply.

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

  Conciseness5/5

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

  The description is two sentences: the first states the tool's core purpose, and the second directs the agent to the necessary discovery step. There is no filler, repetition, or wasted content.

  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 generic executor with 8 parameters, no output schema, and destructive annotation, the description is somewhat thin. It relies heavily on flowker-discover to provide the missing behavioral and configuration context. This is a reasonable design, but the description itself does not fully equip an agent to invoke the tool correctly without first consulting a sibling tool.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents all 8 parameters, including body, headers, pathParams, queryParams, mutationReason, and confirmMutation. The tool description itself adds no parameter-specific meaning, 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.

  Purpose4/5

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

  The description states a specific action ('Execute Flowker API actions') and clearly positions it as the execute counterpart to flowker-discover. It does not enumerate concrete scenarios like starting workflows or posting webhooks, but the verb-resource pair and sibling distinction are reasonably clear.

  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 guidance to 'Use flowker-discover first' to inspect auth expectations, Idempotency-Key requirements, configuration payloads, and webhook behavior. This clearly signals a prerequisite and distinguishes the discovery tool from the execution tool, though it does not explicitly 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.

• matcher-executeA
  3.7/5.0
  Behavior3/5

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

  Annotations already indicate destructiveHint=trueborn, readOnlyHint=false, so the description doesn't need to restate that. It adds scope information but does not elaborate on the effects of actions, auth requirements, or error behavior. It provides some context about the 'live slice' but not deep behavioral details.

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

  Conciseness5/5

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

  The description is two sentences: the first states the purpose and scope; the second directs to matcher-discover for prerequisites. It is front-loaded with the action verb and resource list, with no redundant phrasing or filler.

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

  Completeness3/5

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

  Given the tool's breadth (8 resource types) and that it's an executor with an input schema that documents parameters, the description provides adequate scope but doesn't explain action-specific requirements, return formats, or caveats. It points to discover for details, which partially compensates, but for such a flexible tool, more context on usage patterns could be added.

  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 provides 100% description coverage for all 8 parameters, including examples like 'create', 'startExtraction' for action Apaçı and pathParams/queryParams explanations. The description adds no additional parameter-level detail beyond pointing to matcher-discover for payload inspection, so it meets the baseline for high schema coverage.

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

  Purpose4/5

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

  The description clearly states the tool's function: 'Execute Matcher API actions' and enumerates specific resource areas (contexts, sources, field maps, etc.), distinguishing it from the sibling 'matcher-discover' tool which is for inspection. It uses a specific verb and identifies the resource scope, though it is somewhat generic as an execute-all tool.

  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 instructs to 'Use matcher-discover first to inspect payloads, required headers, and reporting export behavior,' providing clear guidance on when to use the sibling tool before this one. It implies this tool is for execution after discovery, giving context for appropriate usage.

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

• lerianA
  3.9/5.0
  Behavior3/5

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

  The description aligns with the readOnlyHint annotation by noting that live execution is available elsewhere, but it adds little beyond that. It does not discuss potential errors, required authentication, or output behavior, so transparency is moderate given annotations already cover read-only and idempotency.

  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 moderately concise and front-loaded with the core purpose ('Unified portfolio tool'), then lists functions and alternatives. It avoids redundancy but could be trimmed slightly, such as removing the full list of product names that are also in the schema enum.

  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?

  Provides enough context to understand the tool's role and boundaries (e.g., no live execution, pointing to siblings). It does not describe return values or detailed behavior, but given the schema richness and explicit sibling references, the agent is likely to use it correctly. Missing output format description is a minor gap.

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

  Parameters3/5

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

  The description adds minimal parameter context beyond what the schema already provides. While it restates the tool's operations, the schema descriptions already explain each parameter's use, required conditions, and enums, so the added semantic value is low.

  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 a unified portfolio interface for Lerian products, enumerating specific functions (discover, docs, generate SDK, search) and explicitly naming sibling tools for live API execution, which distinguishes its purpose from those alternatives.

  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 guidance that live API execution should be done via product-specific tools and cross-product workflows via 'portfolio-workflow', helping the agent choose when to use this tool versus siblings. It does not elaborate on contextual prerequisites or when to pick one operation over another in detail.

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

• reporter-executeA
  4/5.0
  Behavior4/5

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

  Annotations already signal destructive and non-idempotent behavior. The description adds context about non-trivial request requirements (multipart, X-Idempotency, binary download) that go beyond annotations, informing the agent of potential complexities without overclaiming safety.

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

  Conciseness5/5

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

  Two sentences: the first states the core purpose directly, the second delivers a crucial usage directive. No filler or repetition of schema details; every sentence earns its place.

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

  Completeness4/5

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

  For a generic executor with many parameters and no output schema, the description points to reporter-discover for detailed requirements, covering the most complex behaviors. It doesn't enumerate all actions or return values, but the schema and annotations fill those gaps adequately.

  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 provides detailed descriptions for all 9 parameters, including action, resource, multipart, headers, and confirmation fields. The description only briefly mentions multipart and headers, adding minimal value over the schema, so the baseline of 3 applies.

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

  Purpose4/5

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

  The description clearly states the tool executes Reporter manager API actions, with a specific verb ('Execute') and resource ('Reporter manager API'). It distinguishes itself from reporter-discover by framing itself as the execution counterpart, though it doesn't enumerate specific actions beyond the broad category.

  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 instructs to use reporter-discover first to inspect multipart requirements, headers, and download behavior, which sets clear prerequisites. It does not name alternative tools but implies the discover-execute pairing for this domain.

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

• tracer-discoverA
  4/5.0
  Behavior3/5

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

  Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context about what is inspected but does not disclose additional behavioral traits (e.g., rate limits, side effects). Given annotations, the bar is lower, and the description provides some value.

  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, concise and to the point, with no redundant or extraneous information. It structure is clear, starting with the core purpose and following with usage guidance.

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

  Completeness3/5

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

  The description conveys the tool's purpose and typical use, but lacks details about parameter interplay, expected output, or negotiation of the 'intent' values. Given the schema already lists parameters, the description is adequate but not comprehensive, missing opportunities to explain how the parameters map to discovery actions.

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

  Parameters2/5

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

  The description does not mention any of the five parameters (query, action, intent, resource, component). While the schema provides brief descriptions, they are generic (e.g., 'Search query for intent="search"'). The tool description offers no added semantic guidance for parameter usage, leaving the agent to rely solely on 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 function: discovering Tracer API resources, actions, and execution contracts. It also specifies what it inspects (rule/limit operations, validation payloads, audit filters, endpoints), distinguishing it from execute 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?

  Explicitly states when to use: 'Use this before tracer-execute', providing a clear context and purpose. This guides the agent to invoke it during pre-execution discovery.

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

• fetcher-discoverA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context about what the discovery reveals (path params, required headers like organizationId/productName, body shapes, supported operations), 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 tightly written sentences with no filler. The first sentence states the core purpose, and the second provides immediate usage guidance and concrete examples. Every phrase earns its place.

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

  Completeness4/5

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

  For a discovery tool with 5 schema-covered parameters and strong annotations, the description is sufficiently complete: it explains what the tool does, when to use it, and what kinds of information it surfaces. It does not describe return format, but no output schema exists and the discovery nature makes the return value implicit.

  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 the schema already documents all 5 parameters. The description adds contextual examples of what to inspect (e.g., organizationId/productName headers) but does not add per-parameter meaning beyond what the schema provides. 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 uses a specific verb ('Discover') and names the exact resource scope ('Fetcher manager resources, actions, and execution contracts'). It clearly differentiates from fetcher-execute by framing this as an inspection/discovery tool rather than an execution tool.

  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 the tool ('Use this before fetcher-execute') and what to inspect (path params, headers, body shapes, supported operations). It does not explicitly list when-not-to-use scenarios or name alternative discovery tools, but the guidance is clear and actionable.

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

• flowker-discoverA
  4.2/5.0
  Behavior4/5

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

  The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces this by framing the tool as purely inspect/discover and adds detail about what can be safely inspected. No contradictions with annotations are present.

  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 long, front-loaded with the tool's purpose, and each sentence contributes useful guidance. It avoids redundant restating of the tool name and gets straight to instructions for the agent.

  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 discovery tool with rich annotations and a well-described schema, this description provides enough contextual framing about what can be discovered and when to call it. It does not detail output shape or exhaustive edge cases, but given no output schema and the intentionally broad discovery scope, the level of detail is reasonably 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 description coverage is 100%, so the schema already documents all 5 parameters including enums for intent and component. The description adds high-level domain context but does not substantially enrich parameter-level meaning beyond what the schema provides, so a baseline 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 identifies the tool as a discovery mechanism for Flowker API resources, actions, and execution contracts. It uses specific verbs like 'Discover' and 'inspect' and distinguishes this tool from its execution counterpart flowker-execute by explicitly framing its pre-execution role.

  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 context: 'Use this before flowker-execute' and lists the kinds of things an agent should inspect. It does not explicitly name alternative discovery tools, but it clearly communicates the intended workflow phase and purpose.

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

• matcher-discoverA
  4.2/5.0
  Behavior4/5

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

  Annotations already communicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces this read-only nature ('Discover', 'inspect') and adds useful context about the live slice and what facets are inspectable, such as export behavior. It does not cover rate limits or error behavior, but the annotations cover the core safety profile.

  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 purpose, and every part serves a function: scope enumeration and usage guidance. There is no filler, repetition, or unnecessary detail.

  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 there is no output schema, the description does a good job of setting expectations for what the discovery response will cover: headers, path params, query filters, payload requirements, and export behavior. It also lists the meaningful resource categories covered in the current live slice, making it sufficiently complete for an initial API discovery tool.

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

  Parameters3/5

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

  Input schema has 100% description coverage for all five parameters, including enums and examples. The description adds general context about discovery but does not meaningfully enhance individual parameter semantics beyond what the schema already provides, 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 opens with a specific verb + resource: 'Discover Matcher API resources, actions, and execution contracts.' It clearly differentiates itself from matcher-execute by stating 'Use this before matcher-execute.' The listing of covered API areas also clarifies the tool's exact 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 an explicit usage directive: 'Use this before matcher-execute to inspect headers, path params, query filters, payload requirements, and export behavior.' It provides clear context and a named alternative (matcher-execute), though it does not explicitly exclude other discover siblings 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.

• portfolio-workflowA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare destructive, non-idempotent, and open-world hints. The description adds behavioral context on statefulness ('stateful workflow sessions', 'execute-next progression') and notes that workflows are implemented, giving the agent a clearer picture of what to expect beyond the annotation flags.

  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 concise sentences front-load the core purpose and follow with specific capabilities and examples. No wasted words; every sentence adds information.

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

  Completeness4/5

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

  Given the tool's complexity (8 parameters, multiple intents, workflows), the description provides a solid high-level overview. It names the workflows and core functions, and while it doesn't explain every step or session detail, the schema compensates. The absence of an output schema is noted, but the description offers enough context for initial use.

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

  Parameters3/5

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

  All parameters have descriptive schema entries, so coverage is 100%. The description's mention of capabilities like 'readiness planning' and 'execute-next' maps to the intent enum, but it does not add significant new meaning beyond the schema, which is already detailed.

  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 ('orchestrating') and resource ('cross-product workflows across Lerian products'). It enumerates specific capabilities (discovery, planning, sessions, execution) and lists concrete workflows, effectively distinguishing it from the single-product discover/execute 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 Guidelines4/5

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

  The description implies usage for cross-product orchestration, setting it apart from siblings that focus on individual products. However, it does not explicitly state 'use this instead of X' or provide when-not-to-use scenarios, so it stops short of full usage guidance.

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

• reporter-discoverA
  4.2/5.0
  Behavior4/5

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

  Annotations already disclose readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond those by naming the kinds of execution-contract details that can be discovered, such as request headers, multipart requirements, and endpoint availability.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core purpose, and every phrase adds useful information. There is no redundancy or filler.

  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?

  With rich annotations and a fully described schema, the description adds enough operational context for a discovery tool. It does not describe return formatting or output structure, but that is less critical for a discover-style tool and no output schema exists.

  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 the schema fully documents each parameter and the description need not repeat those details. The description adds domain context about what can be inspected, but it does not add parameter-specific meaning 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 discovers Reporter manager resources, actions, and execution contracts, with a specific verb and resource scope. It also differentiates from reporter-execute by positioning itself as the pre-execution discovery tool.

  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 says to use this before reporter-execute and lists concrete inspection targets such as multipart requirements, X-Idempotency headers, and download behavior. It provides clear context but does not explicitly mention when not to use it or compare with other discover tools.

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

• midaz-discoverA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds context about the discovery capabilities (listing, describing, searching, filtering) and emphasizes it is a pre-execution step, providing value 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 sentences, front-loaded with the primary purpose, and zero filler. All information is essential and directly supports agent decision-making.

  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 discovery tool with no output schema, the description sufficiently explains the types of actions it supports (listing, describing, searching, filtering) and its role in the workflow. It covers the main use cases and provides enough context to know what to expect.

  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 all parameters are documented with their own descriptions. The description does not add extra semantics beyond the schema but reinforces the purpose of understanding required parameters. Baseline 3 is appropriate because the schema fully handles parameter meaning.

  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 it discovers Midaz API resources, actions, and schemas. It names the specific resource (Midaz API) and differentiates from the sibling tool midaz-execute, fulfilling the verb+resource+scope requirement.

  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 instructs to use before midaz-execute to find the right resource+action and required parameters, clearly indicating when to use it. Also lists the supported intents (list, describe, search, filter), which helps distinguish from other discover tools for different APIs.

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

• underwriter-discoverA
  4.4/5.0
  Behavior4/5

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

  Annotations already disclose read-only, idempotent, non-destructive behavior; the description aligns with them and adds useful dynamic context: it inspects currently mounted endpoints and execution contracts. It could have described what a successful response contains, but for a read-only discovery tool this is sufficient 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 two sentences, information-dense, and front-loaded with the key purpose. No word is wasted, and the second sentence supports usage without redundancy.

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

  Completeness4/5

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

  For a discovery tool with a rich intent enum and full parameter documentation, the description covers what the tool is for, when to call it, and what areas to explore. It does not describe the shape of returned discovery results, and there is no output schema, but the likely output is self-describing for a discovery endpoint.

  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 at 100%, so the parameters are fully documented and the description does not need to repeat their semantics. The description enriches examples like jurisdictions, loan products, and previewSchedule, but adds no new parameter-level guidance 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 names the subject (Underwriter API resources, actions, and execution contracts) and the verb 'discover/inspect', making the tool's purpose obvious. It distinguishes itself from underwriter-execute by framing this as the preparation step, which is further supported by the sibling naming pattern.

  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 says to use this tool before underwriter-execute and lists concrete things to inspect, such as jurisdiction discovery, loan product lifecycle actions, and schedule preview payloads. This gives the agent a clear when-to-use directive and differentiates it from the execute sibling.

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

• underwriter-executeA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare destructiveHint: true and readOnlyHint: false; the description confirms and contextualizes this by warning about 'bearer-auth requirements for protected routes' and mentioning decimal-amount-as-string encoding in the schedule preview payload. That specific encoding detail is exactly the kind of non-obvious behavioral disclosure that the agent needs to invoke correctly on live API routes.

  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, zero filler, maximal information density. Every clause either names the tool's purpose, references the prerequisite discovery workflow, or surfaces a non-obvious API quirk. The awaited 'schedule preview' detail is placed strategically after establishing the alternative-tool-first mandate, so the structure guides the agent's reading order.

  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 an execute tool with 8 parameters, no enum values, and no output schema, the description carries a huge burden—and it delivers. It covers the authentication prerequisites, points to the discovery sibling for request contracts, names the encoding gotcha, and links the mutation flags (confirmMutation) to 'live API actions' implicitly. The 'decimal amounts encoded as strings' note seems to address a known failure mode. This is a complete briefing packet, not just a description.

  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 earns an extra point by revealing cross-parameter behavior: the relationship between action values like 'previewSchedule' and the schedule preview payload's string-encoded decimals, plus the fact that headers are 'allowlisted' and that UNDERWRITER_AUTH_TOKEN is authoritative. It adds meaning to parameters that the schema alone doesn't convey.

  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?

  Uses a specific verb+resource construction ('Execute Underwriter API actions') and immediately orients the agent to the companion workflow by naming underwriter-discover explicitly. It clearly positions itself as the executor of actions that require prior discovery of contracts, which differentiates it from siblings. The description adds genuine semantic weight beyond the tool name alone.

  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 command: 'Use underwriter-discover first to inspect bearer-auth requirements for protected routes, loan product path/query contracts, and the schedule preview payload.' This tells the agent exactly when to use the sibling tool versus this one, and what specific things to check (auth requirements, path/query contracts, schedule preview payload). This is textbook 'when-to-use vs. alternative' guidance.

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