pbs_notification_endpoint_list

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 correctly declares the tool as READ-ONLY, explains the aggregation logic across types, and notes that items are tagged with their 'type'. It also mentions the config prerequisite. Although it doesn't cover all edge cases, it provides adequate behavioral disclosure 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 two sentences and starts with the key 'READ-ONLY' label. The first sentence is concise, and the second provides additional context. Every sentence adds value, though the structure could be slightly more streamlined given the long second sentence.

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 no annotations and full schema coverage, the description covers the tool's purpose, aggregation behavior, parameter usage, and config requirement. It does not explain the return format, but the presence of an output schema mitigates that. It is complete enough for effective use.

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 100%, so the parameters are already documented. The description adds context for 'ep_type' by listing the possible values (gotify, sendmail, smtp, webhook) and explaining the aggregation behavior when omitted. For 'proximo_target', it mirrors the schema. This adds marginal value beyond the schema, earning a baseline 3.

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 starts with 'READ-ONLY: list PBS notification endpoints with their full type-specific config,' clearly specifying the verb and resource. It explains the aggregation behavior across 4 types or filtering by ep_type, and distinguishes itself from PBS's own /endpoints endpoint, which is a directory index. This differentiates it from sibling tools like pbs_notification_endpoint_get or pbs_notification_endpoint_create.

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 explicitly advises when to use this tool: to get a usable list of endpoints as opposed to PBS's own directory index. It also mentions the requirement for PROXIMO_PBS_* config. While it doesn't state when not to use it explicitly, the context is clear, and it provides sufficient guidance for selection.

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