Server Quality Checklist

Tool Scores

• hello_aigent_subscribersB
  3.4/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of disclosure. It does add useful context by requiring the admin token and enumerating the fields returned (agent, principal, topics, etc.), but it does not explicitly state whether this is a read-only operation or describe potential side effects, rate limits, or pagination behavior.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that conveys the core purpose, audience, and contents in a compact manner. Every word is informative, with no filler or repetition.

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

  Completeness4/5

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

  For a simple tool with one parameter and no output schema, the description provides the essential context: what it returns (field list), the auth requirement, and status values. It doesn't mention error conditions or pagination, but these are not critical for a basic subscriber list retrieval.

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

  Parameters3/5

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

  The input schema has 100% coverage for the single 'feed' parameter ('Feed id'). The description adds no additional 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.

  Purpose4/5

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

  The description clearly identifies the resource (feed's subscriber list) and its contents, distinguishing it from sibling tools like event_log or overview. However, it lacks an explicit verb like 'retrieve' or 'list', relying on the noun phrase to imply the operation.

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

  Usage Guidelines2/5

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

  No guidance is given on when to use this tool versus alternatives, nor are any exclusions or prerequisites mentioned beyond the admin token requirement. The context of 'audience you own' is implied but not actionable for tool selection.

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

• hello_aigent_overviewA
  3.6/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral transparency burden. It discloses the admin token requirement and lists the data returned, which implies a read-only operation. However, it does not describe side effects, return format, or error behavior, leaving some gaps for a tool with no annotation support.

  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 concise sentence listing the overview contents, followed by a short note on authorization. Every part is essential and front-loaded with the tool's purpose.

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

  Completeness4/5

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

  Given the tool's simplicity (one parameter, no output schema, no annotations), the description provides sufficient information: what the overview includes, the auth requirement, and the resource type. It could mention the return format or an example, but it is reasonably complete for its complexity.

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

  Parameters3/5

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

  The sole parameter 'feed' is fully described in the schema as 'Feed id' (100% coverage). The description adds no additional parameter semantics beyond referencing 'a feed' in the overview text, so it meets the baseline without enhancing the schema.

  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 it provides an overview for a feed and enumerates specific metrics (subscribers, fetches today, 7-day return rate, etc.). It lacks an explicit verb like 'get' or 'retrieve,' but the tool name and context make the action clear. It distinguishes from sibling tools by aggregating feed-level data, though it does not name alternatives.

  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 use when a high-level feed summary is needed and notes the admin token requirement. However, it does not explicitly state when to choose this over siblings like hello_aigent_subscribers or hello_aigent_event_log, nor does it mention any exclusions or alternative comparisons.

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

• hello_aigent_funnelA
  3.7/5.0
  Behavior3/5

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

  No annotations are provided, so the description must carry the behavioral disclosure burden. It discloses the admin token requirement, which is an important authorization constraint, and describes the funnel stages. However, it does not explicitly state that it is a read-only operation, nor describe return format or potential limitations. It adds some behavioral context (auth requirement) but not comprehensive disclosure.

  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?

  Description is two short sentences with no filler. It front-loads the core output definition and then adds the auth requirement. Every phrase contributes either to what the tool returns or a usage condition.

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

  Completeness3/5

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

  No output schema exists, so the description must clarify return values. It mentions return-rate and act-rate, giving some sense of output, but does not specify the exact structure, whether counts are included, or how the window affects results. Given the tool's simplicity and full schema coverage, this is adequate but incomplete.

  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 descriptions cover 100% of parameters (feed id, window with default), so the description need not add much. It rephrases the window concept as 'over a window' but does not add new meaning about parameter formats, value semantics, or dependencies beyond the schema. Baseline 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 identifies the tool as a cohort funnel showing subscribed → returned → acted stages for a feed, with return-rate and act-rate. This distinguishes it from sibling tools like event_log or subscribers by focusing on conversion funnel metrics. The resource (feed) and window are specified, 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 Guidelines3/5

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

  The description implies usage for funnel analysis over event logs or subscriber lists, but does not explicitly state when to choose this over alternatives. No exclusions or alternative tool references are provided, leaving the agent to infer from the tool's purpose. The admin token requirement is a prerequisite, not usage guidance.

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

• hello_aigent_event_logA
  4/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden for behavioral disclosure. It adds important traits: it is an audit (read-only), newest first, agent-attributed, and requires an admin token. However, it does not disclose the exact return structure or error behavior, though these are partially inferable.

  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, front-loaded sentence followed by a terse requirement note. It includes no filler and conveys purpose, scope, ordering, attribution, and authorization in 17 words, earning a high score.

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

  Completeness4/5

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

  For a simple audit tool with 3 params and no output schema, the description provides adequate context: what it lists, the event types, ordering, attribution, and auth requirement. It does not describe the return fields, but since there is no output schema, a brief note on output would improve completeness; still, the current description is sufficient for basic usage.

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

  Parameters3/5

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

  Schema covers 100% of parameters with descriptions, so the baseline is 3. The description's mention of 'filterable' aligns with the type parameter but adds no new semantics beyond the schema. The limit and feed parameters are already described.

  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 filterable audit of feed events, enumerating the event types (subscribe/fetch/action/unsubscribe) and specifying the ordering (newest first). This distinguishes it from sibling tools like hello_aigent_subscribers (subscriber lists) and hello_aigent_report_event (event reporting/writing).

  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 gives clear context that this is an audit log for feed events, implying use when reviewing past event activity. However, it does not explicitly state when to prefer it over alternatives or provide exclusions, such as noting that hello_aigent_report_event is the write counterpart. The admin token requirement is a useful prerequisite but not a usage guideline for tool selection.

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

• hello_aigent_report_eventA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It discloses authentication requirements ('Uses the feed's publisher token or the admin token'), which is valuable behavioral context. However, it does not mention side effects, idempotency, or return behavior, leaving some transparency gaps.

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

  Conciseness5/5

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

  The description is two sentences with zero waste. It front-loads the core purpose, then adds the trigger condition and authentication note in a concise, structured manner.

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

  Completeness4/5

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

  The description adequately covers purpose, trigger, and authentication for a simple reporting tool. However, with no output schema or annotations, it does not explain return values or error conditions, which is a minor gap. Overall, the essential context is present.

  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 baseline is 3. The description does not add parameter-level detail beyond what the schema already provides, but it does reinforce the semantic link between 'subscription' and 'action' through phrases like 'subscriber's agent completes one of your callable actions.'

  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 reports an action outcome for a subscription, explicitly identifying it as the 'acted' signal for the analytics funnel. This specific verb+resource combination distinguishes it from sibling tools like hello_aigent_event_log.

  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 trigger condition ('Call this after a subscriber's agent completes one of your callable actions'), providing clear context for when to use it. It does not mention alternatives or exclusions, but the trigger is specific enough to guide tool selection.

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

• hello_aigent_create_feedA
  4.2/5.0
  Behavior5/5

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

  With no annotations provided, the description carries full responsibility for disclosing side effects. It does this thoroughly: mints an Ed25519 signing keypair, creates a per-feed publisher token that is shown only once, returns the discovery file, and requires the admin token. This goes well beyond basic 'create' semantics and alerts the agent to important operational 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 three sentences, front-loads the core purpose, and each sentence adds essential information (purpose, side effects, critical token warning). There is no redundancy or filler. It is concise and well-structured for an agent to parse quickly.

  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 has no output schema and no annotations, the description covers the key non-obvious aspects: the one-time token, admin token requirement, and returned discovery file. It could mention what happens after creation (e.g., feed appears in list_feeds) or how to share the discovery file, but it is complete enough for the primary use case.

  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 descriptions cover 100% of parameters, so the baseline is 3. The tool description does not add any parameter-specific guidance beyond the schema; it focuses on high-level behavior (token, keypair, discovery file). Since the schema already explains each parameter, the description does not need to supplement it.

  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: 'Create a Hello Aigent feed', with a parenthetical explaining what a feed is. It also distinguishes the tool from siblings by mentioning the unique side effects (minting keypair, returning discovery file). This clearly states what the tool does and is not a tautology.

  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 for creating a feed and notes it requires the admin token, which hints at when it should be used. However, it does not explicitly state when not to use it or mention any alternative tools (e.g., list_feeds for viewing existing feeds). Usage is implied rather than explicitly contrasted with siblings.

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

• hello_aigent_discovery_fileA
  4.2/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the burden. It adds key behavioral facts: 'Public; no token needed' and the hosting requirement ('host it at your site's /.well-known/hello-aigent.json'). This informs the agent of authentication expectations and post-processing steps. It doesn't describe error handling or return format, but these are partially inferred.

  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, both purposeful. The first sentence names the operation and resource; the second provides deployment context and authentication status. No redundancy, front-loaded with the core action.

  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 one-parameter read tool with no output schema, the description covers the purpose, usage context, a necessary post-condition (hosting the file), and authentication. It lacks details about the file contents or error scenarios, but given the simplicity, it is sufficiently complete.

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

  Parameters3/5

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

  The schema already describes the only parameter 'feed' as 'Feed id' (100% coverage). The description merely repeats 'for a feed' without adding new meaning, such as expected format or examples. Since schema coverage is complete, the 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 states a specific action ('Get the generated discovery file (hello-aigent.json)') on a specific resource ('for a feed'), clearly distinguishing this from sibling tools like event log or publishing. The verb 'get' and the file name make 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 provides clear usage context: 'host it at your site's /.well-known/hello-aigent.json so agents can find and subscribe.' It implies when to use this tool (when setting up agent discovery). It doesn't explicitly mention alternatives, but no sibling tool provides this functionality, so the absence is acceptable.

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

• hello_aigent_publishA
  4.4/5.0
  Behavior5/5

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

  No annotations are provided, so the description must fully convey behavioral traits. It discloses Ed25519 signing by the server, subscriber verification, token-based authentication, and the critical side-effect of broadcasting to every subscriber. This goes well beyond a simple 'publish' statement and gives the agent a strong understanding of consequences.

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

  Conciseness5/5

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

  The description is concise, with three sentences covering purpose, mechanism, and a warning. It is front-loaded with the main action and contains no filler or redundant 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 lack of an output schema and the complexity of the operation (7 parameters, nested objects, side effects), the description covers essential context: signing, authentication, broadcast, and owner confirmation. It does not detail response formats or error handling, but the core usage is sufficiently specified.

  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 high (86%), and the input schema already provides meaningful descriptions for each parameter. The tool description does not add additional parameter-level semantics, so a baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Publish a signed update to a feed.' This is specific with a verb and resource, and it distinguishes itself from sibling tools like create_feed and list_feeds. No ambiguity about what this tool does.

  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 use, including that publishing broadcasts to all subscribers and requires a publisher or admin token. It also includes an important caution to confirm content with the feed owner before calling. However, it does not explicitly mention alternatives or when not to use this tool compared to siblings.

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

• hello_aigent_list_feedsA
  4.5/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the auth requirement (admin token) and the output contents (feeds with specific fields). It does not mention pagination or rate limits, but for a simple list operation this is adequate.

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

  Conciseness5/5

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

  Two concise sentences: the first states the action and outputs, the second states the auth requirement. No unnecessary words, 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?

  For a zero-parameter list tool, the description is complete: it specifies the exact feed fields returned and the required admin token. No output schema exists, so the description fully handles return value transparency.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema fully covers parameter semantics. The description adds context about the return fields, which is helpful but not required for parameters. Baseline for 0 parameters is 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 verb ('List'), the resource ('feeds'), and the scope ('you own'), while also enumerating the returned fields (id, title, topics, latest_seq, discovery URL). This distinguishes it from sibling tools like create_feed and publish.

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

  Usage Guidelines4/5

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

  The description implies use when you need to list the feeds you own and explicitly mentions the admin token requirement. It does not provide explicit alternatives or when-not-to-use guidance, but the sibling tool names make the context clear.

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