fossa-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.1
Disambiguation4/5
The tools are organized by resource area and most have clearly distinct purposes, aided by cross-referencing descriptions. However, there are several overlapping report/export tools (e.g., multiple attribution report variants, issue export methods) that could confuse an agent. The sheer number of tools increases the risk of misselection despite good descriptions.
Naming Consistency4/5
Most tools follow a consistent fossa_<verb>_<noun> snake_case pattern, with verbs like get, list, create, update, delete. Deviations include noun-phrase tools like fossa_project_posture and fossa_package_observability, and inconsistent use of 'org' vs 'organization' (e.g., fossa_org_settings vs fossa_create_organization_label). Overall the pattern is predictable but not perfectly uniform.
Tool Count1/5
With 137 tools, this server far exceeds a manageable scope; even for a broad API like FOSSA, the number is overwhelming and violates the 3-15 tool guideline. The extreme count makes navigation and selection difficult for agents.
Completeness4/5
The tool surface is exceptionally broad, covering projects, revisions, issues, release groups, teams, users, OIDC/SAML, Jira, SBOM, audit logs, and more, with CRUD for most resources. Minor gaps exist: some background exports cannot be polled, and user lifecycle management is incomplete (no create/update/delete for regular users). Overall, the domain is well-covered.
Average 4.4/5 across 131 of 137 tools scored. Lowest: 2.5/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 42 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds useful context that this is a composite workflow and 'model-friendly' in output, but it does not disclose deeper behavioral details such as orchestration steps or potential performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact at two sentences, but the second sentence mixes useful context ('composite MCP workflow') with promotional filler ('centerpiece demo tool'). It is not overly long, yet every sentence does not fully earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema and annotations cover some ground, but with zero schema description coverage and a vague depiction of a composite workflow, the description does not sufficiently explain what 'issue posture' includes or how parameters shape the result. It is minimally adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameter. It implies project/revision locators are involved but gives no syntax, semantics, or guidance on top_issue_count, leaving the agent without parameter-level understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific deliverable ('one high-value, model-friendly view of a project revision's current FOSSA issue posture') and labels it as a composite workflow, but 'issue posture' is vague and not clearly distinguished from sibling tools like fossa_get_issue_overview or fossa_export_project_issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives. The description only says it is a 'composite MCP workflow' and 'centerpiece demo tool,' implying a high-level summary but without defining selection criteria or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the read-only nature. The description adds minimal context by specifying 'complete detail for one issue', but does not disclose any additional behavioral traits such as output format or performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, a single sentence, but it is vague and fails to convey essential usage nuances. It is front-loaded but does not earn its place because it omits critical information that could be included without excessive length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's five parameters, two of which are required, and the presence of an output schema, the description is insufficient. It does not explain parameter interdependencies, scope options, or any prerequisites, making it hard for an agent to use correctly without external context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description mentions none of the five parameters. It does not explain the role of issue_id, category, scope_type, project_locator, or revision_locator, leaving the agent without necessary guidance to invoke the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves an issue, with the verb 'Retrieve' and resource 'issue'. The phrase 'complete detail' hints at returning full issue information, distinguishing it from sibling tools like get_issue_overview or get_issue_facets, though not explicitly naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as list_issues or get_issue_overview. It simply states what it does without any context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true and openWorldHint=true, so the safety profile is already declared. The description adds only that it lists 'detected' dependencies, which implies a read operation. It does not disclose pagination, filter behavior, or any caveats, but with annotations present this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that is appropriately sized. It front-loads the core purpose ('List dependencies') and is not verbose, though it could have included a bit more detail without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (21 parameters, many filters) and 0% schema coverage, this description is far too sparse. It does not mention the required revision_locator parameter, the variety of filters, or any guidance on what the response contains (though an output schema exists). It is adequate only as a minimal summary, not as a complete tool explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and with 21 parameters the description must compensate. It merely says 'with filters' without explaining any of the many filter parameters (e.g., licenses, depths, has_issues). The description adds no meaning beyond the schema's field names, which are also mostly self-explanatory but not elaborated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists dependencies for a specific project revision, which is a specific verb+resource+scope. It distinguishes from general project listing tools like fossa_list_projects, but a sibling tool named fossa_list_revision_dependencies_v1 exists whose purpose is not differentiated here.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'with filters useful for licensing/security investigation' implies the tool is appropriate for those contexts, but it provides no explicit guidance on when to use it versus alternatives like fossa_get_dependency or fossa_list_revision_dependencies_v1, nor any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint=true annotation already establishes the safe read-only nature, so the description's added value is limited to 'text-friendly' format. It does not disclose other behavioral aspects like pagination or rate limits, but annotations cover the key safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no wasted words. It efficiently states the tool's core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having rich annotations and a full output schema, the tool is complex (15 parameters) and the description is sparse. The schema provides parameter titles and enums, and the output schema covers returns, but the description lacks usage guidance and parameter explanations, making it only partially complete for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate by explaining any of the 15 parameters. While parameter names like 'format' and 'include_*' are somewhat self-explanatory, the description adds no context about format values, revision_locator syntax, or the meaning of the boolean flags.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a FOSSA attribution/SBOM report for a revision, using a specific verb ('Retrieve') and resource ('attribution/SBOM report'). It distinguishes from siblings like fossa_get_revision_attribution_json by emphasizing 'text-friendly' format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as fossa_get_revision_attribution_json or fossa_get_revision_sbom. It lacks any when/when-not context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although annotations already declare readOnlyHint=true and openWorldHint=true, the description adds useful behavioral context by explaining what the result includes: projects, revisions, branch, and ticket status. This goes beyond the annotation safety flags and informs the agent about the output's informational value without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a clear first sentence stating the action, a one-word read-only note, and a third sentence elaborating on the blast-radius context. Every sentence contributes value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, 2 required, and no schema descriptions, the description is far too sparse. It does not explain the category parameter (licensing, vulnerability, quality) or scope_type (global/project), nor the effect of project_locator and revision_locator. The presence of an output schema reduces the need to describe returns, but parameter semantics remain critically undocumented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must explain parameters to help the agent fill them correctly. It does not mention issue_id, category, scope_type, project_locator, or revision_locator at all. The phrase 'on which branch' hints at revision_locator but never names it. This is a significant gap for a 5-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'List the projects and revisions affected by one issue' with a specific verb and resource. It further distinguishes itself from siblings by calling it the 'blast-radius view of a single CVE or policy conflict', adding precise scope that sets it apart from other issue-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context by explaining this is used to see the blast radius of a single CVE or policy conflict, including which projects carry it on which branch and whether a ticket is filed. It does not explicitly name alternatives or state when not to use it, but the purpose is specific enough to guide selection among the many issue tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates safe read operation, and the description's 'Query' aligns. The description adds useful behavioral context about scope (global vs project revision) and comparison between revisions, but does not disclose pagination or return format. With good annotations, a 3 is suitable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. It front-loads the core action and quickly adds scope and comparison. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex (23 parameters, comparison mode), and while the output schema exists and annotations help, the description is too terse to guide effective use. It doesn't explain how revision scoping or comparison works, when to use project_locator vs revision_locator, or what the response structure entails beyond the schema. More guidance is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only partially compensates. It implicitly covers the required 'category' parameter by listing licensing/vulnerability/quality, and hints at scope_type/project_locator via 'globally or for one project revision.' However, the other 20+ parameters such as severity, sort, status, and filters are unexplained. This is insufficient for a tool with many parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Query' and clearly identifies the resource as licensing, vulnerability, or quality issues. It also specifies the scope (global or one project revision) and the comparison capability, distinguishing it from single-issue tools like fossa_get_issue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: to query issues globally or per project revision, and to compare revisions. However, it does not name alternative tools or provide explicit exclusions, so a 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reiterates 'Read-only.' It goes beyond annotations by explaining the spec defect (both optional params) and the tool's behavior of refusing invalid calls before making a request, which is valuable behavioral context. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear summary and then provides necessary detail. The spec-defect explanation is somewhat lengthy but earns its place by explaining a non-obvious validation behavior. Overall, it is well-organized and no sentences are wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the core one-of constraint and sort format, it omits any mention of pagination parameters (page, page_size) or date-range filters (start_date, end_date) that are part of the schema. Given the schema itself has no descriptions and annotations don't cover these, the tool description is incomplete for practical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explains locator, project_id, and sort in detail, but the remaining five parameters (page, page_size, view, start_date, end_date) are completely undocumented. With 8 parameters total, this is insufficient coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+scope: 'List FOSSA build records for a revision or project, or count them.' It clearly distinguishes this from sibling tools by framing it as the 'why has this revision not analyzed' view, which differentiates it from scan-listing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: to understand why a revision hasn't been analyzed, and explicitly states the 'exactly one of locator or project_id' requirement. However, it does not name alternative tools or provide explicit 'when-not-to-use' guidance, falling 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a read-only operation. The description adds some context by specifying the need for an exact locator, but it does not disclose additional behavioral traits such as response formats, pagination, or any potential side effects. With annotations covering the safety profile, this is adequate but not enriched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the first stating the core purpose and the second giving a specific usage hint. There is no redundant info or filler. It is front-loaded with the essential verb and resource, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (not shown), so return values are presumably covered there. However, the description omits any explanation of the revision_locator parameter and the optional include flags. For a tool with 7 parameters, this brevity is acceptable for the essential flow but leaves the agent to infer parameter semantics from names alone, which is a moderate gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 only explains the dependency_revision_locator by advising to use the exact locator from fossa_list_dependencies. The other required parameter, revision_locator, is not mentioned, and the numerous boolean include_* options are only self-explanatory through their names. This incomplete compensation leaves significant gaps for a 7-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a single dependency's richer detail record for a specific revision. The verb 'Get' is specific, and the resource is well-defined ('richer detail record for one dependency in one revision'). It distinguishes itself from siblings like fossa_list_dependencies, which lists dependencies rather than fetching a single detailed record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage hint: 'Use the exact dependency revision locator returned by fossa_list_dependencies'. This tells the agent to obtain the locator from a specific sibling tool, establishing a prerequisite workflow. However, it does not explicitly state when to choose this tool over alternatives or provide exclusion criteria, so it loses a point for not offering broader guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, so the description adds value beyond that by explaining the overlay semantics—'the overlay can only make enforcement stricter, never looser.' This is useful behavioral context not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and contains no redundant phrasing. Every word contributes to understanding the tool's scope and constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the return values are covered. The description clearly explains what the tool returns and its behavioral guarantees. However, it omits details about the project_locator parameter, which is critical for correct invocation. The tool is relatively simple, but the parameter gap prevents full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one required parameter, project_locator, with 0% schema description coverage. The description does not explain the format or semantics of project_locator, so the agent would have to guess how to construct this identifier. No compensation for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: to show the security policy in force for a project, including the configured base policy and any local overlay. This is specific and distinguishes it from related tools like evaluate_security_policy or enable_security_policy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for read-only viewing via the verb 'show' and the explicit 'Read-only' statement. However, it does not explicitly mention when to prefer this tool over alternatives such as fossa_evaluate_security_policy, nor does it provide exclusions or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, but the description adds valuable context: 'WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.' It also discloses side effects (creates project/revision, assigns policy/team/labels/release group, queues analysis) and explains force_rebuild behavior. This goes beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main action and then delivers supporting detail in a logical order: write requirement, side effects, prerequisite workflow, and limitations. Each sentence contributes meaning without redundancy, though it is a bit dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 19 parameters, no schema parameter descriptions, and no examples of asynchronous behavior, the description provides the key workflow and restrictions but leaves gaps. The output schema covers return value, but many parameters and the exact meaning of 'component' and 'revision' remain implicit. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain required parameters like package_spec or revision. It adds meaning for a few optional parameters (policy, team, labels, release_group, force_rebuild) but 19 parameters remain largely undocumented. Given the low coverage, the description only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description centers on a specific verb+resource: 'Start an asynchronous build of a component that was already uploaded to a signed URL.' It explicitly distinguishes itself from the upload flow by stating 'this tool only starts the build' and referencing fossa_get_component_upload_url as a prerequisite, which differentiates it from the sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete workflow guidance: 'Get the upload URL from fossa_get_component_upload_url first and PUT the file to it; this tool only starts the build.' It also notes an organizational constraint ('Non-premium organizations may only import SBOMs'). It lacks explicit alternatives or when-not-to-use statements, but the workflow context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds meaningful context beyond the readOnlyHint annotation by explaining what an exception is (scope, creator, expiry) and how it keeps issues out of the active set. No contradiction with annotations; the extra detail helps the agent understand the domain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the main purpose. Each sentence adds value: purpose, conceptual explanation, and usage pattern. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the tool has 9 optional parameters with zero schema descriptions. The description omits pagination, filtering, sorting, and project/release-group scoping, leaving significant gaps for an agent to invoke the tool correctly in various scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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. It only clarifies exception_id and category, while 7 other parameters (page, count, search, sort_by, project_id, release_group_id, order_by) remain unexplained except by their names, which is insufficient for a 9-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists organization issue ignore rules or fetches one by id. The verb 'list' and resource 'issue ignore rules' are specific and distinguish it from sibling mutation tools like delete_issue_exceptions or extend_issue_exception.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides usage guidance by noting 'Read-only' and instructing to pass exception_id for a single rule or category to list. It does not explicitly name alternative tools, but the guidance is clear enough for basic selection between list and fetch modes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already in annotations, the description reiterates 'Read-only' and adds meaningful behavioral context: that this endpoint returns aggregate daily counts (active, ignored, remediated) as a trend view, not individual issue details. This adds value beyond the annotations and does not conflict with them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact at three sentences, front-loaded with the main action, and free of fluff. The standalone 'Read-only' sentence is slightly redundant with the annotation but does not significantly detract from conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a clear purpose and differentiates from sibling tools, and the output schema covers return values. However, with 6 optional parameters and zero schema descriptions, the agent lacks essential parameter semantics for constructing a correct request, especially for filters beyond the date range.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description only vaguely references 'over a date range,' which partially covers start/end. However, other parameters (category, team_ids, label_ids, project_id) are not explained at all, and the category enum is not mentioned, leaving the agent without sufficient guidance for filtering beyond the date range.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Retrieve' with a clear resource: 'daily active, ignored, and remediated issue counts over a date range.' It also distinguishes from sibling tools by stating it is 'the trend view behind FOSSA's Issue Overview: how the backlog moved, not what is in it,' which separates it from issue listing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It communicates usage context by explicitly labeling itself as read-only and contrasting the trend view ('how the backlog moved') with a snapshot of issues ('not what is in it'), implying when to use this tool versus alternatives. However, it does not explicitly name any sibling tools or provide exclusion criteria, so it falls 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description's 'Read-only' is redundant. However, it adds behavioral context about grouping by revision and the inclusion of per-revision counts, which is not present in annotations. It does not mention pagination or rate limits, but the added context about the view's shape and purpose is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: first sentence states what the tool does, second confirms read-only, third provides the use-case and sibling comparison. Every sentence adds value, with no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and annotations, the description is too brief for a tool with 20 parameters. It does not explain the required 'category' parameter or any key filtering options, and does not clarify the 'revision' concept or how grouping works. The purpose is clear, but the operational context is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description contains zero parameter information while the schema has 20 parameters and 0% schema description coverage. It does not compensate for the low coverage, leaving the agent to guess the meaning and usage of params like 'scope_type', 'change_status', and 'compare_to_revision' from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('issues grouped by dependency revision'), adds the per-revision counts, and explicitly distinguishes it from fossa_list_issues. It clearly communicates what the tool does and how it differs from its sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('which packages should we upgrade first' view) and names the alternative (fossa_list_issues for per-issue view). This provides clear context and a direct comparison, exceeding minimal guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true and openWorldHint=true, the safety profile is already covered. The description adds meaningful context by specifying 'analyzed' revisions, which implies the return set is limited to those already processed, and it clarifies the revision locator format. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and includes a critical usage note without any wasted words. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 9 parameters and no schema-level descriptions, yet the description only addresses the project_locator. Even with an output schema present, the agent lacks guidance on filtering options (refs_type, source, resolved_only, etc.), making the description insufficient for confident invocation of advanced use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for 9 parameters. The description only hints at project_locator's format ('full revision locator returned by FOSSA'), leaving refs, count, offset, source, minimal, refs_type, resolved_only, and locator_contains completely unexplained. Since the schema itself provides no descriptions, the parameter semantics are largely ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List analyzed revisions, branches, or tags for a project.' It clearly states what the tool returns and distinguishes it from sibling tools like fossa_list_revision_scans, which focus on scans rather than revisions/branches/tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on the required input format ('Use the full revision locator returned by FOSSA, including any `$revision` suffix'), which helps the agent construct the project_locator correctly. However, it does not explicitly state when to prefer this over related tools or when not to use it, so it stops 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.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the idempotentHint=false annotation. It states 'Additive: existing assignments are left alone and duplicates are ignored,' which implies that repeated identical calls would have no additional effect (idempotent). This directly conflicts with the annotation, so transparency scores 1 despite the useful write requirement disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four dense sentences with no fluff. It front-loads the purpose, then covers write safety, behavioral nuance, and key parameter constraints. Everything earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter write operation with an output schema, the description covers purpose, prerequisites (FOSSA_ALLOW_WRITES), side-effect behavior, and the critical parameter constraints. It is complete enough for an agent to invoke correctly, despite the annotation contradiction which is separately flagged.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description compensates effectively. It explains the semantics of package_version vs. apply_to_all_versions, the scope_id omission rule for org scope, and implies label_ids must refer to existing labels. This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Assign one or more existing package labels to a single package.' This distinguishes it from siblings like bulk_assign_package_label and set_package_label_assignments by specifying 'single package' and 'existing labels'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives important usage constraints, such as the exclusivity requirement between package_version and apply_to_all_versions, and the conditional omission of scope_id for org scope. However, it does not explicitly mention alternatives or when-not-to-use scenarios, so it stops 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true), the description discloses crucial consequences: 'The score and its stated reason are both gone; there is no read endpoint to recover them from afterwards.' This irreversibility and lack of recovery endpoint is valuable context that annotations do not provide. Also reinforces that it writes to FOSSA.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no fluff: states the action, the prerequisites, and the consequence. It is front-loaded with the primary purpose and each sentence earns its place. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, prerequisites, and irreversibility, and the presence of an output schema covers return values. However, with three required parameters and zero schema description coverage, the lack of parameter explanations is a notable gap. The description is adequate for understanding the tool's role but not fully complete for invoking it correctly without inferring parameter meanings from names alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage and the tool description provides no parameter-specific guidance. It only mentions 'in one scope' without linking to scope_type or scope_id. The parameter names are self-explanatory to some degree, but the description adds no meaning beyond the schema itself, failing to compensate for the complete lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Remove the custom risk score from a vulnerability issue in one scope', and explains the effect ('so FOSSA ranks it by its standard severity again'). This distinguishes it from sibling tools like fossa_set_custom_risk_score. The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the required environment ('Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true') and implies the use case of reverting to standard severity. It does not explicitly name alternative tools, but the context of removing a custom risk score is clear from the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only, but the description adds valuable behavioral details: the truncation cap (FOSSA_REPORT_MAX_CHARS) and the `contents_truncated` flag on cut files. This goes beyond the basic safety profile and helps the agent interpret results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the core purpose, followed by a parameter tip and a behavioral note. Every sentence adds value without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, a key parameter behavior, and a notable output trait. Output schema exists for return structure, so that is covered. It does not detail how to construct locators, but that may be assumed from context; overall it is sufficient for a read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. It explains the effect of include_contents=False and the truncation flag. However, it leaves project_locator and revision_locator unexplained, relying on naming conventions. Partial compensation only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Return the NOTICE files FOSSA found in a revision's distributed source,' giving a specific verb and resource. It clearly distinguishes this from sibling tools like SBOM or attribution retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a practical usage hint for the include_contents parameter, but it does not explicitly state when to use this tool versus alternatives or when not to use it. The context is implied by the tool's specific purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description repeats 'Read-only' and adds conceptual context about what a report option is. No additional behavioral traits are disclosed, such as pagination, response size limits, or whether it returns all presets at once. The added definition is useful but does not go beyond what annotations already imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences: purpose, read-only note, and definition of a report option. It is front-loaded with the action and resource, contains no filler, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (no parameters, read-only, output schema exists). The description defines the domain concept ('report option') and scope. While it doesn't describe the return format, the output schema presumably covers that. For a low-complexity tool, this is reasonably complete, though it could explicitly mention that it returns the saved presets in a list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so there is nothing to document. The description adds context by stating 'for this organization', which clarifies the implicit scope. With 0 parameters, the baseline is 4, and the description provides some useful context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List the saved report option presets for this organization' — a specific verb ('List') and resource ('report option presets'). It further defines what a report option is (a named bundle of attribution-report switches), which clearly distinguishes this from sibling tools like fossa_save_report_option or fossa_delete_report_option.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for retrieving saved presets, and the read-only annotation reinforces that. However, it does not explicitly state when to prefer this over similar list tools or mention any alternatives/exclusions. For example, it doesn't say 'use this to get all report options before modifying them.' Thus usage guidance is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare destructiveHint=false, yet the description states that a wrong call 'breaks SSO for every user' and can 'hand them the organization,' which is a destructive impact. This is a direct contradiction, so the score is 1 and the contradiction flag is set.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into a concise summary, a high-impact warning section, and a parameter explanation, all in about three short paragraphs. No sentence is wasted; it packs essential risk and semantics without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the absence of return-value details (covered by the output schema), the description addresses prerequisites, irreversible consequences, the lack of a read-back endpoint, and parameter semantics. This is complete for a high-risk write operation, exceeding the minimum needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates fully by explaining each key parameter: entry_point is the IdP SSO URL, cert is the PEM certificate, audience is SP entity ID, role-management fields control authority, and organization_id falls back to FOSSA_ORG_ID. It adds behavioral nuance beyond the schema, such as the fact that the three required fields are always sent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Replace the organization's SAML single sign-on configuration,' a specific verb-resource pair that clearly distinguishes from sibling tools like fossa_delete_saml_settings. The scope is explicit: it replaces, not merges, the configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong contextual guidance, warning that this is a replacement used for organization-wide login and that permissions (FOSSA_ALLOW_WRITES, FOSSA_ALLOW_ADMIN) are required. It advises capturing current settings from the web app because no read API exists, but it does not explicitly name alternatives or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it explicitly warns 'WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.', explains that it creates a background job and emails audit history, and notes it is gated as a POST. This aligns with readOnlyHint:false and adds detail about side effects and prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary purpose. It contains three short paragraphs, but there is minor redundancy between 'WRITES TO FOSSA' and 'gated like any other POST'. Overall, every sentence adds useful context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With six parameters and no schema descriptions, the tool description covers the main behavior and caveats (write gating, email delivery, date format) but omits explanations for the optional filter parameters. Since an output schema exists, not detailing return values is acceptable, but the parameter gap prevents full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It only clarifies date format and requiredness for start_date and end_date. The optional parameters (topics, actions, topic_actions, acting_user_ids) remain unexplained, leaving ambiguity about acceptable values and filtering behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Queue a CSV export of the audit log for a date range') and the delivery method (email link to the calling token's user). It is distinguishable from siblings like fossa_get_audit_logs by the export and email aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when an emailed CSV export of audit logs is needed) and provides necessary context like required date format and premium subscription. However, it does not explicitly mention alternatives such as fossa_get_audit_logs, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations: the Premium subscription requirement with 403 behavior, and why PDF/zip outputs are not requested (they don't survive as text). These details help the agent anticipate errors and understand the tool's limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence states the core purpose, and subsequent sentences add essential context (report content, prerequisite, output limitation). Every sentence earned its place with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations, an output schema, and a clear high-level description, the tool is fairly complete. It explains the report's purpose and prerequisites. The main gap is lack of parameter explanation, but given the self-titled schema properties and defaults, the description suffices for an agent to decide on invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain any of the 10 parameters. It doesn't clarify what project_locator or revision_locator mean, nor the effect of boolean flags like exclude_quick_wins. The description completely fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Return FOSSA's remediation guidance report for a revision' and explains the report content ('ranked fix plan: quick wins, high and low priority work, and outdated dependencies'). This specific verb+resource combination distinguishes it from sibling tools like fossa_get_vulnerability_remediation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool, including a prerequisite ('Requires a Premium subscription with Security enabled') and a when-not-to-use condition ('other organizations get a 403'). It does not explicitly name alternatives, but the context is sufficient for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable context beyond those hints: explains the security significance ('standing grant'), the meaning of requiredClaims, and explicitly states 'No credential is returned.' This enriches the behavioral model without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. The first sentence states the action, followed by two short paragraphs offering security context. Every sentence adds meaningful value with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with an output schema, the description covers the tool's semantics and security implications thoroughly. It does not explain parameter behavior, but that is minor given the clarity of the tool's purpose and the presence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not mention any of the four parameters (prev, user_id, page_size, provider_id). It heavily relies on the reader to infer parameter meanings from names alone, and offers no guidance on filtering or pagination.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'List the OIDC trust relationships configured for this organization,' which is a specific verb+resource+scope statement. It also distinguishes from related siblings like fossa_get_oidc_trust_relationship by using 'list' and clarifying this is a collection-level read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'This is the tool to read when auditing what can authenticate without a password.' This gives clear context, though it does not name alternative tools for other scenarios or provide explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions 'Read-only' (which aligns with annotations) and adds a unique behavioral detail about the locators filter being sent to a POST endpoint when too long. This goes beyond the annotations and provides useful insight into how the tool handles large filters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and each sentence adds value. It avoids redundancy and is well-structured in a short paragraph.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with an output schema and 14 optional parameters, the description covers the key aspects: purpose, when to use, read-only safety, and a notable edge-case behavior. It does not explain all parameters, but the schema's titles and enums help fill gaps. Overall, it is reasonably complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It only explains the sort parameter (licensing, security, quality, scan time, title) and the locators filter behavior. The other 12 parameters (e.g., page, count, types, labels) are not described, leaving the agent to infer from names/titles alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List FOSSA projects visible to the current account,' which is a specific verb+resource combination. It distinguishes itself from siblings like 'get_project' by clearly indicating a list operation for all projects, and it adds 'organization-wide project inventory' for further clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use: 'Use this first when the user names a project informally or asks for an organization-wide project inventory.' This is clear context, though it does not mention alternatives or when not to use it, so it falls 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds behavioral detail beyond that: results are newest-first, and each entry includes licensing, security, and quality policy versions. This helps the agent interpret the returned data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and a second sentence that adds crucial interpretation guidance. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists and annotations cover safety, the description sufficiently explains the purpose and result interpretation. It lacks explicit mention of pagination behavior, but for a simple historical list tool this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explicit explanation of page, page_size, project_locator, or revision_locator beyond what the tool name suggests. For a tool with 4 parameters and zero schema descriptions, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List the policy scans FOSSA has run against a revision, newest first,' which is a specific verb, resource, and ordering. It clearly distinguishes this from sibling tools about dependencies, SBOMs, or issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second paragraph explains a key use case: comparing policy versions to understand whether findings predate policy changes. It offers clear context for when the tool is valuable, though it does not explicitly name alternatives or say when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'Read-only' which aligns with the readOnlyHint annotation, and clarifies that the tool returns counts/summaries, not the issues themselves. This adds behavioral context beyond the annotation, though it does not cover all behavior such as filtering capabilities or output structure. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, front-loaded with the primary action. Every sentence is useful: the purpose, the read-only safety note, and the pointer to the sibling tool. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high parameter count (12) and 0% schema description coverage, the description only covers the core use case of comparing two revisions and status counts. It does not mention the various available filters (severity, CWE, depth, etc.) or explain what the output contains beyond 'count'. While an output schema exists, the description alone is insufficient for full API comprehension.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain any of the 12 parameters. It only implicitly references 'two revisions' which maps to revision_locator and compare_to_revision, but leaves all optional filters (severity, cwes, search, etc.) undocumented. The description does not compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action ('Count how many issues are new, remediated, or unchanged'), names the resource ('issues'), and scopes it ('between two revisions of one project'). It also differentiates this summary tool from the related fossa_list_issues by explicitly directing users to that sibling for actual issue details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use guidance: 'answers what did this build change in one call'. It names the alternative tool (fossa_list_issues with compare_to_revision) and explains when to use that instead, making the choice between siblings explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false). The description adds beyond that by specifying the required environment variable, the structure of `projects` entries, and the consequence of an empty `projects` array. This is useful behavioral context that is not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary purpose, and each subsequent sentence adds critical operational detail (write requirement, project structure, constraint). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and annotations, the description covers the essential operational constraints: write permission, project object shape, and non-empty requirement. It could explicitly state that it creates a new release record, but the purpose statement implies that. Overall sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description needed to explain all parameters. It thoroughly describes `projects` (keys, optional fields, requirement), but `title` and `release_group_id` are only inferable from their schema titles. The description partially compensates but leaves semantic gaps for two of three params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: 'Add a release to an existing FOSSA release group.' This clearly identifies the verb and resource, and distinguishes it from related tools like create_release_group (which creates a group) and update_release_group_release (which modifies an existing release).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it targets an existing release group, requires FOSSA_ALLOW_WRITES=true, and mandates at least one project. It does not explicitly name alternative tools, but the 'existing' phrasing and the prerequisites imply when this tool is appropriate versus creating/updating groups or releases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses critical behavioral traits: the tool is write-gated despite being a GET, the side effect is an outbound email not a FOSSA state change, the response is the queued task rather than the report, and api_version="v1" invokes a legacy path. These details are not inferable from the annotations and are essential for correct invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a tight paragraph with front-loaded purpose. All three supporting sentences add high-value behavioral context (write gate, side effect, response format, legacy path) without extraneous wording. It is appropriately sized for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description nails the core behavior and unusual side-effect/response semantics, which is essential for an agent to avoid misinterpreting the tool. However, with 18 parameters and 0% schema description coverage, the lack of parameter clarification and the absence of explicit alternatives relative to sibling tools leave notable gaps. The output schema mitigates return-value ambiguity, but agent decision-making for parameter selection is under-supported.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only adds meaning for one parameter (api_version). The other 17 parameters, including boolean flags like preview and include_* options, are left entirely to their names/defaults. With such a large parameter surface, the description should compensate by clarifying ambiguous parameters, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: "Email a revision's attribution report to the account behind the API token." This clearly distinguishes it from sibling tools that render, generate, or fetch attribution reports, and the recipient/action is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear contextual usage: it emails an attribution report, requires FOSSA_ALLOW_WRITES=true, and notes the legacy path for api_version="v1". It does not explicitly name alternatives like fossa_render_revision_attribution for downloading, so it lacks explicit when-not-to-use guidance, but the context is sufficient for basic selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already indicating read-only and open-world hints, the description adds significant context: it explicitly states the tool does not apply anything to FOSSA and that a FOSSA-raised vulnerability always blocks and cannot be cleared by a local exception. This goes beyond the annotations and clarifies important behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The first sentence captures the core function, and the second adds essential read-only and exception details. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The presence of an output schema and annotations covers return values and safety, but the description lacks parameter semantics due to 0% schema coverage. The main caveats are given, yet the agent might not know how to properly populate 'count' and 'depths' or interpret the locators, leaving the description incomplete for a tool with four parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not compensate for it. While 'revision_locator' is hinted by the word 'revision', the required 'project_locator' and optional 'count' and 'depths' are not explained. The parameter names are somewhat self-explanatory, but the description offers no addition guidance beyond what the schema's titles provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the tool evaluates every dependency in a revision against the effective security policy and returns an allow/warn/block verdict per package. This is a specific verb+resource that distinguishes it from sibling tools like fossa_get_security_policy (which likely just retrieves policy) or fossa_enable_security_policy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by stating the tool reports what the policy says and does not apply anything to FOSSA, implying it is for read-only evaluation. However, it does not explicitly mention alternatives or exclusions (e.g., 'use X to modify the policy'), so it slightly misses full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description significantly augments the annotations. It explicitly states the write requirement, clarifies that it does not modify issues but creates a background job and delivers a report, and discloses that the server cannot poll the job status. This goes well beyond what annotations (readOnlyHint=false, etc.) provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded. The first sentence states the core action, the second warns about write requirements, and the third explains side effects and return token. Every sentence adds essential information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, side effects, and return token clearly. However, it lacks any explanation of the six optional parameters, which is a significant gap given the schema provides no descriptions and the description offers no hints about their semantic meaning. The output schema exists, so return details are partially covered by the schema, but parameter ambiguity remains a notable shortfall.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 6 parameters with 0% description coverage, and the tool description does not mention or explain any of them. The parameters are entirely opaque; the agent only knows names and types, not their meaning or how they relate to filtering the issues behind Issue Overview counts. Description fails to compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Queue') and a specific resource ('an export of the issues behind the Issue Overview counts'). This clearly distinguishes it from sibling export tools like fossa_export_project_issues or fossa_export_global_issues_csv by tying it to Issue Overview outputs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for exporting issues behind Issue Overview counts, requires FOSSA_ALLOW_WRITES=true, and is a POST-like gated operation. While it doesn't name explicit alternatives or when-not-to-use scenarios, the contextual details (gating, no polling endpoint) give practical guidance on when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses a critical side effect: it sends an email, though it is 'read-only with respect to FOSSA state.' It also transparently states the return value ('background task reference') and the lack of a polling endpoint. This provides valuable behavioral context that annotations alone would not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly written and front-loaded. The first sentence states the core purpose immediately. The second paragraph adds essential caveats (email side effect, return value, no polling, alternative) without bloat. Every sentence serves a distinct purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core behavior (queue, email, read-only, return ref) is completely described, and the existence of an output schema reduces the need to explain return values. However, the 14 filtering parameters are completely unaddressed, leaving a significant gap in understanding how to scope the export. The description hints at equivalence with list_packages but never states that the parameters act as filters, so the tool is not fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 14 optional parameters and schema description coverage of 0%, the description provides no guidance on how to populate or use these filters. No parameter is mentioned, and no reference is made to filtering behavior (e.g., 'parameters behave like fossa_list_packages'). The agent is left to guess the meaning of block_types, fix_types, locators, etc., making this a clear gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action: 'Queue an export of the package index and have FOSSA email the download link.' This clearly identifies the resource (package index), the mechanism (email), and the asynchronous nature. It further distinguishes itself by pointing to fossa_list_packages for inline viewing, avoiding confusion with similar export/list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use fossa_list_packages to see the same rows inline.' This tells the agent when to choose this tool (when an emailed link is acceptable) versus the alternative (when inline results are needed). The note that 'this server has no endpoint to poll it' additionally warns against expecting a follow-up, reinforcing the appropriate usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description enriches the annotations by explicitly stating this is a write operation requiring FOSSA_ALLOW_WRITES=true. It also explains the non-obvious null behavior for expires_after, which is meaningful for understanding the side effect of removing an expiry. The premium subscription requirement is an additional operational constraint not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with three short paragraphs that each add value. It front-loads the main purpose, then covers write requirements, the critical null semantics, and a subscription requirement. No sentence is wasted, and the structure is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with only two parameters and an output schema, the description covers the essential context: the write operation, the required environment variable, the premium tier, and the distinct null behavior. It doesn't describe return values, but the output schema exists and the tool is simple, so the description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With no schema descriptions (0% coverage), the description compensates well for expires_after by clarifying that null removes the expiry and a YYYY-MM-DD date sets one. It also notes the absence of a default because null is meaningful. exception_id is not explicitly described, but it is an integer ID and its purpose is evident from the tool's name and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb and resource: 'Change when an issue exception expires.' It also distinguishes from related sibling tools by explaining the alternative behavior of clearing the expiry entirely. The phrase 'clear the expiry so it never does' uniquely identifies this tool's functionality compared to get/delete exception tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage context (for modifying issue exception expiries) and notes prerequisites like FOSSA_ALLOW_WRITES=true and premium subscription. However, it does not explicitly mention alternatives or when-not-to-use, such as 'delete the exception instead' or 'use for exceptions that need a new expiry rather than deletion.' This leaves some ambiguity for an agent selecting among the many issue exception sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a crucial non-obvious API behavior not covered by the annotations: FOSSA returns 401 instead of 404 for non-existent, hidden, or unauthorized providers, clarifying that 'unauthorized' does not necessarily mean invalid credentials. The read-only statement redundantly echoes the annotation but does not contradict it, and the error behavior is valuable context for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise with no wasted words. The first sentence states the purpose, and the second paragraph delivers essential behavioral context. Every sentence adds value, and the structure is front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool with an output schema and readOnlyHint/openWorldHint annotations, the description covers the essential context: what data is returned, the read-only nature, and a critical error-handling subtlety. No significant gaps remain for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description does not explicitly explain the provider_id parameter or how to obtain it. While the parameter name is self-explanatory, the description's only indirect reference—"Show one OIDC provider"—provides minimal added meaning beyond the schema's type and required flag.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: "Show one OIDC provider" and enumerates the exact data returned (issuer URL, scope, creation time). This distinguishes it from siblings like list_oidc_providers (listing multiple) and create/delete (mutations), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a single OIDC provider's details are needed but does not explicitly contrast with siblings or state when not to use it. There is no mention of alternatives such as list_oidc_providers, so the usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context by explaining the default org-wide behavior, the effect of the two include flags, and the significance of the assignment `id` for unassignment. No contradiction is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the purpose is in the first sentence, followed by read-only status, default behavior, and key parameter effects. Every sentence earns its place with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 optional parameters and an output schema, the description covers the essential selection and invocation needs: what the tool does, when it returns all data, how include flags affect results, and how the response maps to another tool. It lacks pagination/limit details, but the output schema fills structural gaps, making the overall guidance sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. It explicitly explains the two boolean include parameters and implies scope/package filtering, but does not describe the meaning or interaction of scope, scope_id, package_id, and package_version. This is partial compensation, leaving some parameter semantics to the schema defaults and names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb and resource: 'List which package labels are assigned to which packages.' This precisely distinguishes the tool from sibling label tools (e.g., fossa_list_package_labels, fossa_assign_package_labels) by focusing on the assignment relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it is read-only, all filters are optional, and no filters returns all assignments in the organization. It also notes that the returned `id` is used by fossa_unassign_package_labels, implying a usage connection. However, it does not explicitly compare against alternative label-listing tools or name when not to use it, so it misses an explicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the read-only behavior is known. The description adds valuable context: the tool returns organization-wide package usage counts and blocked-version counts, and that filters can answer cross-project vulnerability questions without traversing all projects. This goes beyond mere annotation replication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence gives the core purpose, the second clarifies scope and names an alternative, and the third provides a use case. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully explains when to use the tool and what it returns, and an output schema exists to cover return values. However, the large parameter surface (17 parameters) is barely addressed, with only one illustrative filter, so an agent may not know how to use other filters effectively. It is minimally viable but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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, but it barely does. It only mentions 'filters' generically and gives one example (a CVE filter). None of the 17 parameters (cve, severities, block_types, fetchers, etc.) are individually explained, leaving the agent to infer meaning from parameter names and enums alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List the third-party packages the organization depends on, with how many projects use each one and how many of its versions are blocked.' It uses a specific verb ('List'), identifies the resource ('third-party packages'), and distinguishes itself from the sibling tool fossa_list_dependencies by highlighting it as the organization-wide view.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly differentiates when to use this tool vs. fossa_list_dependencies: 'This is the organization-wide package view, not a per-project dependency list: use fossa_list_dependencies for one revision's tree.' It also provides a concrete use case ('who still ships a package with this CVE'), making adoption straightforward.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description adds value beyond that by disclosing the count cap of 50, search semantics, and the deprecated endpoint exclusion. This is useful behavioral context without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no fluff. The primary purpose is in the first sentence, followed by only high-value behavioral notes. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and annotations, the description covers the essential behavioral nuances: pagination, count cap, search filtering, and the deprecated endpoint. It does not explicitly mention default values, but those are in the input schema. This is reasonably complete for a list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. It does explain 'count' (capped at 50) and 'search' (filters by release title), but does not detail 'page' or 'release_group_id'. Since 'release_group_id' is self-evident from its name and 'page' is standard pagination, this is adequate but not thorough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List the releases in a FOSSA release group, paginated,' using a specific verb and resource. This clearly distinguishes it from sibling tools like fossa_get_release_group_release (singular) and fossa_create_release_group_release, while the mention of pagination sets expectations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states 'Read-only' and notes that 'search filters by release title', giving context for when to use the tool. It also excludes an alternative by mentioning the deprecated unpaginated endpoint that is not exposed, but it does not name an alternative tool or provide explicit when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that PDF is not offered, output is capped at FOSSA_REPORT_MAX_CHARS, and the 'full' variant enables all report options server-side. These details provide meaningful operational context beyond the readOnlyHint and openWorldHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main action followed by essential caveats. Every sentence contributes substantive value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core behavior, variant semantics, output format limitation, output cap, and an alternative tool. Given the complexity of 18 parameters, it does not enumerate every boolean option, but the schema provides clear titles and defaults, making this sufficiently complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description clarifies the semantics of the 'variant' parameter, explaining that 'full' accepts no options here and 'preview' renders inline. However, with 18 parameters and 0% schema description coverage, the description only compensates for a small fraction; the remaining 17 parameters rely on their self-explanatory title/default values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: generate a revision's attribution report and return the rendered document. It also distinguishes the tool from the sibling fossa_get_attribution_report by noting that tool is for plain file download, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names fossa_get_attribution_report as an alternative for plain file download, and explains the three variant behaviors (stream, preview, full). This gives the agent clear guidance on when to use this tool vs alternatives, though it does not mention other related sibling tools like fossa_get_revision_attribution_json.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations. It discloses that the operation is a write, requires a specific environment variable, produces a publicly accessible URL with no login, publishes selected report contents (including potential security-sensitive open vulnerabilities), requires Premium, and that FOSSA returns 202 with a background task. This is rich behavioral context that annotations alone (readOnlyHint=false, openWorldHint=true) do not fully convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. The first sentence states the purpose, followed by a critical warning, a security implication, a prerequisite, and an async behavior note. Every sentence adds value without redundancy, making it appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the most important contextual aspects: write operation, environment requirement, public exposure, subscription requirement, and background task behavior. The output schema exists, so return values need not be detailed. It lacks a full parameter breakdown, but given the self-descriptive parameter names and the high-level mention of content options, this is reasonably complete for a well-annotated complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only mentions high-level content categories ('dependency inventory, licenses, and optionally open vulnerabilities'). It does not clarify the meaning of the many include/exclude flags, the locator parameters, or the recipient_email field. The parameter names are somewhat self-explanatory, but the description does not compensate for the total lack of schema descriptions across 17 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Create a publicly reachable link to a revision's attribution report.' This clearly differentiates it from sibling tools like render, email, or get attribution reports by emphasizing the public URL aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: it writes to FOSSA, requires FOSSA_ALLOW_WRITES=true, and requires a Premium subscription. While it does not explicitly name alternative tools or when-not-to-use conditions, the write-vs-read distinction is implied, giving the agent a solid sense of prerequisites and suitability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description significantly adds to the annotations by specifying environment variable requirements (FOSSA_ALLOW_WRITES=true, FOSSA_ALLOW_DESTRUCTIVE=true), the consequence of removing access for link holders, and the guarantee that only the slug is deleted while project and scan history remain untouched. This goes well beyond the simple destructiveHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four concise sentences, each providing unique and essential information. It is front-loaded with the primary action and includes necessary warnings and side effects without any redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description comprehensively covers the tool's purpose, side effects, prerequisites, and safety guarantees. An output schema exists, so return value details are not needed. A minor gap is the lack of guidance on the project_locator parameter, but overall the description is reasonably complete for a single-parameter destructive tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It does not explain the format or meaning of 'project_locator' beyond implying it refers to a project. The parameter name is somewhat self-explanatory, but no concrete guidance on how to construct or obtain the locator is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'remove' and identifies the exact resource (slug from a project's live attribution report URL). This clearly distinguishes the tool from its sibling 'fossa_generate_project_attribution_slug' which performs the opposite action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the effect ('takes the shared report offline') which indicates when this tool is appropriate. However, it does not explicitly mention alternatives or cases where it should not be used, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint and readOnlyHint annotations, the description adds critical behavior: it writes to FOSSA, requires specific environment variables, affects the whole organization, and does not affect previously generated reports. This gives the agent a clear understanding of side effects and scope, which is exactly what transparency requires.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three brief paragraphs: the action, required environment variables, and side-effect scope. Each sentence adds value with no fluff, and the most important information (what it does) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter) and the existence of an output schema, the description covers the essential context: what it deletes, prerequisites, and side effects. It falls short of a 5 only because it does not explicitly clarify what report_option_id refers to, though the name and context make it reasonably clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter, report_option_id, with no description (0% coverage). The description does not explain this parameter or how to obtain the ID, leaving the agent to infer its meaning from the name alone. Since schema coverage is low and the description does not compensate, this dimension scores low.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete a saved report option preset,' which clearly identifies the action (delete) and the resource (report option preset). This distinguishes it from sibling tools like fossa_save_report_option (create/update) and fossa_list_report_options (read).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the use case obvious: deleting a saved preset. It also provides context about requirements (FOSSA_ALLOW_WRITES and FOSSA_ALLOW_DESTRUCTIVE) and warns about organizational scope. However, it does not explicitly mention alternative tools for listing or saving presets, so it falls 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate write semantics (readOnlyHint=false), but the description adds valuable context: it explicitly says 'WRITES TO FOSSA,' requires FOSSA_ALLOW_WRITES=true, and explains the exact side effect—setting all three components (policy, scanning, status check). This goes beyond annotations by detailing operational prerequisites and the conceptual mechanism.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise with three paragraphs. The first sentence gets straight to the point, the second warns about write requirements, and the third explains the concept and parameter. Every sentence adds value, though the conceptual paragraph could be tightened. Overall well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (write operation, multiple settings, prerequisite), the description covers key aspects: the three components, the write requirement, and a critical parameter caveat. It lacks explicit detail on project_locator format and does not describe failure modes, but the presence of an output schema and annotations fill some gaps. It is sufficiently complete for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides crucial semantics only for security_policy_id (numeric id from URL, no API to list). It indirectly clarifies enable_scanning and enable_status_check via the 'three components' explanation, but project_locator receives no elaboration. While helpful for one critical parameter, the description does not fully compensate for the lack of schema descriptions across all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource pair: 'Assign a FOSSA security policy to a project and turn on the enforcement that blocks packages violating it.' It clearly distinguishes from siblings like fossa_assign_security_policy_to_projects by explicitly noting this tool also enables scanning and status check, not just assignment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear prerequisite: 'Requires FOSSA_ALLOW_WRITES=true.' It also explains that blocking is the combination of three settings and that this tool 'sets all three,' implying when to use it versus alternatives that only handle one component. However, it does not name explicit alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by disclosing that regenerating replaces the existing slug (breaking shared links), requiring FOSSA_ALLOW_WRITES=true, needing a Premium subscription, and returning the slug as a bare JSON string. This adds valuable behavioral context that the annotations do not convey, such as the specific destructive effect and authentication conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using three sentences that each add essential information: main purpose, write requirement and side effect, and response format. It is front-loaded with the primary action and avoids redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no nested objects) and the existence of an output schema, the description covers the key aspects: purpose, side effects, prerequisites, and return value. It is slightly incomplete in not explaining project_locator format, but overall provides enough context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description carries the burden of explaining the only parameter, project_locator. However, the description never mentions project_locator or its expected format (e.g., how to construct the locator). The parameter name is self-referential but does not provide sufficient guidance for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Create or regenerate the slug in the URL of a project's live attribution report') with a clear resource (the slug). This distinguishes it from sibling tools like fossa_create_public_attribution_report, which likely creates the report itself rather than just the slug.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use: it requires FOSSA_ALLOW_WRITES=true and a Premium subscription, and it warns that regenerating breaks previously shared links. It does not explicitly name alternative tools, but it establishes prerequisites and consequences, which is sufficient guidance for a write operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes the safety profile, so the description adds value by disclosing the conditional parameter constraints and the difference between count-based facets and distinct-value facets. This goes beyond the annotation without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with four sentences that front-load the core purpose, then add read-only status, usage direction, and parameter constraints. No fluff or irrelevant details are present, and the structure is logical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 7 parameters and the existence of an output schema, the description covers the main behavior, the key parameter interactions, and the nature of results (counts vs distinct values). It does not explain every parameter, but the essential usage context is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates significantly for `facet`, `category`, and `status`, explaining their interplay (e.g., 'category is required for the license-list, package-managers, and statuses facets and rejected by the others'). However, it remains silent on `team_ids`, `scope_type`, `project_locator`, and `revision_locator`, leaving their semantics potentially ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to summarize the current issue set one dimension at a time with counts or distinct values for specific facets. It enumerates the possible facets and explicitly contrasts with fossa_list_issues, making it easily distinguishable from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: 'Use this before fossa_list_issues to find out what is worth listing.' It further details when the `category` and `status` parameters are applicable or rejected, which constitutes clear when-to-use and when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only.' It adds value by explaining what a saved filter represents (criteria, sort, grouping) and the purpose of reading one, which is not captured in annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence conveys the main purpose, followed by a brief read-only note and an explanatory sentence about saved filters. Every sentence contributes meaning, with no fluff or repetition beyond the harmless 'Read-only' echo.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (two optional parameters) and the presence of an output schema, the description is complete. It explains the core functionality, the read-only nature, and the conceptual meaning of the returned data. No critical details like pagination or error behavior are expected for such a simple lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining the two modes of operation: listing by category or fetching by id. It maps to the 'category' and 'filter_id' parameters semantically, though it doesn't explicitly name them or clarify constraints (e.g., mutual exclusivity). This is adequate but not rich.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool lists saved issue filters for one category or fetches one by id, using specific verbs ('List', 'fetch') and a clear resource ('organization's saved issue filters'). This distinguishes it from sibling tools like fossa_save_issue_filter or fossa_delete_issue_filter, which operate on the same resource but with different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you need to view saved filters or read a team's working set. It does not explicitly name alternatives, but the read-only nature and context ('reading one tells you what a team considers its working set') provide clear situational guidance. An explicit 'use this instead of X' would elevate it to 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The read-only annotation already discloses non-mutating behavior, and the description appropriately restates 'Read-only.' It adds valuable context beyond the annotation by explaining the unusual 401-rather-than-404 error response for missing or unauthorized relationships, which is an important behavioral nuance for agents.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and effectively structured: it states the exact purpose at the start, lists returned attributes in a compact phrase, and then adds a brief read-only note plus a specific error-behavior caveat. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a get-style tool: it identifies the resource, the key fields returned, the read-only nature, and an important error-case nuance. With an output schema present and only one parameter, no further context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter, trust_relationship_id, with no description. The description does not explicitly explain the parameter format or provide examples, relying on the parameter name's self-evidence. Since coverage is 0%, the description should compensate more; however, the single parameter is unambiguous given the tool's purpose, so a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Show' with a clear resource 'one OIDC trust relationship' and enumerates the key data returned (issuer, service account, audiences, claims). It effectively distinguishes this single-get tool from listing (fossa_list_oidc_trust_relationships) and creation (fossa_create_oidc_trust_relationship) siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Show one' clearly indicates this is for retrieving a single trust relationship by its ID, contrasting with list or create operations. However, it does not explicitly state when not to use it or mention alternatives, so it stops 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description adds meaningful behavioral context: Premium subscription required (403 otherwise), response shape not declared in OpenAPI and passed through as-is, and api_version v1 differing only in response shape. This goes beyond the annotations and prepares the agent for potential failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the main purpose, then usage guidance, then constraints. Every sentence adds essential information with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 parameters, no schema descriptions, no declared response shape), the description is incomplete. It covers usage context and premium restriction but leaves the majority of parameters unexplained, and the passthrough response note does not compensate for the lack of parameter semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With a 0% schema description coverage and 13 parameters, the description is expected to compensate but only discusses api_version. It fails to explain the meaning or effect of the many include_* flags, exclude_package_labels, or the required locators. The names are somewhat self-descriptive but not sufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a revision's attribution report as structured JSON, using the specific verb 'Return' and naming the resource. It distinguishes itself from rendered formats by explicitly contrasting with 'rendered formats' and referencing the reasoning vs. human presentation use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use this tool: 'Prefer this over the rendered formats when the answer will be reasoned about rather than handed to a person.' It also mentions the api_version v1 legacy path and the Premium subscription requirement, which helps the agent decide whether to attempt the call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description reinforces this with 'Read-only.' It adds valuable behavioral context beyond annotations by specifying the return format (a map of dependency locator to High, Medium, Low, or Unknown) and the conditional parameter requirements. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: three sentences with the purpose stated first, followed by essential usage details. Every sentence adds value, and there is no redundancy or irrelevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description need not detail return values, yet it still summarizes them. It covers the tool's purpose, the optional dependency locator filter, and the scope-specific parameter requirements. It is complete for an agent to use the tool correctly, though it could have briefly noted that this is specifically for binary dependency confidence as opposed to other dependency-related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden of explaining parameters. It adds meaning for dependency_locator (optional, acts as a filter), revision_locator (required for revision scope), and release_id (required for release scope). It does not define locator formats, but it clarifies the conditional relationships between scope and the other parameters, which the schema does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports how confident FOSSA is that a matched binary component is the dependency it named. This is a specific verb+resource combination that unambiguously identifies the tool's function and distinguishes it from sibling tools like fossa_binary_components or fossa_get_dependency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: pass dependency_locator to query a single dependency instead of all, and explains that revision scope requires revision_locator while release scope requires release_id. It does not mention alternatives or when not to use the tool, but the context is clear enough for an agent to know how to invoke it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false), the description reveals crucial behavioral details: it writes to FOSSA and requires an environment variable, it is additive (doesn't remove existing labels), it has no 'all matching' mode (exactly the listed locators get the label), and it explains the version requirement and how apply_to_all_versions changes the target set. This is far more than annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each carrying essential information without redundancy. It front-loads the action, then covers write-safety, additive/filter semantics, and version handling. Every sentence earns its place; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk-write tool with five parameters and an output schema, the description covers the key operational semantics: side effects, prerequisites, no-filter guarantee, and locator format. It does not describe return values (but an output schema exists) or error conditions, which keeps it from a top score, but it is adequate for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It does clarify the most complex parameters: package_locators must include version (with example) and apply_to_all_versions overrides version matching. However, it leaves scope and scope_id to be inferred from their names and the enum, and label_id is not described. Since compensation is partial, the score is below ideal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Assign one package label to many packages in a single call,' a specific verb and resource that clearly states the tool's function. This distinguishes it from sibling tools like fossa_assign_package_labels (which may assign multiple labels) or fossa_unassign_package_labels, while the 'bulk' nature is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage context by explaining that the operation is additive, requires explicit named locators (no filter mode), and that every target is individually listed. It also mentions the write prerequisite (FOSSA_ALLOW_WRITES=true). However, it does not explicitly compare to alternatives like fossa_set_package_label_assignments or fossa_apply_project_label, so it misses a direct when-to-use-this-vs-that statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive and not read-only, but the description adds crucial context: the environment variable requirements, the organizational ownership constraint, and the fact that deletion affects all users. This goes well beyond the structured annotations and fully discloses the operational impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the primary action, and every sentence contributes essential information. There is no filler or redundant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter), the presence of an output schema, and rich annotations, the description covers all necessary context: prerequisites, ownership constraints, and irreversible impact. It is fully sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has only one parameter (filter_id) but schema description coverage is 0%, so the description must compensate. The description does not explain what filter_id means, how to obtain it, or any constraints on it. The parameter name is somewhat self-explanatory, but the description adds no explicit semantic value, which is a notable gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence, 'Delete a saved issue filter,' uses a specific verb and resource, clearly distinguishing it from sibling tools like get_issue_filters (list) and save_issue_filter (create). The scope and action are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when you need to delete a saved issue filter. It adds important context about authorization (FOSSA_ALLOW_WRITES and FOSSA_ALLOW_DESTRUCTIVE) and ownership scope. However, it does not explicitly mention alternatives or when not to use it, so it falls 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and write operations. The description adds valuable context: stored credentials are deleted, issue tracking is severed, and the id vs name pitfall is highlighted. This goes beyond the annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the core action, and each sentence adds essential information: side effects, prerequisites, and a practical tip. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete tool with an output schema, the description covers side effects, prerequisites, and a common confusion point. It could mention reversibility explicitly, but the annotations and context make this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (0%), but the description clarifies the only parameter (jira_id) by noting it is not the Jira site name and suggesting to list configurations first. This meaningfully compensates for the schema's minimal title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action 'Delete a Jira site configuration', which is a specific verb and resource. It clearly distinguishes from sibling tools like get_jira_configurations and save_jira_configuration by naming the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance that this writes to FOSSA and requires env vars, and advises listing sites first because the id is not the Jira site name. It doesn't explicitly mention alternatives, but the tool name and context make the use case clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructive and read-only annotations, the description adds critical context: writes require FOSSA_ALLOW_WRITES and FOSSA_ALLOW_DESTRUCTIVE environment variables, the operation scopes only to the specified release, and there is no undo. This significantly informs the agent of side effects and prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. Each subsequent sentence adds necessary information (write requirements, scope, irreversibility) without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation, the description covers purpose, required settings, scope of effects, and lack of undo. An output schema exists, so return values need not be described. This is complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameter descriptions (0% coverage), and the description does not explicitly explain release_id and release_group_id. While the parameter names plus the tool name make the roles inferable, the description does not compensate for the schema gap with explicit parameter-level meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: "Delete one release from a FOSSA release group." It clearly distinguishes this from sibling tools like fossa_delete_release_group (which deletes the entire group) and release creation/update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clarifies the precise scope of deletion—"one release"—and states that the release group, other releases, and pinned projects are left alone. This implies the appropriate use case (single release removal) and differentiates it from deleting the whole group, 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations (destructiveHint=true, readOnlyHint=false) by disclosing that the operation writes to FOSSA, requires specific admin/destructive permissions, removes the team from all groups, drops all associations such as member access and project/release group assignments, and is irreversible with no undo. This is comprehensive behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the action ('Delete a FOSSA team'), and every sentence adds value: prerequisites, detailed effects, and irreversibility. No word is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive delete operation, the description is exceptionally complete. It covers purpose, required permissions, side effects, non-destruction of related entities, and lack of undo. Given the output schema exists, return value documentation is unnecessary. The agent has all context needed to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description does not mention the team_id parameter at all. While the tool name and purpose make it inferable that team_id identifies the team to delete, the description fails to compensate for the lack of schema-level documentation as required by the rubric for low-coverage cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete a FOSSA team,' which is a specific verb+resource statement that clearly distinguishes this tool from sibling tools like fossa_create_team, fossa_update_team, and fossa_get_team. The name itself is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the required environment variables (FOSSA_ALLOW_WRITES=true, FOSSA_ALLOW_ADMIN=true, FOSSA_ALLOW_DESTRUCTIVE=true) and describes the full consequences of deleting a team, including removal from groups and dropping associations. This gives clear context for when to use the tool, though it does not explicitly name alternative tools for non-destructive modifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and description confirms 'Read-only'. It adds valuable context beyond annotations: the export is grouped by issue type, CSV is returned as raw text under data.content, and default-branch fallback behavior. This enriches the agent's understanding of what happens during invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the main purpose, and every sentence carries meaningful information. No filler or repetition of schema details. Highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description doesn't need to list return fields. It covers the core behavior (whole-project export), key alternatives, default revision selection, and CSV-specific details. Slight gap: does not explain status or ref_type semantics, but schema enums mitigate this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description compensates somewhat by explaining that omitting revision_id or ref exports the latest revision on the default branch. However, it does not elaborate on project_locator, status, or ref_type, leaving those to schema titles/defaults. The mention of CSV format and data.content adds semantic value not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool exports every issue on a project revision as JSON or CSV, with a specific verb+resource. It also distinguishes from sibling fossa_list_issues, making the scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use fossa_list_issues instead when filtered, paged issues are needed rather than a whole-project report. Also explains default behavior when revision_id or ref are omitted, providing clear context for when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description reinforces this with a clear 'Read-only' statement. It adds valuable behavioral context beyond annotations, such as the fact that failed creation jobs are only reportable by their job_id, and that project_locator is only needed for multi-project issues.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: the first sentence states the core purpose, and the second paragraph provides essential parameter guidance and safety information. Every sentence contributes value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to explain return values. It covers the key behavioral nuances (read-only nature, optional parameter conditions, failure reporting) and is sufficiently complete for a status-checking tool with three parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden of explaining parameters. It effectively explains job_id (for failed creation attempts) and project_locator (only for issues affecting multiple projects). The remaining issue_id is obvious from the name and context, and its role is implied by 'for one issue'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function: showing the state of a fossabot dependency-upgrade PR for a specific issue, including creation progress, analysis progress, and the PR link. The verb 'Show' plus the resource and scope ('for one issue') distinguishes it from sibling tools like list or create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful context on when to use the tool (read-only status check) and explains when the optional parameters project_locator and job_id are relevant. However, it does not explicitly name alternative tools for when not to use this one, stopping just short of a full when/when-not comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, covering the read-only nature. The description adds a meaningful prerequisite: the project_locator must come from another tool, which affects invocation expectations. This is beyond the annotations and provides useful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, front-loaded with the core purpose and followed by an essential usage note. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-project read operation with an output schema and readOnly annotation, the description adequately covers the scenario. It might benefit from noting the optional ref/ref_type parameters for revisions, but they are not central to the tool's primary use. The 'do not guess locator' guidance is a key completeness element.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden. It explains the key parameter project_locator as an exact FOSSA locator not to be guessed, offering significant value. The optional ref and ref_type are not described but are self-explanatory with enums and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get detailed metadata about exactly one FOSSA project' with a specific verb, resource, and scope. It distinguishes itself from siblings like fossa_list_projects by emphasizing 'exactly one' and 'detailed metadata.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides critical usage guidance: use the exact locator from another FOSSA MCP tool and do not guess from a repository name. This implies when to use (when a locator is already obtained) and sets an exclusion (don't use repo name), 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds meaningful behavioral context: the report is 'streamed back rather than queued,' the portal publishing switch is deliberately not exposed, and PDF is unavailable due to text decoding. It also explains the effect of exclude_package_labels, giving the agent important operational knowledge.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. Each sentence earns its place: synchronous generation, read-only nature, streaming behavior, publishing exclusion with an explicit alternative, PDF limitation, and one key parameter explanation. There is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (22 parameters, output schema present, annotations present), the description covers the main decision points: synchronous vs. queued, read-only, publishing excluded, PDF unavailable, and one parameter's filtering semantics. The output schema and readOnlyHint cover return shape and safety, but many parameters remain semantically unexplained, so it is not a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 22 parameters. Only exclude_package_labels is semantically explained ('drops every dependency carrying any of the named package labels'). The remaining parameters—such as format, preview, dependency_info_options, and the many include_* flags—are left to their names/enums without additional meaning, which is insufficient for a low-coverage schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Generate and return an attribution or SBOM report for one release in a FOSSA release group, synchronously.' It clearly scopes the tool to a single release within a release group and distinguishes it from the queued sibling by explicitly naming fossa_queue_release_group_attribution_report for the publish/write path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-not-to-use guidance: publishing is a write, so users should use fossa_queue_release_group_attribution_report instead, and PDF is not offered because the response is decoded as text. It also frames this tool as the synchronous, read-only option, which is clear practical guidance for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavior beyond the readOnlyHint: it discloses the type discriminator on entries, the no-paging exception, and the constraint that all projects of a release group must be on the team first. This is useful, non-obvious context that annotations do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: a clear lead, a 'Read-only' note, and a structured breakdown of the three targets. Every sentence communicates necessary information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values are already covered. The description explains the domain-specific nuances (release group prerequisite, target distinctions, pagination differences) making the tool fully usable. A slight gap is not framing this relative to team update workflows, but that is not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the burden. It fully explains the target enum values and when release_group_id is required. It does not explain team_id, page, or search, but those are self-explanatory and have schema defaults, so the description sufficiently compensates for the most critical parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'List what could still be added to a FOSSA team' — a specific verb+resource+scope. It then enumerates the three target types, making it unmistakable what the tool returns and distinguishing it from siblings like fossa_get_team or fossa_update_team_assignments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly explains when to use each target: users for org members not yet on the team, projects_and_release_groups for all assignable items, and release_group_projects for a specific release group's missing projects. It also notes the no-paging behavior for the latter, which helps an agent choose based on data volume. It does not explicitly name alternative tools, but the guidance is otherwise strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reinforces the readOnlyHint annotation with 'Read-only.' and adds valuable context: 'Returns account ids, usernames, and email addresses — identity, not credentials.' This clarifies the nature of returned data and sets expectations about sensitive information. It also explains the team_id behavior, going beyond the annotation's simple read-only flag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into three short paragraphs: purpose, usage guidance, and return semantics. It is front-loaded with the main action, and every sentence adds meaningful information without redundancy. There is no filler or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and readOnly/openWorld annotations, the description covers the essential operational context: what the tool does, when to use it, a key parameter nuance, and what kind of data is returned. It does not explicitly discuss pagination, but the parameter names (`page_size`, `prev`) make that inferable, so the omission is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explains the role of `team_id` (required for team-level tokens) and implies `provider_id` through the OIDC provider context. However, pagination parameters `prev` and `page_size` are left undocumented, so the description only partially compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states 'List the service accounts that may be named in a new trust relationship for an OIDC provider.' This uses a specific verb (list) and resource (service accounts) with a clear scope ('may be named in a new trust relationship'). It distinguishes the tool from sibling OIDC tools like list_oidc_providers or list_oidc_trust_relationships by focusing on service accounts available for trust relationships.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use this before fossa_create_oidc_trust_relationship to find the user_id to grant.' This gives a precise when-to-use instruction and names the companion tool. It also notes the `team_id` requirement under team-level permissions, providing concrete context for when that parameter matters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces that by saying 'Neither transport changes FOSSA state.' It adds valuable context about the transport behavior and the legacy response shape, which goes beyond the annotations. It does not discuss auth or rate limits, but for a read-only list operation this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences with no redundancy. The first sentence gives the primary purpose; the rest add necessary distinctions and behavior. It is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, its difference from the v2 alternative, and the transport edge case, which is the most non-obvious behavior. Since an output schema exists, the return structure is covered. It doesn't spell out every parameter, but the remaining ones are adequately self-describing, making this complete enough for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explains the purpose of `dependency_locators` and `transport` in context, but other parameters (limit, offset, include_ignored, include_hash_data, include_license_text) are not described. However, those are self-explanatory from their names and the schema provides defaults, so the description adds moderate value but not full compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'List a revision's dependencies in FOSSA's legacy v1 response shape.' It clearly distinguishes this tool from the v2 alternative (fossa_list_dependencies) by naming the exact differences (dependency lock, full license objects, issue targets).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'fossa_list_dependencies is the better default; this exists for the fields the v2 response drops and for filtering by a locator list too long for a query string.' This gives concrete when-to-use and when-not-to-use guidance, and even explains the transport workaround for long locator lists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses rich behavioral details: view-specific row shapes, the exception that every view except paths requires path, the lack of a count view in comparisons, and the exclude semantics of exVendored/exConverted in vendored_match. This goes well beyond what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and well-structured: the first sentence states the core purpose, then paragraphs build from view shapes to comparison mode to filter semantics. Every sentence contributes value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (15 parameters, multiple views, comparison mode), the description covers the central operational decisions and special constraints well. The output schema exists, so return values need not be described. The main shortfall is incomplete guidance on several secondary filters, but the core behavior is sufficiently complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful semantics for view, path, compare_to_revision, change_status, and vendored_match, which are not explained in the schema. However, with 15 parameters and 0% schema description coverage, many parameters remain unexplained—pagination, sort, search, package_ids, snippet_ids, package_labels, and rejection_status get no semantic clarification, leaving a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List the code snippets FOSSA matched in a revision, or roll them up by package or by path.' This clearly identifies the operation and distinguishes it from related tools like fossa_get_snippet or fossa_list_packages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete usage context: it explains the read-only nature, the four view modes, the path requirement for all views except paths, and how to use compare_to_revision with change_status. It does not explicitly name alternative tools or state when not to use this tool, so it stops 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral detail beyond the annotations, such as the write requirement, the ON/OFF switch logic, the deep merge behavior on update, and the note that existing reports are untouched. This complements the sparse annotations (readOnlyHint=false, destructiveHint=false) without contradicting them. Some details like idempotency or response format are not mentioned, but the output schema covers return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and efficiently structured, front-loading the purpose, then the write warning, then the merge semantics. Every sentence earns its place, and the paragraphs are not overly long. The organization makes the distinction between create and update behavior crisp and easy to follow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema, return values need not be explained. The description covers the essential write semantics, switch grouping, merge behavior, and the distinction from report generation. However, it leaves some ambiguity around 'all four groups' (not enumerated) and how updates are triggered (implied via `report_option_id`), which are minor gaps in an otherwise thorough explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero schema description coverage, the description carries the full burden for parameter semantics. It explicitly explains `sections` and `dependency_data` (ON/OFF switches, empty list meaning), and the general rule that omitted groups are not sent. However, it doesn't detail `exclude_package_labels`, `use_hash_and_version_data`, or explicitly state that `report_option_id` triggers an update, though these are partially inferable from names and context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Create a saved report option preset, or update an existing one.' This is a specific verb+resource combination that distinguishes it from siblings like delete_report_option and list_report_options. The additional note 'This changes a preset, not a report' further clarifies its scope and prevents confusion with report generation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool, including the prerequisite 'Requires FOSSA_ALLOW_WRITES=true' and the distinction between create (requires all four groups plus a name) and update (deep merge behavior for omitted groups). However, it does not explicitly mention alternatives or when not to use this tool, leaving the differentiation to the reader to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations: it explains the cascade effect (trust relationships are deleted with the provider), the consequence (workloads lose login ability), and the irreversibility ('Nothing here restores them'). This goes well beyond the destructiveHint annotation by detailing what gets destroyed and why caution is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and each sentence earns its place. It starts with the core action, then lists prerequisites, then explains the cascade and provides a pre-delete step. The structure is logical and easy to scan, with no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive and cascading nature of this operation, the description covers the essentials: the action, prerequisites, consequences, and a recommendation for a pre-delete checklist. It does not explain the return value, but an output schema exists (as indicated), so that is not required. The description is complete enough for an agent to understand the full impact and necessary precautions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only the parameter name and type (integer) with no description. The description implies that provider_id is the identifier of the OIDC provider to delete, and it mentions filtering on `provider_id` in the sibling list tool, giving some context. However, it does not explicitly state how to obtain the provider_id or that it is required, so it only partially compensates for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Delete an OIDC provider and every trust relationship that points at it.' This is a specific verb+resource combination that also distinguishes itself from sibling tools like fossa_delete_oidc_trust_relationship, which only deletes a single relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear contextual usage guidance: it warns about the cascading deletion of trust relationships, lists required environment variables (FOSSA_ALLOW_WRITES, FOSSA_ALLOW_ADMIN, FOSSA_ALLOW_DESTRUCTIVE), and instructs the user to list trust relationships before deleting. It does not explicitly name an alternative tool for deleting just a trust relationship, but the cascade warning makes the scope clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint annotation by explaining that email=true queues the export and emails it, while email=false streams a zip archive that cannot be returned over MCP. It also states the permission requirement, adding valuable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, then provides mode-specific behavior and a permission note. Every sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two optional parameters, an output schema, and readOnly/openWorld annotations, the description covers the essential behavior, permission, and return semantics for both modes. The output schema handles return-value details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions for the two parameters (0% coverage), so the description must compensate. The email parameter is thoroughly explained, but team_ids is not mentioned at all, leaving its purpose and format to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Request the organization-wide issues report as CSV.' This clearly distinguishes it from related tools like fossa_export_project_issues by emphasizing organization-wide scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly explains the email=true and email=false modes, including what the caller receives in each case, and states the required Create permission. It provides strong usage context, though it does not explicitly name alternative tools or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description notes 'Read-only', consistent with readOnlyHint annotation, and explains the effect of the optional project_locator parameter—checking a specific project's repository instead of the whole organization. This adds useful behavioral context beyond the annotations, without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, followed by safety and parameter guidance. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple status tool with one optional parameter, annotations stating read-only, and an output schema present, the description is complete: it covers purpose, parameter behavior, and safety. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly explains the project_locator parameter's purpose and effect, compensating for the schema's lack of description (0% coverage). The schema only defines it as string|null with a default; the description adds meaningful semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports fossabot connection status and remaining analysis credits, using the specific verb 'Report' and naming the resource. It distinguishes from sibling fossabot tools that handle upgrade PRs, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: call without parameters for organization-wide status, or pass project_locator to scope to one project's repository. It does not explicitly name alternative tools, but the guidance is sufficient for an agent to decide when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses a key behavioral trait: credentials, headers, and webhook URLs are replaced by presence flags, and the tool never returns a secret. This adds valuable transparency about what the tool does and doesn't return, which is not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the first states the core function, the second adds critical security behavior. Every word earns its place, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with an output schema, the description fully covers its purpose, safety profile, and security behavior. The presence of an output schema means return values are already documented, so no further detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the empty schema already provides full coverage. The description correctly omits parameter details, and the baseline for 0 params is 4. No additional parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a specific resource ('every Jira site this FOSSA organization is configured to export issues to'), clearly distinguishing it from sibling tools like save/delete Jira configurations. This makes the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this is a read-only list operation, and it advises using the FOSSA web app to read secrets back. It doesn't explicitly name sibling alternatives for modifications, but the read-only nature and scope are clear enough for an agent to know when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description echoes 'Read-only.' It adds valuable behavioral detail by enumerating possible status values (CREATED, ASSIGNED, RUNNING, SUCCEEDED, FAILED) and noting the appearance of a download URL upon success. This goes beyond the annotation's safety indication without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences, front-loaded with the primary purpose in the first sentence. The second sentence packs essential details about the parameter source and expected response statuses without any filler or repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (not shown), the description need not detail return structures. It covers the tool's core behavior: status checking, parameter provenance, possible statuses, and the download URL on success. This is complete for an agent to decide when to use the tool and interpret simple results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only one parameter (task_id) and 0% schema description coverage, the description compensates well by explaining that task_id is the value returned by fossa_queue_release_group_attribution_report. This gives the parameter meaningful context beyond its integer type, telling the agent exactly where to obtain it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Check whether a queued release group attribution report has finished,' which clearly specifies the verb (check), resource (release group attribution report status), and scope. This distinguishes it from sibling tools like fossa_queue_release_group_attribution_report (which queues the report) and fossa_get_release_group_attribution_report (which retrieves the actual report).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states that `task_id` is the value returned by fossa_queue_release_group_attribution_report, making the usage context clear: call this after queuing a report. It implies polling for status but does not explicitly mention when not to use it or suggest alternatives once succeeded, though the notion of a download URL on success hints at a subsequent step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and the description reinforces this with 'Read-only.' It adds context about the meaning of the sections and the two-sided nature of linked_organizations, going beyond the annotations. No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Consists of three concise sentences, front-loaded with the main purpose, followed by essential clarifications. No redundant information; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations provide safety hints, the description sufficiently covers the tool's behavior, including how to use it in conjunction with fossa_share_sbom_revision. No major gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining section options ('share_requests' vs 'linked_organizations') and the project_locator as an optional filter. It does not specify the exact format for project_locator, but the semantic meaning is clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and clearly identifies the resource ('SBOM revisions shared with others' or 'linked organizations'). It distinguishes from sibling tools like fossa_share_sbom_revision by focusing on listing sharing details rather than performing the share action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains the two sections and that project_locator optionally filters share_requests. It further states that the sharedOrganizationId from linked_organizations is required by fossa_share_sbom_revision, implying usage before sharing. However, it does not explicitly state when not to use this tool or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the readOnlyHint annotation, including the FOSSA_REPORT_MAX_CHARS cap and the truncated JSON fallback behavior. It also clarifies that include_match_details requires path. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, front-loaded with the primary purpose, and every sentence adds important detail (including the truncation behavior). It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's main return values, optional parameter behavior, and an important edge case (truncation). Given the output schema exists and the tool is read-only, this is a complete and self-sufficient description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It thoroughly explains the optional path and include_match_details parameters and their relationship, but does not clarify the required project_locator, revision_locator, and snippet_id beyond their names. This partial compensation warrants a mid-range score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows a single matched snippet with specific details (upstream package, licenses, issue counts, file paths), distinguishing it from the sibling fossa_list_snippets which would list snippets. The verb 'Show' and specific resource make the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use this tool—when you need details for a specific snippet—and gives clear guidance on optional parameters (path, include_match_details). It does not explicitly name alternative tools or exclusion criteria, so it stops short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces it with "Read-only." Beyond that, it discloses request-count implications per section, parameter scoping across list sections, and sort restriction. This adds useful context about operational behavior and cost without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three focused paragraphs: first states purpose, second explains sections and cost, third clarifies parameter relationships. No filler or redundant repetition of schema defaults. Every sentence adds value and is front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, 4 sections, output schema present), the description covers the key aspects: what each section returns, defaults, request cost, and shared parameter behavior. It does not describe output fields, but the output schema exists to provide that. The only minor gap is explicit alternative-tool comparison, but this is not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description is the sole source of parameter meaning. It explicitly explains `page`, `page_size`, `search`, `sort`, `sections`, and indirectly `team_id` ("numeric id"). It also explains shared application of pagination/search and the sort rejection condition, which is critical for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb-resource pair: "Get a FOSSA team by its numeric id, and any of its member, project, and release group listings." This clearly differentiates it from sibling tools like fossa_list_teams or fossa_get_team_groups by focusing on retrieving a single team with optional nested listings. The section breakdown further clarifies scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear usage context: "Read-only," default behavior ("Defaults to 'team' alone"), and cost guidance ("Each section costs one FOSSA request, so ask only for what is needed"). It also warns about the `sort` parameter being rejected when neither 'projects' nor 'release_groups' is requested. However, it does not explicitly name alternative tools for comparison, though the purpose is self-evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, and the description reinforces the read-only aspect. It adds valuable context beyond annotations: the return fields ('usage', 'max', 'unlimited'), the default behavior ('Defaults to both'), and the failure scenario when creating a release group at the limit. No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the core purpose, the second covers safety, requirements, return shape, and use case. Every phrase earns its place with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-optional-parameter read tool with readOnly/openWorld hints and an output schema, the description fully covers what the agent needs: the operation, the parameter meaning, the return payload shape, and a concrete use case. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description compensates by explicitly naming the parameter values ('contributors and release groups') and explaining that the null default means both. This adds meaning beyond the bare enum in the schema, though it doesn't spell out array behavior in detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Read a FOSSA organization's plan limits and current usage for contributors and release groups.' This clearly distinguishes the tool from the many sibling creation/update tools, especially by framing it as a pre-check for release group creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context on when to use: 'Useful before creating a release group, which fails once the organization is at its limit.' It also notes the read-only nature and the requirement for FOSSA_ORG_ID. However, it does not mention alternative tools or when-not-to-use scenarios, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Read-only,' which aligns with the readOnlyHint annotation. It adds meaningful behavioral nuance beyond annotations by noting that `view="paths"` returns a directory tree one level at a time and is the only view accepting `path` and `search`. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each carrying distinct information: the core action, the read-only note and scope parameter, and the view parameter behavior. It is front-loaded with the main purpose, avoids repetition, and has no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, multiple modes, output schema available), the description covers parameter dependencies, view semantics, and an important restriction (path/search only with paths view). The output schema is present, so return values need no further explanation. It is self-sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining all 7 parameters. It maps `scope` values to required parameters (revision_locator vs. release_group_id/release_id), clarifies `view` options (count vs. paths), and indicates that `path` and `search` are only valid with `view="paths"`. This is comprehensive given the schema's silence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Count the binary decomposition components found in a revision or a release group release, or list them grouped by the file path they were found at.' It clearly distinguishes the two primary operations (count vs. list paths) and the target resources (revision or release).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit context for when to use the tool and how to choose parameters: 'scope selects what is being asked about' and describes the required locators for each scope. It also explains which view accepts `path` and `search`. However, it does not explicitly compare to sibling tools or state when an alternative would be preferable, so it falls 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite readOnlyHint and openWorldHint annotations, the description adds substantial behavioral context: it is read-only (redundant but reinforcing), describes what each view returns (strings with hit counts, component files), and discloses the page_size cap of 50. This goes well beyond the annotation metadata and provides actionable knowledge for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the tool's core purpose and then detailing the two modes. Every sentence contributes value, with no repetition or filler. It is well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema is present (so return values are documented elsewhere), the description covers the key contextual aspects: the two available views, their required parameters, and pagination restrictions. It could be more complete by explaining the revision_locator parameter and explicitly stating that only one of component_id/dependency_locator should be provided depending on view, but overall it is sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It explains the role of view ('component_matches' vs 'dependency_components'), the required parameter for each (component_id, dependency_locator), and the page_size cap. However, it does not clarify revision_locator, page, or the interplay between them, leaving some parameters still ambiguous to a new agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Drill into one binary decomposition revision' and distinguishes the two sub-modes ('component_matches' vs 'dependency_components'). It uses a specific verb ('drill into') and identifies the resource ('binary decomposition revision'), setting it apart from sibling tools like fossa_binary_components or fossa_binary_dependency_confidence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use each view: component_matches needs component_id and returns match strings; dependency_components needs dependency_locator and returns component files. It also notes pagination constraints. However, it does not explicitly contrast with alternative tools or state when not to use this tool, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, but the description adds the FOSSA_ALLOW_WRITES=true requirement and explains the behavioral constraint that vulnerability issues cannot be disputed. This goes beyond the structured annotations and provides useful operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose sentence, followed by the write requirement and a concise but complete breakdown of reason constraints. Every sentence earns its place with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the description covers the action, prerequisite (FOSSA_ALLOW_WRITES), reason categorization, and the vulnerability exclusion. Since an output schema exists, omitting return-value details is acceptable. Minor gap: no explanation of the 'comment' parameter, but it is low-risk and self-evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has an enum for 'reason' but no descriptions. The description adds semantic meaning by grouping the enum values into licensing vs quality categories and explicitly excluding vulnerability issues. Other parameters (issue_id, comment) are self-explanatory, so this covers the key parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Dispute') and resource ('licensing or quality issue'), and it immediately clarifies that it tells FOSSA the finding is wrong. This distinguishes it from the many sibling tools, as there is no other dispute-specific tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-not guidance ('Vulnerability issues cannot be disputed') and implicitly when-to-use by explaining that it is for incorrect licensing or quality findings. It also states that the reason must match the issue's category, which helps the agent select the correct usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond annotations by stating 'WRITES TO FOSSA' and requiring specific admin flags. It details a major security implication: 'whoever can call this can choose which issuer FOSSA will believe' and warns about unauthenticated deployments. This provides behavioral context about side effects and authorization beyond what readOnlyHint/idempotentHint/destructiveHint convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately sized but each sentence adds value. It leads with the core purpose, then requirements, then security context, then parameter guidance. It is structured with line breaks for readability. It could be slightly tighter by merging some context, but no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating admin operation with 3 parameters and an output schema, the description covers purpose, prerequisites, security implications, and parameter semantics. It does not discuss idempotency (annotation says false) or potential errors, but the presence of an output schema likely covers return values. Overall, it is nearly complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full burden. It defines issuer precisely: 'must be the issuer URL exactly as the provider mints it in the `iss` claim'. It explains scope/scope_id relationship: 'Use scope="team" with scope_id set to a team id... org scope takes no scope_id'. These are crucial semantic details not present in the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Register an OIDC identity provider that this FOSSA organization will trust' with the verb 'Register' and resource 'OIDC identity provider'. It distinguishes from sibling tools like get_oidc_provider and list_oidc_providers by focusing on creation, and from create_oidc_trust_relationship by explicitly noting this is the first half of a password-less login path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear usage context: this is for registering a provider, and it explicitly notes 'Adding a provider does not by itself let anyone in — a trust relationship does that', implying the alternative tool create_oidc_trust_relationship. It also mentions required environment variables (FOSSA_ALLOW_WRITES=true, FOSSA_ALLOW_ADMIN=true) as preconditions. However, it does not explicitly name a sibling tool or enumerate all when-not scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses the FOSSA_ALLOW_WRITES=true requirement and the failure condition at release group limits. It also clarifies that the first release is bundled with group creation, adding meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with each sentence earning its place. It front-loads the primary action and then provides essential constraints and parameter details without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 params, write operation), the description covers key behavior, constraints, and the most complex parameter. Output schema exists, so return values are handled. It could be more complete on parameter specifics, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining the `projects` parameter structure (projectId, branch, revisionId) with an example. Other parameters are left to schema, but their names are self-explanatory, making this adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a FOSSA release group together with its first release, using a specific verb and resource. This distinguishes it from related tools like fossa_create_release_group_release, which creates subsequent releases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains that FOSSA has no empty release group, so the first release must be created in the same call, providing clear context for when this tool is appropriate. It does not explicitly name alternatives, but the rationale is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations: it explicitly warns 'WRITES TO FOSSA' and lists required environment variables, which aligns with readOnlyHint=false. It also discloses side effects of auto_add_users (automatic user additions) and unique_identifier's role in SCIM/SSO mapping. This is valuable contextual information that the annotations alone do not provide. The description does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently organized: a one-sentence purpose statement, a clear write-safety warning, and parameter details in a compact paragraph. Every sentence adds value – no filler, no repetition of schema structure. It is appropriately sized for a tool with five parameters and non-trivial side effects.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 params, write operation, side effects, dependency on external features), the description covers all critical aspects: purpose, required environment, parameter semantics, feature prerequisites, and cross-references to related tools. The presence of an output schema means return-value documentation is unnecessary. No significant gaps remain for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite the schema having 0% description coverage, the description thoroughly explains all parameters: default_role_id (with cross-reference to fossa_list_roles), auto_add_users (including its default and access implications), unique_identifier (SCIM/SSO external key), and team_group_ids (requires feature). This goes well beyond the bare schema definitions and gives the agent actionable guidance for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a FOSSA team' – a specific verb+resource statement that clearly distinguishes this from sibling tools like fossa_list_teams, fossa_get_team, fossa_update_team, and fossa_delete_team. The tool's name and title align, and the description leaves no ambiguity about its core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is a write operation requiring FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_ADMIN=true. It also explains the implications of parameters like auto_add_users ('widens access without another call') and team_group_ids ('requires the team groups feature to be enabled'). However, it does not explicitly state when to use this tool over alternatives (e.g., fossa_update_team for modifications), though the name and sibling context make this implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already marking destructiveHint and idempotentHint, the description adds crucial behavioral context: the label is removed from every project carrying it, the change is permanent, and environment variable requirements (FOSSA_ALLOW_WRITES, FOSSA_ALLOW_DESTRUCTIVE) are disclosed. This goes beyond annotations to convey the breadth of impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is five sentences, front-loaded with the primary action, then provides necessary warnings and constraints. Every sentence adds value, with no repetition of schema or annotation information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers prerequisites (env vars), side effects (removed from every project), pre-check recommendation (list labels), plan restrictions (premium), and scope (projects only lose the tag). An output schema exists, so return values need not be described. This is comprehensive for a simple destructive tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for label_id is 0%, and the description does not compensate. It only refers to 'this id' without explaining what label_id is, where to find it, or its format. The parameter name is self-explanatory, but the description provides no additional semantic value beyond the schema's basic type and name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Permanently delete an organization label.' The verb 'delete' and resource 'organization label' are specific, and it distinguishes itself from sibling tools like fossa_create_organization_label and fossa_list_organization_labels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit pre-usage guidance: 'Check fossa_list_organization_labels with this id first' to see affected projects, which serves as a safety check. It also notes the premium plan restriction and clarifies that projects are not otherwise affected, preventing misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true), the description discloses that environment variables FOSSA_ALLOW_WRITES and FOSSA_ALLOW_DESTRUCTIVE must be set, and explains that deletion removes the label everywhere it is assigned across all packages, projects, and revisions. This adds important non-obvious behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct, front-loaded with the core action, and uses two additional sentences for prerequisites and critical warnings. Every sentence adds value without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation. The description covers prerequisites, the destructive scope, and an alternative, making it complete for a complex mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only lists 'label_ids' with no description, and the description does not explain the parameter beyond implying that these IDs refer to the label definitions to delete. Since schema coverage is 0%, the description should compensate, but it remains implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Permanently delete one or more package label definitions' with a specific verb and resource. It distinguishes itself from the sibling tool by mentioning the alternative for removing a label without destroying it, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use fossa_unassign_package_labels instead when the goal is to remove a label from a single package without destroying the definition. It also warns about the large blast radius, giving clear context on when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is a write operation (readOnlyHint=false) and not idempotent, and the description reinforces this with 'WRITES TO FOSSA.' It goes beyond annotations by disclosing that the minted token is deliberately not returned, the response contains identity and metadata instead, the token remains valid for 15 minutes to 12 hours, and specific error conditions all return 400. This provides rich behavioral context beyond what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold headings, clear paragraphs, and front-loaded purpose. It is longer than strictly necessary, especially the security rationale about the token not being returned, but that content is valuable for transparency and safety. Every sentence contributes to understanding the tool's behavior, so it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, security-sensitive tool, the description is remarkably complete. It covers the operation, prerequisites, return value semantics, error handling, and even the alternative API call. The output schema exists, which likely documents the response structure, so the description does not need to repeat that. The only minor gap is full parameter semantics, but overall completeness is high.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. It explains `token` (JWT from identity provider) and `username` (FOSSA service account), but does not describe `provider_id`, `expires_in`, or `is_push_only`. Since `provider_id` is a required parameter, the lack of explanation for it is a meaningful gap, though the tool's purpose and the mention of 'unknown provider' errors partially infer its role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to check whether an OIDC trust relationship works by performing the token exchange a CI job would perform. It explicitly distinguishes from sibling tools by saying 'use this to answer "is my trust relationship configured correctly?", not to obtain a token.' This is a specific verb+resource combination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use this tool versus when not to. It states to use it for verification, not for obtaining a token, and directs CI jobs needing the real token to call `POST /oidc/token-exchange` directly. It also notes required environment variables (FOSSA_ALLOW_WRITES, FOSSA_ALLOW_ADMIN), providing clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the readOnlyHint and openWorldHint annotations. It discloses detailed behavioral traits: sections are independent, responses are split into 'data' and 'errors' keys, empty results vs failures are distinguished, and the specific 404 for 'last_published' is explained. This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear paragraphs and front-loaded purpose. While longer than typical, every sentence provides useful information about behavior, error handling, or usage. It is not padded, though it could be slightly more succinct without losing critical detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is remarkably complete for a tool with two parameters and an output schema. It explains the response structure, the distinction between empty and failed sections, and the meaning of the 404 error. Given the complexity and absence of schema descriptions, the description fills all necessary gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description compensates strongly for the 'sections' parameter by explaining each enum value and their effects. However, it does not elaborate on the format or semantics of 'project_locator', leaving a gap for that parameter. Overall, it adds substantial meaning beyond the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: "List a project's labels, its release-group memberships, and the timestamp of the last update published for it." This uses a specific verb (list) and resource (project associations), distinguishing it from sibling tools like fossa_get_project or fossa_list_projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on how to use the tool, including how to request the optional 'last_published' section and how to interpret errors. It explains the default behavior and the special 404 case, giving practical guidance. It does not explicitly name alternatives, but the usage context is well established.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the readOnlyHint and openWorldHint annotations by explaining the meaning of release_group_id (the integer in the FOSSA URL) and defining the three sections and the default behavior. It is consistent with the annotations and provides useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the main purpose, and then covers parameter details and defaults in a structured way. Every sentence contributes meaningful information, with no unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only retrieval tool with an output schema, this description is complete: it covers the resource, optional selections, parameter semantics, and default behavior. The presence of an output schema means it doesn't need to describe return values in detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are explained in the description: release_group_id is the integer in the release group's FOSSA URL, and sections enumerates the possible values with their meanings. Since the schema has no descriptions, this fully compensates and gives the agent clear guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a FOSSA release group by its numeric id' and specifies that it can optionally include teams and projects. This distinguishes it from sibling tools like fossa_get_release_group_release or fossa_list_release_group_releases because it focuses on fetching the group record itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for what the tool returns and explains the optional sections ('group', 'teams', 'projects'). However, it does not explicitly mention when not to use this tool or point to alternative tools, such as fossa_get_release_group_release when only a single release is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'Read-only,' reinforcing the readOnlyHint annotation. It adds valuable behavioral details beyond the annotations: count is capped at 50, package_locator is a partial match, and the index cache timing is disclosed. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with the core purpose in the first sentence. The second sentence adds necessary parameter nuances without fluff. Every sentence earns its place; no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description covers the essential context: read-only nature, section-specific argument behavior, and search semantics. With 3 optional parameters and an output schema, the description is sufficient for an agent to invoke the tool correctly. It leaves no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining all three parameters: section (enum values and defaults), package_locator (partial match, only in locators section), and count (only in locators, capped at 50). It also clarifies which sections require no arguments. This is excellent parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Read the package index's own metadata' and then details the exact outputs (total package count, cache time, package managers, locator search). This clearly distinguishes it from sibling tools like fossa_list_packages or fossa_export_package_index by focusing on the index's own metadata rather than package data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear parameter-scoping guidance ('summary' and 'package_managers' take no arguments; package_locator and count apply only to 'locators'), which helps with usage. However, it does not explicitly state when to choose this tool over alternatives, such as fossa_list_packages or fossa_export_package_index. The guidance is implied but not explicit about tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false), the description adds significant behavioral context: it explicitly states 'WRITES TO FOSSA' and the environment variable requirement, explains the side effects of creating a job and making the report visible when is_publishing is set, and notes it returns a task id to poll. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it front-loads the core purpose, then warns about write requirements and side effects, and ends with a direct comparison to the read-only alternative. Every sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (17 parameters, mutation, background job, output schema present), the description is remarkably complete. It covers the async nature, the side effects, the gating condition, and the polling mechanism. With an output schema available, return value details are not needed, and the description covers all critical operational aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for parameter meaning, but it only discusses the is_publishing parameter's effect. The 17 parameters, including dependency_info_options and various include_* flags, are left to their self-explanatory names and schema titles. This provides minimal added value over the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queues an attribution or SBOM report for a release group as a background job, with an optional publish action. It uses a specific verb ('Queue') and identifies the resource ('attribution or SBOM report for one release in a FOSSA release group'), and distinguishes itself by explicitly contrasting with fossa_get_release_group_attribution_report for read-only needs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: when you want to queue a background job and optionally publish to the SBOM portal. It also gives a clear alternative for read-only scenarios: 'For a report you just want to read, fossa_get_release_group_attribution_report returns the content directly and writes nothing.' This directly addresses usage vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description adds critical behavioral details: requires FOSSA_ALLOW_WRITES=true, opens a real PR, is asynchronous with a `creating` response, returns existing state for duplicate requests, and consumes fossabot credits for retry_analysis.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by warnings and parameter details in three concise paragraphs. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of annotations, the description covers async behavior, real-world side effects, idempotency behavior, and resource consumption. However, it omits explanation of `project_locator`, which is a minor completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. It thoroughly explains `fix` and `retry_analysis`, but doesn't mention `project_locator` at all and only implicitly references `issue_id`. This leaves a gap for the remaining parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: asking fossabot to open a dependency-upgrade pull request or re-run analysis on an existing PR. This distinguishes it from sibling tools like fossa_get_fossabot_upgrade_pr (which tracks) and fossa_list_fossabot_upgrade_prs (which lists).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly points to fossa_get_fossabot_upgrade_pr as the tracking alternative and explains when to set retry_analysis=True instead. This gives clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond annotations. It explains the required environment flags (FOSSA_ALLOW_WRITES, FOSSA_ALLOW_DESTRUCTIVE), the filter-vs-list semantics, the dangerous path='/' behavior, and how rejected=False reverses the action. This adds critical context for a destructive operation that annotations only hint at.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact paragraph that front-loads the purpose, then flows naturally into safety requirements and filter semantics. Every sentence earns its place; there is no fluff or repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a dangerous, filter-based tool with 10 parameters, the description covers the core semantics, safety tiers, and reversal behavior. It leaves some parameters unexplained, but the output schema covers return values, and the description's warnings about destructive behavior are sufficient for an agent to avoid catastrophic misuse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates by explaining the key filter parameters: path ('path="/" with nothing else rejects every snippet match'), snippet_ids/package_ids ('naming ids keeps the target set visible'), and rejected ('Set rejected=False to reverse'). It does not explain all 10 params (e.g., search, package_labels, vendored_match), but the most important ones are covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Reject snippet matches so FOSSA stops counting them, or unreject ones that were rejected before.' It clearly distinguishes the tool's mutation purpose from sibling snippet tools like fossa_list_snippets and fossa_get_snippet by focusing on changing rejection state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear when-to-use context: 'Rejecting is how a false-positive snippet match is dismissed, and it suppresses the licensing issues that match raised.' It also gives practical guidance on narrowing the filter (naming ids vs. using path='/') and requires the destructive tier for unnarrowed calls. It doesn't explicitly name alternatives, but this is a unique operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Disclosures go well beyond the annotations: it warns about write requirements (FOSSA_ALLOW_WRITES, FOSSA_ALLOW_ADMIN), explains replacement semantics (lists replace rather than merge), warns that omissions widen authentication, and notes sub wildcard validation. This gives the agent actionable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, moving from purpose to prerequisites to behavioral specifics. Every sentence contributes meaningful information, with no redundant fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers prerequisites, update limitations, replacement semantics, and a validation rule, and the output schema handles return-value details. A minor gap is the ambiguous behavior when passing null vs. omitting the list parameters, which is not clarified for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining that audiences and required_claims are the updatable fields and that each list replaces the stored list. It also adds validation detail about sub wildcards. However, it leaves trust_relationship_id and the internal structure of required_claims objects mostly implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Change which tokens an existing OIDC trust relationship accepts." It clearly distinguishes this from sibling create/get/delete tools by emphasizing "existing" and scoping updates to audiences and required_claims.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool (to update an existing OIDC trust relationship) and provides clear limitations: only audiences and required_claims can be updated, user/provider are fixed at creation. It does not explicitly name alternative tools like create_oidc_trust_relationship, so it stops 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by disclosing the FOSSA_ALLOW_WRITES=true requirement, the write side effect, and the failures map in the response. These details are not present in the annotations, which only indicate readOnly=false, destructive=false, idempotent=true, and openWorld=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences long, front-loaded with the purpose, and every sentence adds unique value: the write warning, label prerequisite, explicit naming requirement, and failure reporting. There is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low parameter count, existing annotations, and presence of an output schema, the description covers all essential aspects: the action, the write requirement, the limitation on label creation, the explicit project naming, and the failure reporting. It is sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining label_id is a numeric id of an existing label and project_locators are explicit project names. It could provide more detail on the exact locator format, but the key semantics are conveyed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Apply one existing organization label to a list of projects.' It distinguishes itself from related operations by explicitly noting it does not create labels and that the filter-based bulk assignment mode is not exposed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: the label must already exist, projects must be explicitly named, and the tool is a write operation requiring FOSSA_ALLOW_WRITES=true. It does not explicitly name alternative tools, but the exclusions (no label creation, no filter mode) help an agent decide when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false), the description discloses the write requirement (FOSSA_ALLOW_WRITES=true), the unattached creation behavior, premium plan restriction, and that the response contains the new numeric id. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each with distinct value: purpose, write requirement, workflow context, and plan restriction/response. Front-loaded with the main action; no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with one parameter, the description covers all necessary aspects: what it does, how it fits with related tools, prerequisites (write flag), limitations (premium plans), and response content. The output schema existence further reduces the need to explain return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. It provides context that the label is an 'organization label for tagging projects,' but it does not specify allowed formats, uniqueness, or other constraints for the 'label' string parameter. Minimal added meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new organization label for tagging projects,' using a specific verb and resource. It distinguishes itself from sibling tools like fossa_apply_project_label and fossa_create_package_labels by specifying 'organization label' and noting that it creates an unattached label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the label is created unattached and that fossa_apply_project_label puts it on projects, providing a clear workflow. It also mentions the premium plan restriction (403) and the FOSSA_ALLOW_WRITES=true requirement, giving conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true and readOnlyHint=false, but the description adds substantial detail: what is destroyed ('revisions, issues, and scan history'), the required environment variables, and the irreversibility warning. This goes far beyond annotations and fully discloses behavioral consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary action. Every sentence provides essential information: purpose, prerequisites, and consequence/caveat. No wasted words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, required environment variables, destructive effects, irreversibility, and a specific safety caveat about locator accuracy. With an output schema present, return values need not be described. This is complete for a destructive single-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With one parameter and 0% schema description coverage, the description must explain the parameter. It does so by clarifying that project_locator must be exact and that a locator guessed from a repository name may refer to a different project, advising to confirm with fossa_get_project. This adds valuable meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Permanently delete one project and everything FOSSA has scanned for it' with a specific verb, resource, and scope (one project). This clearly distinguishes it from sibling tools like fossa_delete_projects (plural) and fossa_delete_project_attribution_slug.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context: requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true, warns about irreversibility, and advises confirming the exact locator with fossa_get_project. It does not explicitly name alternatives like fossa_delete_projects, but the one-project scope and locator guidance are sufficient for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds critical behavioral details: deletion is permanent and cannot be undone, it writes to FOSSA, and it explicitly excludes the dangerous `locators=all` mode. These are value-added safety disclosures not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the primary purpose in the first sentence and supporting safety details in short, focused sentences. Every sentence adds meaningful context without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive batch deletion tool, the description covers all essential aspects: permanence, required env vars, locator format, batch capability, and the explicitly unsupported `all` mode. Output schema exists, so return values need no explanation. It is complete for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only one parameter and low schema description coverage, the description compensates by clarifying that values must be locators, not human-readable names. Although it doesn't name `project_locators` explicitly, it explains the required format and semantic meaning beyond the schema's generic 'array of strings.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Permanently delete several named projects in one call,' which precisely states the action, the resource (projects), and the batching scope. It clearly distinguishes from sibling tools like fossa_delete_project (singular) by emphasizing 'several' and 'in one call.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly warns about the unsafe `locators=all` mode being unavailable, which is crucial for safe usage. It also states the required environment variables, but it does not explicitly name alternatives (e.g., 'for a single project, use fossa_delete_project'), leaving the batch usage guidance somewhat implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, but the description adds crucial context: projects and scan history survive, the release group and releases do not, and there is no undo. It also details the specific permission flags required. This significantly exceeds what annotations convey and does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with the primary purpose. Every sentence adds distinct value: purpose, requirements, side effects, and alternative. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive tool, the description covers purpose, preconditions, side effects, and alternatives. With an output schema present and no return-value expectations, the description is fully sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explicitly explain the release_group_id parameter. However, the parameter name is highly self-explanatory, and the description clarifies the concept of a release group. The tool's one-parameter simplicity partially compensates, but explicit parameter documentation is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete a FOSSA release group and every release in it' with a specific verb, resource, and scope. It explicitly distinguishes from the sibling tool fossa_delete_release_group_release for removing a single release, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names the alternative tool for single-release deletion and states required environment variables (FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true) as prerequisites. This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint, readOnlyHint), the description explains the full consequences: users lose SAML login, domains go with the config, and the operation is irreversible because the API cannot read settings back. This adds significant value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: action, prerequisites, consequences, and mitigation. Every sentence is information-dense and necessary, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, irreversible admin tool, the description covers prerequisites, side effects, irreversibility, pre-action steps, and parameter fallback. With an output schema present, no return-value detail is needed. This is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description compensates by explaining the fallback behavior of `organization_id` (falls back to FOSSA_ORG_ID). It also implies the parameter is optional, matching the schema. This adds meaning beyond the raw type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Remove the organization's SAML single sign-on configuration entirely.' This clearly distinguishes it from related tools like fossa_update_saml_settings and other delete operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the required environment flags (FOSSA_ALLOW_WRITES, FOSSA_ALLOW_ADMIN, FOSSA_ALLOW_DESTRUCTIVE) and provides cautionary guidance (copy settings, ensure admin access). It does not explicitly contrast with alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds meaningful context beyond annotations by enumerating exactly what data is reported (first-party scans, container scans, path dependencies, snippet retention, Free vs Premium) and highlighting the 403-avoidance behavior, which is valuable for agent planning.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The two-paragraph description is compact and front-loaded with the core purpose in the first sentence. Every sentence contributes either to scope or usage context, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only configuration lookup tool with an output schema present, the description is complete. It explains what the tool returns at a high level, why it matters, and how to use it effectively, leaving no operational gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds no parameter details, but none are needed—the empty schema leaves nothing to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the organization's CLI capabilities and defaults, including subscription level and supported scan types. It specifies the resource ('organization's CLI capabilities') and verb ('Read'), and is distinct from all sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit situational guidance: 'This is the fastest way to find out whether a feature is even available before a tool call fails with a 403.' It tells the agent exactly when to use this tool (pre-flight check) and lists the specific features it covers, making the use case unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses critical behavioral traits: the URL expires in five minutes, the server cannot perform the upload, and the binary file type is billing-gated. This adds substantial context about side effects and limitations that annotations alone do not capture. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. The first sentence states the core functionality, and the second paragraph elaborates on read-only nature, the required PUT action, the follow-up call, and a specific edge case. No wasteful words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and that an output schema exists, the description provides comprehensive context: workflow (get URL, PUT, then build), expiration, server limitations, and billing restrictions. It is sufficiently complete for an AI agent to invoke and handle the tool correctly, leaving few unknown behaviors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), and the description only partially compensates. It mentions component archive, SBOM, or binary, which maps to file_type enum values, and explains the billing gate for binary. However, it does not explain package_spec or revision, both required parameters. This is a gap, but the tool name and context provide some implicit meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Get a pre-signed URL for uploading a component archive, SBOM, or binary to FOSSA.' This is a specific verb and resource, and it distinguishes itself from the follow-up tool fossa_build_component by explicitly saying 'Call fossa_build_component afterwards to start the analysis.' The purpose is unambiguous and unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it mints an upload URL, does not upload anything, and the URL must be PUT to by the caller. It explicitly instructs to call fossa_build_component afterwards, giving a workflow. It also notes a caveat: file_type="binary" is billing-gated and 403s when out of binary decompositions, which is a practical usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description reinforces 'Read-only' and adds useful behavioral context about avoiding pagination, which goes beyond the annotations. It does not detail the return structure, but an output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core action, no fluff. Every sentence earns its place, and the structure is ideal for quick agent scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only summary tool with an output schema, the description fully covers purpose, usage context, and key behavioral traits. It is complete for its scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. There is no need for parameter descriptions, and the description correctly avoids mentioning nonexistent inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Count' and names the exact resources ('projects, shared projects, and release groups'), clearly distinguishing this summary tool from the broader listing tool fossa_list_projects. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'for a size check before listing anything' and contrasts with the alternative 'without paging through fossa_list_projects'. This gives clear usage guidance and points to the sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description reinforces read-only. Beyond annotations, it discloses the section mechanics, defaults to 'release' and 'summary', and warns that each section costs one FOSSA request—valuable behavioral insight that helps the agent avoid excessive API usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured. It front-loads the purpose, explicitly states read-only, explains sections in a scannable list, and adds a cost warning—all in under 80 words with no redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's moderate complexity with multiple optional sections, the description covers the section types, defaults, cost behavior, and read-only nature. Since an output schema exists, return formats are already documented, making this description complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description thoroughly explains the 'sections' parameter by defining each enum value and the default behavior. The two ID parameters (release_group_id, release_id) are self-explanatory by name, so the description compensates adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Get one release inside a FOSSA release group' and lists the available rolled-up views. This clearly distinguishes it from sibling tools like fossa_list_release_group_releases (which returns multiple releases) and fossa_get_release_group (which fetches the group itself).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it is read-only, targets a single release, and includes specific guidance on selecting sections based on need, warning that each section costs an additional request. It does not explicitly name alternative tools or exclusions, but the scope is evident from the description and tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=true and openWorldHint=true, already indicating a safe read operation. The description adds valuable behavioral details: the redirect behavior for 'part=original' (returns a download URL, not the document) and the 400 error for non-SBOM projects. These go beyond annotations to set expectations accurately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise, using paragraphs and code formatting to clarify the two modes. Every sentence adds useful information—purpose, behavior, and constraints—without redundancy. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to detail return structures. It covers the key contextual aspects: what each 'part' returns, the redirect nuance, and the valid project types. The 400 error condition is an important edge case that is explicitly mentioned, making the description complete for an AI agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description compensates by thoroughly explaining the 'part' parameter, including its default and the meaning of each enum value. It does not clarify 'project_locator' or 'revision_locator', but those are standard locator parameters self-evident from their names and required status. The explanation of 'part' provides significant semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns FOSSA's analysis of an uploaded SBOM or a link to the original file. It distinguishes between the two 'part' modes and specifies that it applies only to SBOM projects, differentiating it from sibling revision tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context on when to use the tool (for SBOM projects) and explicitly states that non-SBOM projects return a 400 error. It also explains the two 'part' choices. However, it does not mention specific alternative tools when one might use something else, so it falls short of full explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true, and the description reinforces with 'Read-only.' Beyond that, it discloses the tool's output structure: 'Returns a partial fix and a complete fix, each with the semver distance — MAJOR, MINOR, or PATCH.' This adds context about the return format and the tool's judgment support, going beyond mere annotation repetition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three compact sentences, front-loaded with the primary purpose, and every sentence adds value. No redundant filler or unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of annotations (read-only, open-world) and an output schema, the description still covers essential context: the unique single-vulnerability scope, the nature of the return (partial/complete fix with semver distance), and how it differs from the sibling tool. This is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description partially compensates by framing the parameters: 'one dependency revision' (revision_id) and 'one vulnerability' (vuln_id). It implies the semantic mapping but doesn't explicitly name or format the parameters. Since the baseline for 0 coverage is 4, the description provides enough contextual hint, though not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Ask which version of one dependency revision fixes one vulnerability, and how far away that version is.' It specifies the verb, resource, and scope, and explicitly distinguishes this tool from the sibling 'fossa_get_revision_remediation_guidance' by describing it as the 'single-vulnerability answer.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus an alternative: 'This is the single-vulnerability answer; fossa_get_revision_remediation_guidance returns the whole report for a project revision instead.' This names the alternative and clarifies the scope, enabling proper tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint and openWorldHint, and the description confirms 'Read-only' and adds extensive behavioral details: cursor-paginated walking forward/backward with non-mixable directions, cursor source from pageInfo, include_counts behavior, and the edge case of non-connected repos reading as empty. This far exceeds the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise andfront-loaded with the core purpose. Each sentence adds value: the opening states what it does, the middle covers pagination and counts, and the final addresses a potential error condition. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's behavioral scope for a list operation: it identifies the resource, explains pagination mechanics, the optional counts parameter, and a non-obvious edge case. With an output schema present, return values need not be described. The description is complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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. It explains the tricky pagination parameters (first/after, last/before, cannot mix), the include_counts flag, and cursor provenance. It does not explicitly describe sort, state, search, or project_locator, but those are relatively self-explanatory enums/strings. The added semantics for the less obvious parameters merit a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'List the dependency-upgrade pull requests fossabot has opened against a project's repository.' This clearly distinguishes it from sibling tools like fossa_get_fossabot_upgrade_pr (singular) and fossa_request_fossabot_upgrade_pr (create).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (listing fossabot PRs) and explicitly states it is read-only. It also explains pagination behavior and the empty-result case for non-connected repos, but it does not explicitly mention alternatives or when-not-to-use scenarios, so it misses a higher score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reaffirms 'Read-only.' It goes beyond by disclosing pagination mechanics, the issuer-URL nature of providers, the premium subscription requirement yielding a 403, and that no credential/client secret is returned. This is rich behavioral context not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with the purpose, followed by essential behavioral details. No wasted words; every sentence adds meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and annotations cover read-only safety, the description provides sufficient context: what the list contains, how pagination works, how filtering works, the permission prerequisite, and the absence of credentials. It covers the main edge cases an agent would encounter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the `prev` parameter as a cursor for pagination and clarifies that `filter_scope_id` is required when filtering by team scope. It does not explicitly explain `page_size` or the `filter_scope` enum values, but the names are self-evident and the description adds meaning to the non-obvious parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List the OIDC identity providers this FOSSA organization federates with,' using a specific verb and resource. It also clarifies that each provider is an issuer URL, distinguishing it from sibling tools like fossa_get_oidc_provider (singular) and list_oidc_trust_relationships.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context: pagination via cursor ('pass the `last` value from a previous page as `prev`'), filtering requirements ('Filtering by team scope requires `filter_scope_id`'), and a subscription prerequisite (premium; 403 otherwise). It does not explicitly name alternatives but the list vs. get distinction is implied by the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description adds meaningful context: the package labels vs project labels distinction, the id semantics for downstream tools, and the 402/403 response on the Free plan. This enriches the agent's understanding without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each earning its place: the core action, read-only confirmation, distinction from sibling, id usage, and a pricing/access caveat. No redundancy or fluff; the description is tightly written and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool returns (all package labels), how it differs from the related project-label tool, what the output is used for (label_id for assignments), and a known error condition. With an output schema present and no parameters, the description is fully sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema provides no parameter documentation. The description adds no parameter details (since none exist), but it does clarify that the returned numeric id is the label_id used by assignment tools, which indirectly explains how the tool's output feeds into other operations. With 0 params, baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List every package label defined in the organization,' a specific verb+resource+scope that immediately conveys the tool's function. It also distinguishes this tool from the sibling fossa_list_organization_labels by clarifying the difference between package and project labels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the user when to choose an alternative: 'use fossa_list_organization_labels for the labels that tag projects.' It also explains that the numeric id from this tool is what assignment tools take as label_id, providing clear contextual usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description enriches the readOnlyHint/openWorldHint annotations with concrete behavioral details: FOSSA caps page_size at 50, include_all_with_members switches to an unpaginated deprecated endpoint, and results include specific fields. This goes far beyond the annotations and helps the agent predict side effects and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then adds essential behavioral details in a logical order. Every sentence contributes meaningful information without repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description need not detail return values. It fully covers the pagination behavior, search semantics, the alternative deprecated mode, and the data returned. For a listing tool with no required parameters, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It explains page_size cap, search filters by team name, and the special behavior of include_all_with_members. The 'page' parameter is not explicitly described but is implied through the pagination discussion, so the compensation is strong but not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'List the teams in the FOSSA organization.' It clearly distinguishes the tool from siblings like fossa_get_team by indicating it lists multiple teams, and the scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it explains pagination, page_size limits, search semantics, and when to use the deprecated 'include_all_with_members' option. It does not explicitly name alternatives like fossa_get_team for single-team retrieval, so it falls short of full when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description adds meaningful behavioral details: each section is a separate FOSSA request (cost/performance), credentials come back obfuscated, and the tool requires FOSSA_ORG_ID. These are not inferable from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but front-loaded with the purpose and reads naturally. The extensive list of sections is somewhat redundant with the schema enum, but the grouping and explanations justify its length. No wasted sentences, but it could be tightened by referencing the enum for exact names.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the description covers prerequisites, output behavior (obfuscation), request cost, and the full set of sections. An output schema exists, and since the description already addresses endpoint-specific behavior, no critical context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining the meaning of the 'sections' parameter, categorizing the endpoint-derived section names (authentication, general, integrations-*, languages-*, projects-*). It adds semantic grouping over the flat enum in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Read one or more sections of a FOSSA organization's settings', using a specific verb ('read') and a clear resource. It distinguishes the tool from write/update siblings like fossa_update_org_settings and fossa_delete_org_setting by explicitly stating it is read-only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is a read-only operation, requires FOSSA_ORG_ID, and warns that each section is a separate request so the agent should ask only for what is needed. It does not explicitly name alternative tools for mutation, but the read-only framing and sibling names convey the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and openWorldHint=true, but the description goes far beyond by explicitly stating 'WRITES TO FOSSA' and explaining the queued-build side effect in concrete terms. It also clarifies that despite the read-like intent, it is 'gated like any other POST' and requires an environment variable. This fully discloses behavioral traits without contradicting any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-sentence purpose, a bold warning, then a short explanatory paragraph. Every sentence carries meaningful information—there is no filler, and the critical caveat about writes is prominent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having one parameter and an output schema, the description covers the essential context: the purpose, the write side effect, the async queuing, the result states, and the retry behavior. It gives the agent everything needed to invoke correctly and set expectations, making it complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (purls) has zero schema description coverage, but the description compensates by clarifying 'package URLs' and the 'up to 100' limit. This adds meaning beyond the raw schema (array of strings). It stops short of detailing PURL format or URL encoding, but for a single simple parameter it is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific and unambiguous statement: 'Resolve up to 100 package URLs to the FOSSA components they identify and return the licensing FOSSA holds for each.' This names the exact verb, resource, and output. It is distinct from sibling tools like fossa_list_dependencies or fossa_get_dependency, which do not focus on resolving purls to licensing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when the tool causes side effects ('a PURL FOSSA has not analyzed yet is queued for an asynchronous build') and advises calling again later for queued results, which is clear usage guidance. It does not explicitly name alternative tools or exclusions, but the unique purpose makes the 'when to use' implicit and unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations: it explicitly warns 'WRITES TO FOSSA', requires FOSSA_ALLOW_WRITES=true, explains that criteria is stored as-is keyed by issue view names, and mentions the premium subscription requirement. It also clarifies the update semantics and category immutability, giving the agent essential operational knowledge.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by prerequisites, usage rules, and criteria semantics. Every sentence adds necessary detail without fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and six parameters with a nested criteria object, the description covers the essential aspects: create vs update mode, required env var, premium requirement, category fixity, and criteria format. Return values are handled externally by the output schema, so no further explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates meaningfully for filter_id, category, and criteria, explaining the create/update distinction and the criteria key structure (severity, packageManagers, etc.). However, it does not clarify the semantics of name, sort, or group beyond what the bare schema property names and enums imply.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb-resource pair: 'Create a saved issue filter for the organization, or update an existing one.' It distinguishes this from sibling tools like fossa_delete_issue_filter and fossa_get_issue_filters by focusing on the save/create/update operation on saved filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete usage guidance: omit filter_id and pass category to create, pass filter_id to update, and notes that category is fixed at creation. It also states prerequisites (FOSSA_ALLOW_WRITES=true, premium subscription) but does not explicitly compare against alternative tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description reinforces the read-only nature. It adds value beyond annotations by stating a prerequisite: 'Requires the organization's security features to be on' and clarifying the open-world behavior (catalog lookup not tied to organization). No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the primary action, followed by scope clarification, an alternative tool, and a prerequisite. Each sentence adds distinct value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one parameter, rich annotations, and an output schema present, the description covers the essential context: what the tool does, what it returns, when to use it, and a prerequisite. No gaps remain for the given complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has only a 'query' string parameter with no description (0% coverage). The description compensates by explaining the query can be 'by identifier or text', giving an example CVE-2021-44228, which tells the agent what values are acceptable. This meaningfully adds beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Search FOSSA's CVE catalog by identifier or text and return the matching CVEs with their descriptions.' It specifies the resource (FOSSA's CVE catalog) and the verb (search), and distinguishes itself from findings by clarifying it is a catalog lookup, not organization-specific. This separates it from siblings like fossa_list_issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage guidance: it says to use fossa_list_issues with category="vulnerability" to find affected projects, contrasting the catalog lookup use case with the finding/affected use case. It also gives an example of when to use this tool (to answer "what is CVE-2021-44228" regardless of org impact).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true, openWorldHint=true). It discloses critical behavior: the tool rewrites the entire rule set, has no precondition for concurrency safety, may silently undo concurrent edits, reports surviving rules in `data.rules_sent`, preserves all non-block rules, and relies on an undocumented endpoint that may change without notice. This is exceptional transparency for a destructive mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence states the core purpose. Every subsequent sentence adds critical safety or behavioral information. It avoids filler and uses clear formatting with bold warnings. Length is appropriate for the tool's complexity and risk profile.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (destructive mutation, concurrency risk, undocumented endpoint), the description covers all essential aspects: what it does, when it does nothing, what data it reports, and its stability caveat. An output schema exists (has output schema: true), so return values are presumably documented there, but the description still covers the non-obvious 'data.rules_sent' field. This is complete for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description explains that 'package_locator' is the package whose block is being removed, and 'policy_id' identifies the policy. It also explains the behavior of the rule removal, which adds meaning beyond the raw parameter names. However, it does not specify formats, examples, or how to obtain valid values. With only two simple parameters, the description provides enough context to understand their roles, but a bit more detail on expected formats would be helpful. Baseline 3 is appropriate given the low coverage and the description's partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: 'Remove a package's blocked-dependency rule from one FOSSA quality policy.' It clearly identifies the action (unblock) and the target (a specific package's blocked rule in a policy). This distinguishes it from siblings like fossa_block_package and other policy tools, even without explicitly naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly warns about the destructive nature and required environment flags: 'WRITES TO FOSSA, DESTRUCTIVELY. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true.' It also provides a clear condition for when the tool performs no operation: 'If the policy carries no such block, nothing is sent and the policy is left alone.' This gives the agent actionable guidance on when to use (and avoid) this tool, including the concurrency caveat.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and idempotentHint=true, but the description adds much more: write requirement, default-to-None semantics, replace vs. merge behavior for two fields, mutual exclusivity of tracking/hidden branches, and that policy/scanning changes trigger a rescan. These are meaningful behavioral disclosures beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized, front-loaded with the core purpose, and every sentence adds value. It is well-structured with clear paragraphs and no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 24 parameters and no schema coverage, the description covers all major caveats: write permission, default semantics, replace-vs-merge fields, mutual exclusivity, and side effects (rescan). 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.
Parameters4/5
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. It explains the critical default-to-None behavior for all fields and details the replace semantics for label_ids and transitive_excludes, plus mutual exclusivity for branch parameters. It does not describe every individual parameter, but the schema titles are fairly self-explanatory and the most important semantic warnings are covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and identifies the resource ('one project's settings') with enumerated categories (metadata, branches, policy assignments, etc.). This clearly distinguishes it from sibling tools like fossa_get_project, fossa_delete_project, and fossa_update_revision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool (updating project settings) and provides a prerequisite (FOSSA_ALLOW_WRITES=true). It also advises reading current values with fossa_get_project before using label_ids or transitive_excludes. It does not explicitly exclude alternatives but gives clear operational context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that it writes to FOSSA and requires the environment variable FOSSA_ALLOW_WRITES=true. It also details partial-update semantics, the ambiguity between omitted and explicit null, and the rejection of setting and clearing the same field. These are non-obvious behavioral traits not captured in annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is about 80 words, front-loaded with the purpose, and every sentence adds meaningful functional detail. It covers write requirements, partial updates, clear_fields nuances, and scope exclusion without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with 8 parameters and nuanced update semantics, the description covers all critical operational aspects: the write requirement and env var, partial update behavior, the clear_fields mechanism, conflict rejection, and the distinction from release updates. An output schema exists, so return-value details are not needed. This is complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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. It explains that clear_fields is for unsetting nullable fields and clarifies the null ambiguity. The top-level purpose mentions title, policies, portal visibility, and report text, mapping to the parameter names. However, individual parameter meanings (e.g., licensing_policy_id) are not elaborated, but the names are self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Update a FOSSA release group's title, policies, portal visibility, or report text.' It also distinguishes itself from the sibling tool by stating 'This does not touch releases; use fossa_update_release_group_release for those.' This clearly differentiates its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the user to use fossa_update_release_group_release for release-level updates, providing an alternative. It also explains when to use clear_fields versus setting a field, and the restriction on setting and clearing the same field. This gives concrete usage context, though it does not enumerate all possible alternatives (e.g., create/delete).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly discloses that this tool writes to FOSSA and requires FOSSA_ALLOW_WRITES=true, going beyond the annotations. It also explains partial update semantics and that analysis results are unaffected, providing valuable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose. The added sentences about write requirements and partial update behavior are high-value and non-redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and only five parameters, the description covers purpose, write safety, and behavioral nuances. It is sufficiently complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description names the three mutable fields (link, url, author) and explains that only passed fields are sent. This adds meaningful semantic detail. The locator parameters are not explained but their names and required status in the schema reduce ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'update' and the resource 'revision's metadata', listing the editable fields (link, url, author). This distinguishes it from sibling tools like fossa_update_project or fossa_update_release_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (updating revision metadata) and clarifies that it edits provenance rather than analysis results. It does not explicitly reference alternatives, but the resource scoping makes the intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes far beyond the annotations by disclosing the permanent, credential-less security implications, the exact environment requirements, wildcard matching behavior, and the risk of enabling admin tier without caller authentication. The description adds substantial behavioral context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but every sentence contributes essential value, from the high-level summary to security warnings to parameter semantics. The most important warning is front-loaded and the structure flows logically from 'what it does' to 'why it is dangerous' to 'how to use it safely'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-risk, mutating, security-sensitive tool with no schema descriptions and a low-ambiguity name, the description is remarkably complete. It covers prerequisites, security caveats, parameter details, scoping, and data sourcing. The output schema exists, so the absence of return-value explanation is not a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description thoroughly explains required_claims (claim, value, hasWildcards, sub pinning, wildcard refusal), audiences, user_id lookup, and scope/scope_id semantics. It even provides an example for sub. This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb + resource ('Grant a workload permanent password-less login to FOSSA as a specific service account') and clearly states the outcome. It distinguishes itself from sibling tools like fossa_create_oidc_provider and fossa_exchange_oidc_token by focusing on trust relationship creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete guidance: requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_ADMIN=true, tells how to find user_id via fossa_list_oidc_provider_service_accounts, and explains how to use scope='team' with scope_id. However, it does not explicitly state when not to use this tool or name alternative tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description adds valuable behavioral context: response contents, non-pagination, and the fact that single-group lookups resolve email addresses. This goes well beyond the minimal annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences in a logical order: purpose, concept, response shape, and a non-pagination caveat. Every sentence earns its place, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and an output schema, the description covers all essential aspects: scoping, response contents, non-pagination, and the team-group/team distinction. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no parameter descriptions, but the description explains that omitting team_group_id returns all groups while passing a numeric id returns a single group and enriches the response. This fully compensates for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool retrieves FOSSA team groups, either all in the organization or a single group by numeric id. It clearly distinguishes team groups from teams, differentiating it from sibling tools like fossa_get_team.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the two call modes (all vs. by ID) and clarifies the domain concept, giving clear context for when to use the tool. However, it does not explicitly name alternative tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavioral context: the three sections and their meanings, the permission-delegation rule, default to 'roles' only, per-request cost, and lack of pagination. This goes well beyond the readOnlyHint and openWorldHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two well-structured sentences: the first gives the overall purpose, the second details sections and behaviors. Every sentence adds essential information without redundancy, and it is front-loaded with the main verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations and output schema, the description covers all necessary context: operation type, parameters with defaults, cost, pagination, and security-related assignability rules. Nothing critical is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only offers an enum for 'sections' with no descriptions (0% coverage). The description fully explains each enum value ('roles', 'permissions', 'assignable'), their meaning, and the default, completely compensating for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists roles, the permission catalog, and assignable roles, using the specific verb 'List'. It distinguishes itself from sibling tools like fossa_manage_role by being read-only and focused on role listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (listing roles and permissions) and explains the assignable subset and default behavior. It does not explicitly mention alternatives, but the read-only nature and detailed sections make usage conditions apparent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses important behavioral traits: page_size cap at 50, search fields, sort format, the deprecated unpaginated endpoint, service account flags, and that token metadata never includes token values. This adds substantial context beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by behavioral details. Each sentence adds distinct value without redundancy, and the length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all six parameters, explains edge cases (deprecated endpoint, service accounts), and addresses security-relevant details (token values never returned). Given the tool's complexity and the presence of an output schema, the description is highly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the full burden of explaining parameters. It does so thoroughly: page_size cap, search match fields, sort format, user_id single-fetch behavior, and include_all's effect. This goes well beyond the bare schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List the users in the FOSSA organization, or fetch one user by numeric id.' It specifies the verb ('list') and resource ('users'), and distinguishes two operation modes, setting it apart from sibling tools that focus on projects, issues, or other entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the default paginated list versus the deprecated `include_all` endpoint, and explains parameter behaviors like search and sort. It does not explicitly name alternative tools for user-related operations, but it gives enough internal guidance to make appropriate choices for most scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses write behavior, env var gates, scope-specific destructive requirements, side effects on attribution and issues, and edit permissions. This provides rich context not inferable from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized: purpose first, followed by safety warnings and scope parameter rules. Every sentence adds necessary context for a complex multi-scope tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers permission needs, side effects, scope rules, rescan behavior, and admin-only scope. Given the 10-param schema and output schema, nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description compensates by explaining each scope value and its required parameters, plus the meaning of origin_id. It clarifies action semantics and permission implications across scopes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence explicitly states the tool adds or removes a license from concluded licenses for a dependency revision. This is a specific verb+resource, setting it apart from sibling tools focused on projects, revisions, issues, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool: to override scanner-detected conclusions and affect attribution. It details permission requirements for different actions and scopes, but does not name alternative tools for similar tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond annotations: 'WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true' clarifies the mutation context. The one-way disclosure warning ('vendored spec documents no endpoint to withdraw it, so treat it as one-way') adds critical side-effect information not visible in annotations. No contradiction with readOnlyHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: first states the purpose, then the write prerequisite, then the irreversibility warning, then parameter clarification and constraints. No filler, logically ordered, and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key operational constraints: write-token requirement, feature flag, one-way nature, and the exact source for the shared_organization_id. With an output schema present, return-value details are not needed. Slight gaps: no mention of error conditions or what happens if the link is invalid, but overall the description is strong for a 2-parameter mutating tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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. It does explain the trickiest parameter (shared_organization_id) by distinguishing it from an organization id and pointing to a source. However, revision_id is only implied by context and lacks guidance on how to obtain or format it, leaving a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Share one SBOM project revision with another organization.' This clearly distinguishes the tool from siblings like fossa_get_sbom_sharing (which reads sharing links) and other revision tools. The resource and action are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Only revisions of SBOM projects can be shared' (exclusion) and 'the organization needs the sbomSharing feature flag' (prerequisite). It also directs users to fossa_get_sbom_sharing(section='linked_organizations') to obtain the correct shared_organization_id, serving as a companion-tool reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds important behavioral context beyond annotations by stating 'WRITES TO FOSSA' and requiring specific environment variables (FOSSA_ALLOW_WRITES=true, FOSSA_ALLOW_DESTRUCTIVE=true). It also scopes the destructive impact by clarifying that only bindings are removed, not label definitions. This complements the annotations (readOnlyHint=false, destructiveHint=true) with actionable prerequisites and safety details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with the main purpose in the first line. Warnings are clearly separated, and the parameter clarification is directly under the schema. Every sentence provides necessary information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive tool, the description covers purpose, prerequisites (env vars), parameter source, and the scope of destruction. The output schema is present, so return values are handled elsewhere. All essential context for invoking the tool is provided, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only the type (array of integers) for `assignment_ids` with no description. The description compensates by explaining that these are 'the `id` values from fossa_list_package_label_assignments' and emphasizing they are assignment IDs, not label IDs. This is crucial for correct usage and goes well beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Remove specific package label assignments' with a clear verb and resource, and explicitly differentiates from label deletion by noting 'The label definitions themselves are untouched; only these bindings go away.' This distinguishes the tool from siblings like fossa_delete_package_labels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the agent to obtain `assignment_ids` from fossa_list_package_label_assignments, indicating a prerequisite step. It also clarifies when to use this tool—when only assignments should be removed—without deleting labels. However, it does not explicitly name alternative tools (e.g., fossa_set_package_label_assignments) that could also remove assignments, so it's not fully explicit about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses the environment variable requirement, the mandatory title quirk, the structure of project entries, and the rejection of same-project-in-both-lists. This adds significant operational detail that the annotations do not provide. No contradiction with the annotations was found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence adds value, starting with a one-sentence summary, then a write warning, followed by parameter behavior and an edge-case rejection rule. No fluff or redundant repetition of schema fields. It is well-structured and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (write operation, 5 parameters, nested object structure, an API quirk), the description covers all essential aspects: purpose, write permission, parameter semantics, and a key edge case. An output schema exists, so the description does not need to explain return values. This is complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description compensates by explaining the semantic meaning of the non-obvious parameters: 'projects' entries (projectId, branch, revisionId) and 'projects_to_delete' (project locators). It also clarifies that 'title' is required even when unchanged. The remaining parameters (release_group_id, release_id) are self-explanatory from their names. This is strong compensation for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb and resource: 'Rename a release in a FOSSA release group and add, repin, or remove the projects in it.' This distinguishes it from sibling tools like create_delete/get release group releases, and also from the separate 'fossa_update_release_group' tool. The action scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool, including the write requirement (FOSSA_ALLOW_WRITES=true) and the API quirk about needing the title parameter even when only changing projects. It also explains the reject condition for overlapping projects. However, it does not explicitly name alternatives or state when not to use this tool, so it falls 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint, openWorldHint), the description adds crucial behavioral details: exactly which actions require FOSSA_ALLOW_DESTRUCTIVE, how 'replace' clears unbounded sets, that all_projects/project_filters are resolved server-side and may affect an unknown number of projects, and the prerequisite that projects in a release group must already be on the team. This is rich, non-redundant context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is long, it is tightly structured with bullets and bold warnings. Every sentence adds essential information—permissions, target-specific argument rules, action behavior, and destructive edge cases. The front-loaded purpose and requirements make it easy to scan, and there is no redundant fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, 3 targets, 3 actions), the description is remarkably complete. It covers all parameter combinations, special cases like unbounded project sets, validation behavior, prerequisites for release groups, and permission gates. The presence of an output schema means return values don't need description, and the behavioral and semantic coverage is thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description carries full responsibility for parameter meaning—and it delivers. For each target, it explains which parameters apply and their structures (e.g., users require id and roleId for add/replace; project_filters accepts title, labels, type, etc.). It also clarifies action semantics (replace sets exactly what is named) and that mismatched arguments are rejected.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Change what is assigned to a FOSSA team' and enumerates the three assignment types (members, projects, release groups). This clearly distinguishes the tool from sibling tools like fossa_update_team (team metadata) and fossa_manage_team_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (for any of three assignment targets) and details how each target uses different arguments. It states required environment variables (FOSSA_ALLOW_WRITES, FOSSA_ALLOW_ADMIN, etc.) and when destructive permission is needed. However, it doesn't explicitly mention when not to use this tool or name alternatives, so it falls 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description adds significant behavioral detail: it warns about non-atomicity for multi-team removals, clarifies that removing a team does not delete it, explains that 'replace' on users removes everyone else, and lists permission requirements. This far exceeds the annotation signal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized: a one-sentence overview, then requirements, then per-target details. Each sentence adds necessary information without redundancy. It is structured and front-loaded, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is reasonably complex (5 params, 2 enums, no schema descriptions, but has output schema). The description covers all essential aspects: purpose, permissions, parameter semantics, non-atomicity, and side effects. The output schema handles return values, so no need to describe those. It is complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the full burden of explaining parameters. It clearly maps 'team_ids' to the 'teams' target, explains that 'users' expects objects with 'id' and (for add/replace) 'roleId', and delineates which actions support each target. This compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Change what is assigned to a FOSSA team group: the teams it contains, or its members.' This is a specific verb+resource+scope, and it distinguishes itself from sibling tools like fossa_update_team_assignments by focusing on team group assignments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool, including required environment variables and which actions require destructive permissions. It explains the two targets (teams/users) and their supported actions, but it does not explicitly mention alternative tools or provide 'when-not' scenarios, stopping 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool writes to FOSSA and requires FOSSA_ALLOW_WRITES=true, which complements the readOnlyHint=false annotation. It adds critical behavioral context: the bulk endpoint cannot set scanning/status check, so projects with scanning off will block nothing. It also explains the safety guard against empty lists to prevent unintended re-policying of all projects. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose in the first sentence. Each paragraph adds necessary caveats about writing requirements, behavioral differences from siblings, and safety restrictions. No wasted words; the length is justified by the important safety warnings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's write nature and the availability of an output schema, the description covers the essential behavior, side effects, limitations, and safety mechanism. It explains the potential pitfall with the bulk endpoint and the developer's deliberate choice to avoid the filter mode. The output schema handles return value details, so no further description is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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. It clarifies that security_policy_id refers to a single policy and project_locators are explicit project targets, and adds that every target must be named and blank lists are refused. However, it does not explain the format or source of locators or how to obtain the policy ID, leaving some gap for users unfamiliar with FOSSA constructs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the action: 'Assign one FOSSA security policy to several projects at once.' It uses a specific verb (assign), names the resource (security policy) and target (projects). It also distinguishes from sibling tool fossa_enable_security_policy by explicitly stating it does not touch scanning or the status check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it contrasts with fossa_enable_security_policy ('Unlike... this does not touch scanning or the status check'), warns about the unreliability of the bulk endpoint, and explains that the 'apply to all projects matching filters' mode is deliberately not exposed. It also instructs that empty or all-blank lists are refused, giving clear when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond the annotations: it requires FOSSA_ALLOW_WRITES=true, clarifies that only label definitions are created (not assignments), and states that the response includes created label IDs needed by assignment tools. This matches annotations (readOnlyHint=false) with no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with the main purpose. No redundant wording. Each sentence adds valuable information (purpose, write requirement, scope, and response details).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter) and has an output schema (not shown, but noted). The description covers what it does, prerequisites, how it differs from related tools, and what the response contains. No significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides the parameter type (array of strings) with no description. The description adds 'one or more' indicating non-empty, and clarifies these are package label definitions. It doesn't specify label format constraints, but for a simple string array this is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Create one or more package labels in the organization.' This distinguishes it from sibling tools like fossa_create_organization_label (which creates org-level labels) and assignment tools that bind labels to packages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use this tool ('creates label definitions only') and when not ('nothing is tagged until fossa_assign_package_labels or fossa_bulk_assign_package_label binds one to a package'). It also names the alternative tools and notes the write permission requirement (FOSSA_ALLOW_WRITES=true).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes far beyond the annotations by disclosing that the operation writes to FOSSA, requires admin environment variables, and—critically—that a token secret is returned only once and carries significant authority. It also warns about transcript/log exposure of the credential, which is essential behavioral context for safe agent use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence serves a purpose: statement of operation, safety flag, role/team requirement, security warning, and guidance. It is front-loaded with the core action and immediately warns about write access. No filler; the length is justified by the tool's complexity and security sensitivity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 params, write operation, sensitive credential handling), the description covers prerequisites, role/team logic, token behavior, and security risks. An output schema exists, so explaining return values is unnecessary. It is complete and self-sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description compensates by explaining the key relationship between org_role_id, team_id, and team_role_id, and by clarifying the behavior of the token switches. However, it does not explain the username, email, or full_name parameters, leaving some semantic gaps despite the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Create a FOSSA service account, optionally with API tokens.' It is specific and distinct from sibling tools like fossa_create_team or fossa_create_release_group, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit prerequisites: 'WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_ADMIN=true.' It also explains the non-obvious requirement of a role or team assignment, and directs users to fossa_list_roles for role IDs. This gives clear when-to-use and how-to-proceed guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true, etc.), the description adds critical behavioral details: required environment variables (FOSSA_ALLOW_WRITES, FOSSA_ALLOW_ADMIN, FOSSA_ALLOW_DESTRUCTIVE), irreversibility ('not reversible from here'), and the side effect that existing tokens are not invalidated. These go far beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense. Each sentence adds value: purpose, required environment flags, irreversibility, recommendation to read first, and token expiration behavior. It is front-loaded with the primary action and uses minimal wording without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is fully adequate for a destructive tool: it explains what it does, prerequisites, side effects, and related actions. An output schema exists, so return value details are not necessary. Given the tool's complexity and the rich annotations, no meaningful gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single self-explanatory parameter, trust_relationship_id. Schema coverage is 0% because the description does not mention the parameter by name, but it indirectly explains how to obtain it via fossa_get_oidc_trust_relationship. This is sufficient compensation for a simple ID parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Revoke one OIDC trust relationship' with a specific verb and resource. It distinguishes this from sibling tools like fossa_create_oidc_trust_relationship, fossa_update_oidc_trust_relationship, and fossa_get_oidc_trust_relationship by framing it as the revocation path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool ('revocation path for a leaked or over-broad grant') and gives an alternative action ('Read it with fossa_get_oidc_trust_relationship first if it may need to be recreated'). This clearly contrasts with the read/get tool and provides concrete guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already indicating destructive behavior, the description adds valuable context: 'target="logo" clears the organization's uploaded logo and nothing else,' clarifying the exact scope of destruction. It also discloses the required environment variable safeguards, going beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the main purpose. Each sentence serves a distinct function: stating the action, highlighting write/destructive requirements, explaining the target parameter, and pointing to an alternative. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter destructive tool with an output schema, the description covers purpose, prerequisites, effect scope, and an alternative. It is self-contained and does not require additional context from sibling tool names or schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter with a const value and no description, so the description compensates by explaining the parameter's effect: 'target="logo" clears the organization's uploaded logo and nothing else.' This adds behavioral meaning, though the schema's const already constrains the value, slightly limiting added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a FOSSA organization's logo' with a specific verb and resource. It further distinguishes itself by noting 'clears the organization's uploaded logo and nothing else' and references the alternative SAML deletion tool, differentiating it from sibling deletion tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly mentions required environment variables (FOSSA_ORG_ID, FOSSA_ALLOW_WRITES=true, FOSSA_ALLOW_DESTRUCTIVE=true) and provides an explicit alternative: 'To remove the organization's SAML single sign-on configuration... use fossa_delete_saml_settings.' This fully guides when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description consistently states 'Read-only.' It adds valuable behavioral context: every entry records who acted, on what, old/new value; both views take same filters; starting_after and offset semantics. This goes beyond annotations to explain edge-case behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, all highly informative and directly relevant. No filler, front-loaded with the core purpose, then practical usage tips. Each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 13 parameters and zero schema description coverage, the description covers the most critical aspects: read-only nature, data content, count/list modes, and pagination strategy. The presence of an output schema fills in return-value details. It is complete for an agent to choose and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It adds meaning for key parameters: view (list/count), starting_after (row-id cursor), offset (drifts), and clarifies filters apply to both views. However, many of the 13 parameters (e.g., topics, actions, sort_by, dates) are left to schema titles; the description doesn't explain their exact format or interaction, making it slightly incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the organization's audit log or counts matching entries, using specific verbs ('Read', 'count') and a clear resource. It distinguishes itself from potential siblings like fossa_export_audit_logs by focusing on reading/counting rather than exporting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: run view="count" first to size a query before paging, and use starting_after (row-id cursor) for reliable paging vs offset which drifts. This is concrete when-to-use and how-to-use instruction beyond general context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint:true and openWorldHint:true, but the description adds substantial behavioral nuance: the URL is 'constant public GitHub App installation URL with no state, code, or nonce,' safe to show and reuse, and following it would only fetch an HTML page. This explains side effects and security posture far beyond the structured annotations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into three short paragraphs, each earning its place: the first states the core purpose, the second explains the read-only and human-in-the-loop aspects plus error condition, and the third details the URL's safety and reusability. There is no fluff; every sentence adds essential information for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description is fully complete. It covers purpose, usage, error handling (404), the nature of the return value (a constant, safe, public URL), and explicit confirmation that the tool does not perform installation. The agent can confidently invoke and interpret the result without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, and the input schema is empty with 100% coverage. The description appropriately does not discuss parameters, adhering to the baseline of 4 for no-parameter tools. It could have noted 'takes no input' explicitly, but that would be redundant given the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get the URL a FOSSA administrator opens to install the FOSSA GitHub App,' which clearly identifies the specific action (get), the resource (URL for GitHub App installation), and the audience. It distinguishes itself from all sibling tools, which focus on projects, revisions, issues, teams, etc., leaving no doubt about its unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it clarifies the tool is read-only and 'installs nothing,' so the returned URL must be opened by a human with GitHub admin rights. It also explains that a 404 means the GitHub App is not configured, giving the agent diagnostic context. This goes beyond simple usage and covers when-not-to-expect-installation behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by disclosing that FOSSA's update endpoint replaces both editable fields rather than patching, that deletion removes team associations and membership lists but not the teams themselves, and that there is no undo. It also explicitly warns about the destructive nature of delete, complementing the destructiveHint and idempotentHint annotations with concrete consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently organized: a one-line summary, a clear warning about writes and permission flags, then action-specific parameter requirements, and finally deletion behavior. Every sentence adds necessary information, and the structure front-loads the most critical facts (purpose, write safety, permissions) before diving into details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (three actions, three permission flags, destructive side effects, field replacement semantics), the description covers all essential aspects: what the tool does, how each action maps to parameters, what deletion affects, and which sibling tool handles the related but distinct task of changing team assignments. The presence of an output schema means return-value documentation is not required, so the description is fully sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining the role of each parameter in the context of each action. It clarifies that name and default_role_id are the two editable fields and that team_group_id is required for update/delete. However, it does not elaborate on the meaning of default_role_id beyond its schema title, so it stops short of full semantic coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create, rename, or delete a FOSSA team group,' a specific verb+resource statement that exactly matches the tool name and clearly differentiates from sibling tools. It further distinguishes itself by noting it covers three actions rather than three near-identical tools, and explicitly names fossa_update_team_group_assignments as the alternative for changing team membership.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit per-action requirements (create needs name+default_role_id, update needs team_group_id plus both, delete needs only team_group_id) and states when to use this tool vs. the related assignment tool. It also specifies environmental prerequisites (FOSSA_ALLOW_WRITES, FOSSA_ALLOW_ADMIN, FOSSA_ALLOW_DESTRUCTIVE for delete), giving clear when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which provide no safety hints), the description discloses critical behavioral traits: writes to FOSSA, requires environment variable and subscription, credentials are stored, travel through tool call and appear in transcripts, and are not echoed back. It also explains the clear_fields mechanism and why it exists, adding significant context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then uses caps for warnings, and logically structured paragraphs for create/update and credentials. Every sentence provides necessary information, and the credential warning is detailed but fully relevant. No filler or redundancies.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex write tool with 19 parameters and no schema descriptions, the description covers key usage modes, prerequisites, credential security, and the nuanced behavior of updates and clearing fields. An output schema exists, so not explaining return values is acceptable. This description is exceptionally complete for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It explains the key semantics of jira_id (create vs update), clear_fields (clearing null fields vs leaving unchanged), and credentials (username, password, headers) including their handling. However, many parameters like components, issue_types, and default_* projects remain undocumented, leaving gaps for a 19-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Create a Jira site configuration, or update an existing one.' This uses a specific verb and resource, and the create/update distinction distinguishes it from sibling tools like fossa_get_jira_configurations and fossa_delete_jira_configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use create vs update: 'Omit `jira_id` to create; supply it to update.' It also notes prerequisites (FOSSA_ALLOW_WRITES=true, premium subscription) and offers an alternative for credential configuration: 'prefer configuring credentials in the FOSSA web app and using this tool for everything else.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses key behavioral traits: it is destructive (removes unmentioned assignments), requires both FOSSA_ALLOW_WRITES and FOSSA_ALLOW_DESTRUCTIVE, and warns about clobbering others' labels. It also explains the reconcile semantics and empty-list clearing behavior, which the annotations alone do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and logically ordered: purpose, warnings, reconcile semantics, prerequisite read, parameter clarification, and alternative tool. Every sentence adds value and none are redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive write tool with nested object parameters and no schema descriptions, the description covers purpose, usage, destructive implications, prerequisites, parameter semantics, and alternatives. The output schema exists, so return details need not be described. It is fully sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates well for the most complex parameter `new_label_ids`, clearly defining its key-value mapping, the literal 'all' for all versions, and empty-array clearing. It does not explicitly explain `scope_id`, but the schema's enum and default null provide some structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Replace a package's label assignments at one scope with an exact desired state.' It clearly distinguishes this from related tools by labeling it a 'reconcile, not an addition' and by contrast with fossa_assign_package_labels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool versus the alternative, recommending fossa_assign_package_labels for additive intent. It also instructs to read current state with fossa_list_package_label_assignments first, and highlights required environment variables for writes/destructive operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal destructive and non-read-only behavior, but the description adds substantial context: the FOSSA_ALLOW_WRITES and FOSSA_ALLOW_DESTRUCTIVE environment requirements, the broad 'every issue matching the filters' behavior when issue_ids is omitted, and the durable-rule distinction for issueException. It also warns that the affected set is not visible in advance, which is exactly the kind of behavioral trait an agent needs. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured, front-loading the action set and using short paragraphs for safety requirements, selection semantics, and exception-specific constraints. Every sentence adds new information—no filler, no repetition of schema fields or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 24-parameter destructive mutation tool, the description covers the critical selection-destructive behavior, required environment variables, the preview workflow, and action-specific parameter constraints. Since an output schema exists, return-value details are not necessary, and the description provides sufficient context to invoke the tool safely and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates for the most critical parameters: it clarifies issue_ids (exact vs. omitted set), and maps package_scope, ignore_scope, expires_after, and license_id to the issueException action. It also tells the agent to use the same filter arguments as fossa_list_issues, which offloads semantics to a sibling. However, many of the 24 filter parameters are not individually described, so the compensation is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb phrase: 'Ignore, unignore, unlink, or create a reusable exception for a set of issues,' naming the exact actions and resource. It also distinguishes this tool from siblings by clarifying the durable exception behavior and explicitly excluding ticket export, so the agent knows what this tool does and does not do.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent to run fossa_list_issues with the same arguments first to preview the affected set, and clearly states when the destructive gate applies (FOSSA_ALLOW_DESTRUCTIVE required when issue_ids is omitted). It also explains that issueException-specific parameters only apply to that action and that ticket export is not offered, providing direct when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, it discloses write requirements (FOSSA_ALLOW_WRITES=true, FOSSA_ALLOW_ADMIN=true), the partial-update semantics ('Only the fields passed are sent; anything omitted is left as FOSSA has it'), the null-handling nuance for uniqueIdentifier, and the side effect that default_role_id only affects future members. These are valuable behavioral details not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by prerequisites and then nuanced behavior. Every sentence adds critical information—no fluff or repetition. The structure flows logically from what/requirements/behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with partial-update semantics and a nullable field, the description covers all essential context: purpose, prerequisites, update behavior, null handling, side effects, and an explicit alternative for re-roling. The output schema covers return value details, so nothing is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description compensates by explaining the meaning of key parameters: it names updatable fields, explains the unique_identifier/clear_unique_identifier relationship, and clarifies default_role_id's scope. It does not deeply explain auto_add_users or the exact format of unique_identifier, but the purpose statement covers enough to infer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Update a FOSSA team's name, default role, auto-add setting, or external identifier.' It clearly distinguishes this from sibling tools by later stating 'This tool does not change membership' and pointing to fossa_update_team_assignments for role changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: it states when to use this tool (updating team settings) and when to use an alternative ('use fossa_update_team_assignments with action "replace" to re-role existing members'). It also explains the partial-update behavior and the separate switch for clearing unique_identifier, which helps correct tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The write requirement (FOSSA_ALLOW_WRITES=true) is disclosed, aligning with readOnlyHint=false. Idempotency is explicitly stated, matching idempotentHint=true. Additionally, it warns that the endpoint is undocumented and may change without notice, which is valuable behavioral context beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured: it opens with the purpose, then covers the write requirement, parameter details, idempotency, and API stability warning. Each sentence earns its place, with no fluff or repetition. The information is front-loaded and logically ordered.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all essential context: purpose, write prerequisites, parameter semantics, policy type constraints, reversibility, idempotency, and stability risk. Since an output schema exists, return values need not be explained. This is a complete and self-sufficient description for a write operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description fully explains all three parameters: package_locator is defined as a versionless locator with examples, versions has clear semantics (omission vs. explicit list), and policy_ids are specified as numeric IDs of quality policies only. This adds significant meaning beyond the schema's basic type/title information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Block a package by adding a blocked-dependency rule to one or more FOSSA quality policies.' It specifies the exact verb (block), the resource (package), and the mechanism (quality policy rule), distinguishing it from sibling tools like fossa_unblock_package.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it names fossa_unblock_package as the reversal tool, states that block rules cannot attach to licensing/security/SBOM policies, and explains the behavior of omitting vs. specifying versions. It also notes the FOSSA_ALLOW_WRITES=true prerequisite, giving clear when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate write (readOnlyHint=false) and destructive (destructiveHint=true). The description adds essential context: 'WRITES TO FOSSA' and the required environment variables FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true. It also describes the side effect (issues become active again) and the safeguard against clearing all exceptions in one call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then permissions, then usage modes and safety notes. Each of the five sentences contributes distinct value—purpose, auth requirements, input options, safety constraint, and recommended pre-check—without extraneous filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 optional parameters, multiple target modes) and the presence of an output schema, the description covers the necessary prerequisites, permissions, selection semantics, and safety guardrails. It also references fossa_get_issue_exceptions as a pre-flight step, making it complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description compensates by explaining each parameter's role: exception_id for a single rule, exception_ids for a named list, and filter parameters (category, project_id, release_group_id, policy_id) for batch deletion. It also clarifies the constraint that at least one filter must be provided, adding meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete issue ignore rules' with the effect 'makes the issues they were suppressing active again.' This distinguishes from sibling tools like fossa_get_issue_exceptions and fossa_extend_issue_exception by specifying the delete action and the scope (single, list, or filter).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage rules: 'Pass exactly one target' and details the three modes (exception_id, exception_ids, filter). It warns that the filter form requires at least one filter, preventing blanket deletes, and directs the agent to 'Run fossa_get_issue_exceptions first to see what a filter covers.' This is clear when-to-use and safety guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, openWorldHint), the description discloses that providing `label_id` changes the response to include 'locators of the projects carrying that label.' It also clarifies the resource scope (project vs. package labels), adding valuable behavioral context not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with the core action in the first sentence. The subsequent sentences add necessary distinctions and parameter behavior without redundancy or fluff, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage distinctions, parameter semantics, and behavioral nuances. With an output schema present and annotations provided, it is sufficiently complete for an agent to select and invoke the tool correctly without further clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema merely defines `label_id` as an optional integer. The description adds essential semantics: omitting it lists all labels, while including it reads a single label and enriches the response with project locators. This fully compensates for the schema's lack of descriptive coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List the organization's project labels, or read one by id.' It also distinguishes from the sibling tool fossa_list_package_labels by explicitly noting 'Package labels are a separate resource; see fossa_list_package_labels,' which eliminates ambiguity about which label resource this tool targets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context by explaining that these are project labels used by fossa_apply_project_label and filtered by fossa_list_projects and fossa_list_issues. It also directs users to the alternative tool for package labels, giving clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: it discloses that passing 'permissions' on update replaces the entire list, that scope is immutable after creation, and that deletion is refused for built-in roles or roles still assigned to users. This goes well beyond the basic readOnlyHint/destructiveHint annotations and provides no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense yet well-structured, with a clear first sentence, a block for write prerequisites, action-specific parameter breakdowns, and a dedicated paragraph for permissions behavior and edge cases. No sentence is wasted; the length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all essential operational context: purpose, prerequisites, parameter usage, replacement semantics, immutability, and deletion restrictions. It references fossa_list_roles for valid permissions and handles edge cases, making it fully complete for an agent to use the tool correctly. Output schema exists, so return value documentation is not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description fully compensates by explaining each parameter's role in the context of each action: scope values ('organization'/'team'), role_id for update/delete, name/description/permissions for create/update, and the structure of permissions entries. It also clarifies which parameters are needed for each action, making the schema's defaults and nullability interpretable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create, update, or delete a custom FOSSA role,' which uses a specific verb and resource, clearly distinguishing this tool from siblings like team management or project tools. It also specifies that it handles all three actions in one tool and focuses on custom roles, differentiating from built-in roles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance for each action (create, update, delete), including required parameters for each. It mentions prerequisites (FOSSA_ALLOW_WRITES, FOSSA_ALLOW_ADMIN, FOSSA_ALLOW_DESTRUCTIVE) and points to fossa_list_roles for valid permissions, helping the agent choose correctly. It also explains restrictions on deleting built-in or assigned roles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses that both actions destroy state, replace is a full-section replacement with no undo, propagate overwrites on every project, unknown keys are rejected, and sbom-report-defaults is not readable. This goes well beyond the annotations (destructiveHint=true, readOnlyHint=false) and provides essential behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Despite being long, the description is exceptionally well-structured with bullets and bolded action names. Every sentence adds critical information about auth, behavior, or parameter usage. No fluff or redundancy; the length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all major edge cases: section-specific auth requirements, non-readable section, unsupported sections for propagate, array-based sections, and an explicit pointer to the SAML alternative. With an output schema present, the lack of return-value discussion is fine. This is complete for a complex write tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema description coverage is 0%, the description thoroughly explains `action`, `values`, `items`, `fields`, and `section` semantics. It clarifies which sections use items vs values, what fields does in propagate, and how action changes the HTTP verb. This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes one section of FOSSA organization settings or propagates defaults to all projects. It distinguishes from related tools by name (e.g., fossa_org_settings for reading, fossa_update_saml_settings for SAML). This is a specific verb+resource with scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use replace vs propagate, specifies prerequisites (FOSSA_ALLOW_DESTRUCTIVE, FOSSA_ALLOW_ADMIN for certain sections), and names an alternative tool for SAML. It also advises re-reading with fossa_org_settings before replace to avoid clobbering. This is comprehensive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![fossa-mcp MCP server](https://glama.ai/mcp/servers/darthzen/fossa-mcp/badges/card.svg)](https://glama.ai/mcp/servers/darthzen/fossa-mcp)

Score Badge

Copy to your README.md:

[![fossa-mcp MCP server](https://glama.ai/mcp/servers/darthzen/fossa-mcp/badges/score.svg)](https://glama.ai/mcp/servers/darthzen/fossa-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/darthzen/fossa-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server