List an organization’s payout certificates

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

Beyond the annotations, the description adds genuinely non-obvious behavior: results are newest first, include amounts/grader/appeal window/due date/overdue, and never expose settlement claims or payment details, which stay on BugSecure. It also discloses the AI triage-access prerequisite. This complements the readOnly/idempotent/openWorld annotations without contradicting them, though it does not discuss error conditions 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.

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

The description is two dense sentences: the first names the resource, scope, prerequisite, ordering, and returned fields; the second draws a clear boundary around what is excluded. There is no filler, and the main verb and object are front-loaded.

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 an output schema present and annotations already covering read-only/idempotent behavior, the description provides the key missing context: scope, prerequisite, ordering, returned fields, and exclusion of payment details. Parameters are fully described in the schema. Minor omissions like explicit pagination mechanics and error behavior are not critical for a filtered list query.

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 baseline is 3. The description only reinforces organizationId as belonging to the signed-in user and does not add meaning for limit, offset, status, or reportId beyond what the schema already states. No parameter semantics are left undocumented, but the description adds little on top of the schema.

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 names a specific verb and resource: list payout certificates an organization the signed-in user belongs to owes researchers. It adds the prerequisite of AI triage access and the returned fields, and the org-scoped wording distinguishes it from user-scoped siblings like list_my_certificates. The final clause also separates it from payment/settlement tooling.

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 gives a clear scope and prerequisite: only organizations the signed-in user belongs to, and only if the organization has enabled AI triage access. It explicitly excludes settlement claims and payment details, telling agents not to use this when payment execution data is needed. It does not name a specific sibling tool as the alternative, so it falls just short of a 5.

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