Skip to main content
Glama

HODDS

by ai.hodds
OverviewDiscussionsAdmin

List watches

list_watches
Read-onlyIdempotent

Lists the watches of the organisation with their challenger and number of pending alerts; include_closed adds the watches closed in the last 30 days. Needs an organisation token (Authorization: Bearer hodds_...); without it the tool returns the error token_required.

Input Schema

NameRequiredDescriptionDefault
include_closedNotrue: include watches closed in the last 30 days.

Output Schema

NameRequiredDescriptionDefault
countYes
pendingNoDelivery on the next call: alerts that wait for this organisation. Absent when there is nothing to deliver. Only ack_alerts empties it.
summaryNoOne sentence in English, or in French when the request was in French.
watchesYes
offer_versionNo
free_watch_usedYesHistorical free-watch indicator; false grants no prepaid right. See GET /api/plan.offer_version.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedOutput schema / description
      Previous value: -"Watches of the organisation, as returned by list_watches and GET /api/watches. Closed watches of the last 30 days appear only with include_closed."New value: +"list_watches / GET /api/watches: activated watches only, no drafts. Closed within 30 days included only with include_closed."
    • addedOutput schema / properties / free_watch_used / description
      Added value: +"Historical free-watch indicator; false grants no prepaid right. See GET /api/plan.offer_version."
    • addedOutput schema / properties / offer_version
      Added value: +{
+  "enum": [
+    "legacy",
+    "prepaid-v1"
+  ],
+  "type": "string"
+}
    • changedOutput schema / title
      Previous value: -"HODDS watch list (0.3.0)"New value: +"HODDS watch list (0.6.0)"
  2. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the lower bar applies, and the description still adds real value: the exact token scheme ('Authorization: Bearer hodds_...') and the concrete failure mode ('token_required'). It doesn't mention volume, pagination, or ordering of the returned list, which keeps it from a 5.

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 compact sentences with zero filler: listing semantics and flag behavior come first, auth and error behavior second. Every clause carries information an agent can act on.

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 read-only list tool with full schema coverage and an output schema, the description covers what matters: scope, flag effect, auth, and error case. Ordering/pagination of results is the only notable omission, and the output schema partly compensates.

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 single parameter is already documented, so baseline 3 applies. The description restates include_closed with the same 30-day window already present in the schema, adding essentially no new meaning.

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?

States a specific verb and resource ('Lists the watches of the organisation') and describes what each entry carries (challenger, pending alert count), which implicitly distinguishes it from the singular get_watch sibling. It does not name the sibling or state the contrast explicitly, so it falls short of a 5.

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 include_closed flag's effect (adds watches closed in the last 30 days) is spelled out, and the auth requirement is stated, but there is no explicit guidance on when to choose this over get_watch or other listing tools such as list_gaps/list_processes. Usage is implied rather than directed.

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

All HODDS toolsInspect
Try in Browser
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources