fossa_set_custom_risk_score

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

The description goes far beyond annotations by disclosing the write requirement, the organization-wide override behavior, the null default state, the error conditions for create/update, and the lack of a read endpoint. This is exactly the kind of behavioral context that annotations alone cannot provide.

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 efficiently structured, starting with the core purpose, then the write requirement, then the organizational impact, and finally parameter-specific guidance. Every sentence contributes valuable information without 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?

Given the tool's complexity (6 parameters, write operation, create/update nuances, no read-back capability), the description is thoroughly complete. It covers usage, error conditions, scope handling, and clarifies the field's meaning. An output schema exists, so return-value details are not needed.

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?

With 0% schema description coverage, the description compensates well by explaining the action semantics, scope_id/scope_type mapping, and score range. However, issue_id and reason are not explicitly described, though they are reasonably self-evident. Overall, it adds significant meaning beyond the raw 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 clearly states the tool's function: setting FOSSA's custom risk score (0-100) on a vulnerability issue within a project or release group. It uses a specific verb and resource, and distinguishes itself from related tools like fossa_delete_custom_risk_score and locally computed risk scoring.

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?

Provides clear context on when to use the tool, including the requirement for FOSSA_ALLOW_WRITES=true, the distinction between create and update actions and their error conditions, and the scope_id semantics for project vs release_group. It indirectly points to alternatives by clarifying this is unrelated to locally computed scores, though it does not explicitly name alternative tools.

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