list_annotationsFetch annotations sorted by recency, filter by metric, and optionally include retracted entries.
Read annotations, most recent first. Optionally filter to one metric. Retracted annotations are excluded unless include_retracted is true.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| metric | No | ||
| include_retracted | No |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It discloses ordering, filtering capability, and the default exclusion of retracted annotations, which is valuable. However, it does not mention any side effects (though read-only by nature), response format, or performance considerations. It adequately covers the key behavioral aspects for a list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the key purpose (read, most recent first) and then adds optional behavior in an efficient manner. There is no wasted wording, and every clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a simple list operation with no output schema and simple parameters, the description is mostly complete. However, it does not describe the return format (e.g., fields of each annotation), which might be relevant. But for a straightforward list, the omission is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meaning. It does clarify the metric filter and include_retracted flag, but it does not explain the limit parameter's semantics beyond the schema's default. The description adds some context for two of three parameters, but the limit parameter remains only schema-defined. This is a moderate compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists annotations with a specific ordering (most recent first) and names the optional filter and the retraction behavior. While it is distinct from siblings like annotate_metric and retract_annotation, it does not explicitly mention that it is the read counterpart to those, but the purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (reading annotations, filtering by metric, including retracted) but does not explicitly state when to use this tool over other related tools like query_kpis or get_company_health. No exclusions or alternative conditions are given, but the filtering and retraction options hint at specific use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.