list_reasons_by_event

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

No annotations are provided, so the description carries the burden. It explains that profileId selects a lens, but does not disclose whether the operation is read-only (it likely is), whether there are pagination limits, or the order of results. The description adds some context but is insufficient for a full behavioral picture.

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 plus a note, all relevant and front-loaded. Every sentence serves a purpose: the first states the tool's function, the note clarifies profile semantics and provides usage advice. No unnecessary words or redundancy.

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?

With no output schema, the description should explain what the response contains, but it only says 'reason instances.' It does not specify fields, ordering, pagination, or error handling. For a list operation, this is a significant gap. The note about profile is helpful but does not compensate for missing return format information.

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 coverage is 100%, but each parameter's description is minimal: 'Path parameter: eventId' etc. The description adds meaning only for profileId ('a configuration profile (a lens, not a container)'), which compensates slightly. Other parameters receive no additional explanation beyond the schema. Baseline is 3 because schema coverage is high, but richer semantics would be beneficial.

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 'Retrieve all reason instances for which we have deviances for a specific profile, directory and event,' specifying the verb (retrieve), resource (reason instances), and context. It distinguishes from sibling tools like list_reasons (all reasons) and list_reasons_by_checker (by checker) by adding filtering on profile, directory, and event. The note about profile being a lens adds clarity.

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 provides explicit guidance: if the user has not specified a profile, call get_preferred_profile or get_preferences and use preferredProfileId. This tells the agent how to determine the profile parameter. However, it does not explicitly exclude use cases or compare with other list tools for when to use this one specifically.

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