yads-mcp
Server Quality Checklist
Latest release: v0.1.0
- Disambiguation4/5
Most tools have clearly distinct purposes within their domains (queue, tags, scans, targets). Slight overlap exists between tags_bulk_assign and tags_bulk_add_by_ids, and queue_status vs queue_list_rate_limited_modules, but descriptions clarify the differences well.
Naming Consistency4/5Tool names follow a consistent snake_case verb_noun pattern with domain prefixes (queue_, tags_, scan_, bulk_). Minor inconsistencies like undo_bulk_delete_targets (vs. queue_undo_purge) and some verbs (archive vs restore) are present but the overall pattern is predictable.
Tool Count2/5At 31 tools, this exceeds the 25-tool threshold for heavy servers. While the domain is complex and the tools are organized by sub-domains, the count feels bloated for a single MCP server and may overwhelm agents with too many options.
Completeness4/5The tool surface covers the core lifecycle for targets (add, list, get, delete, archive, restore), scans (trigger, bulk, findings), queue management, and tags. Notable gaps include no blocklist-management tool (acknowledged) and no tool to list available scan modules, but these are minor and workaroundable.
Average 3.8/5 across 31 of 31 tools scored. Lowest: 2.6/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 14 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 MIT License.
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.jsonto 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
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states what data is captured, not whether the operation is read-only, what happens with invalid target IDs, or if any side effects occur. The lack of any behavioral disclosure leaves significant ambiguity 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core concept of network context. It avoids unnecessary verbosity and is appropriately brief for a simple get-type tool. However, it could be slightly more structured to separate the data from the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and a single parameter, the description should clarify the return format and any prerequisites. It does not mention what the response contains beyond the captured context, nor does it state that a valid target_id is required. This is insufficient for an agent to confidently invoke the tool without further guesses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not mention the target_id parameter at all. The description adds no meaning beyond the schema's minimal definition of an integer ID. The agent must infer that target_id refers to the target whose network context is being fetched, which is not explicitly stated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deals with network context captured during scans, specifying the external IP and resolved IPs. It is distinct from siblings which focus on queues, tags, scans, and targets. However, it does not explicitly state that the tool retrieves or returns this context, leaving the action implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention any preconditions (e.g., target must exist or have scans) or scenarios where this tool is preferred over others. The sibling list provides context but no explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'Queue a scan' implying asynchronous behavior, but does not disclose what is returned, whether the operation is validated, whether it is idempotent, or what side effects occur. For a tool that triggers scans, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundancy, which is admirably concise. However, it is so terse that it omits essential information, so the conciseness works against completeness rather than as an efficient summary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a queueing action with no annotations and no output schema, the description is incomplete: it does not explain the return behavior (e.g., a job ID or status), the semantics of scan_types, relationship to scan_bulk_preview_count or scan_bulk_by_criteria, or any rate/queue constraints. An agent would need to guess critical details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does 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 names only target_ids ('explicit list of target ids') and entirely omits scan_types, leaving its meaning, allowed values, and required format undefined. The agent cannot reliably construct correct arguments from this description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Queue a scan') and a specific input ('an explicit list of target ids'), which clearly differentiates it from sibling tools like scan_bulk_by_criteria or scan_bulk_preview_count. It does not explicitly name those siblings, but the phrase 'explicit list' signals the distinguishing factor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives only a vague usage context ('explicit list of target ids') and does not specify when to prefer this over scan_bulk_by_criteria or scan_trigger, nor when not to use it. There are no stated prerequisites, exclusions, or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals that the tool returns the full tag list after the change, which is useful, but it does not mention side effects, idempotency, error handling, or permission requirements. For a mutating operation, this is a significant gap beyond what is stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, crisp sentence that front-loads the core action and return value. It contains zero fluff and is easy to parse efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and 0% parameter description, the tool is not adequately specified for reliable invocation. It omits prerequisites, error conditions, and parameter semantics, relying solely on the unknown output schema. An agent would struggle to use this correctly without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no parameter details. Neither 'tag' nor 'target_id' is explained beyond the schema titles, leaving the agent without information on formats, constraints, or valid values. The description entirely fails to compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Add a tag to one target' and emphasizes 'one target,' which implicitly distinguishes from sibling bulk operations like tags_bulk_add_by_ids. However, it doesn't explicitly name any sibling, so differentiation is left to inference, making it slightly less than maximally clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to choose this tool over alternatives such as tags_bulk_assign or tags_bulk_add_by_ids. The phrase 'one target' hints at single vs. bulk, but the description does not state conditions, prerequisites, or when not to use it, leaving the agent to guess.
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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It usefully discloses the server-side limit cap (100), valid scan_status values, and the special semantics of last_scanned_before (matches never-scanned targets). However, it omits return format, pagination details, and any explicit confirmation that this is a read-only operation. The disclosed behaviors add value but leave gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: the main purpose is front-loaded, followed by critical constraints and semantics. It avoids redundancy and wastes no words. However, it could be slightly more organized by grouping parameter details, but overall it is concise and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no annotations, and no output schema, the description is incomplete. It fails to explain several parameters, provides no information about the response structure or pagination behavior, and does not mention any defaults beyond what the schema already shows. The absence of these details leaves the agent guessing on important aspects of invocation and interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It explains limit, scan_status, and last_scanned_before, but leaves tag, page, online, archived, and domain_search entirely undocumented. This partial compensation is insufficient for an 8-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List targets') and resource ('for this key's tenant'), and mentions optional filters. It distinguishes conceptually from sibling get_target (which fetches a single target), though it does not explicitly name the alternative. The verb and scope 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like get_target or other listing operations. It does not mention exclusions or preferred scenarios. The description explains filter behavior but does not help the agent decide between this and sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action and variant, but does not mention side effects (e.g., idempotency, failure behavior if a tag doesn't exist, whether it overwrites existing tags), performance, permissions, or the response shape. For a mutation tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise—two short sentences, no filler, and the differentiating information is front-loaded. Every word serves a purpose, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk mutation tool with no annotations, no output schema, and zero parameter schema coverage, the description leaves out critical operational details: what the tag string represents, how the response indicates success/failure, and whether partial failures are possible. Even though the tool is simple, the lack of behavior and parameter info makes it incomplete for an agent to call confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no parameter-specific meaning. 'tag' is left ambiguous (name vs ID) and 'target_ids' is only clarified by the phrase 'by id', but without format, constraints, or batch size limits. The description does not compensate for the missing schema docs at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Add'), the resource ('a single tag to multiple targets by id'), and differentiates itself from the sibling 'tags_bulk_assign' by calling it a simpler variant for the one-tag-to-many-targets case. This fully disambiguates it from 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly names the alternative (tags_bulk_assign) and frames itself as 'simpler variant' for the common scenario, which provides clear when-to-use guidance. However, it does not explicitly state conditions for when NOT to use it or why one would choose the other beyond simplicity, leaving some room for inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes what the tool returns (state, counts, tasks) but does not state that it is non-destructive or read-only, nor does it mention any side effects, rate limits, or authentication requirements. For a status tool, this is a notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that front-loads the primary purpose and lists the specific data points returned. No redundant phrases or filler; it is well-structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless status query with no output schema, the description adequately enumerates the three main output categories (active state, counts, Celery tasks). It is sufficient for an agent to understand what information will be available, though it does not detail formatting or error behavior, which is acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is effectively 100%. The baseline for 0 parameters is 4. The description adds no parameter information because none exist; no improvements are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the current queue state: active status, queued/running counts, and Celery task details. It uses specific terminology ('paused/resumed', 'queued/running target counts', 'active/reserved Celery tasks') and is scoped to the API key's tenant. It does not explicitly name a sibling tool but the purpose is distinguishable from mutation tools like queue_pause or queue_resume.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied: it is a read-only inspection tool among queue-management siblings. However, the description does not explicitly state when to use it versus alternatives, nor does it mention any conditions or exclusions. An agent could infer it is for status checks, but explicit guidance is missing.
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?
With no annotations, the description must disclose behavioral traits. It explains the expansion behavior of 'full_scan' but does not mention side effects, asynchronous execution, rate limits, or any prerequisites. The description is silent on whether the scan is queued or synchronous, and what happens to the target after the scan, leaving significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two sentences with an example. It front-loads the main action and includes a concrete example for 'scan_types'. No extraneous wording is present, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters and no output schema, the description should cover the return value, prerequisites, and execution behavior. It does not mention what the tool returns (e.g., scan ID or status), whether the scan is asynchronous, or any error conditions. While it explains the 'full_scan' expansion, it omits critical context about the overall process, making it incomplete for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description needs to explain all parameters. It clarifies 'target_id' as a numeric id and 'scan_types' with acceptable values, but completely ignores 'scan_priority'. This omission leaves the agent unsure about how to use the optional priority parameter, and the description does not fully compensate for the schema's lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (trigger a scan) and the resource (an already-known target by numeric id). It also differentiates this tool by specifying 'already-known target', which distinguishes it from other scan tools like 'scan_trigger'. The inclusion of an example module list further clarifies the intended use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is for known targets, but does not explicitly state when to use it versus alternatives like 'scan_trigger'. It provides useful guidance on 'scan_types' values, including the expansion behavior of 'full_scan', which helps the agent decide what to pass. However, it lacks explicit exclusion criteria or references to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It states the state change (un-archiving and subsequent scanning) but omits critical details such as reversibility, permission requirements, error behavior (e.g., what happens if the target is not archived), or any side effects. This is insufficient for a mutating tool without annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the verb and resource, contains no fluff, and conveys the essential information efficiently. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one integer parameter, no output schema, no annotations), the description provides only the basic purpose but lacks guidance on return value, edge cases (e.g., target already un-archived), or any operational context. An agent would need to assume behavior, which is risky for a mutating operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining the parameter. It only refers to 'a target' generically without explicitly linking target_id to the target to be un-archived. It adds no semantic value beyond the parameter name and type, failing to meet the compensation burden for low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb ('Un-archive'), the resource ('a target'), and the effect ('clearing its archived state so it's scanned again'). It is specific and distinguishes this from sibling archive tools like bulk_archive_targets or archive_dead_targets, which perform 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implicitly defines when to use it: when a target has been archived and needs to be scanned again. However, it does not explicitly mention alternatives or when not to use it, though the context is clear enough for an agent to infer the appropriate scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits on its own. It mentions ordering ('newest first') and tenant scoping but omits key behaviors like whether the operation is read-only, pagination limits, or potential impact on other resources. This is insufficient for a tool with zero annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the essential information without extraneous detail. It is front-loaded with the core purpose and ordering. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and an existing output schema, the description is adequate for basic invocation. However, it lacks any mention of pagination or retrieval limits, which could be relevant for large result sets. Still, given the tool's simplicity, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing to explain. The schema description coverage is 100% trivially, and the description adds no parameter semantics. Per the baseline rule for 0 parameters, a score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States clearly that the tool retrieves scan findings for the tenant associated with the key, ordered newest first. The verb 'get' in the name and the resource 'findings' make the purpose unambiguous. It is distinct from sibling scan tools like scan_trigger, which initiate scans rather than retrieve results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives. There is no mention of configuration prerequisites or contexts where this tool should be preferred over scan_* variants. The agent must infer usage from the name alone.
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 no annotations provided, the description must disclose behavioral traits, and it does so for the critical 'replace' action: 'replaces each target's entire tag list with `tags`.' It also clarifies the default action ('add') and the remove action. This is valuable beyond what the schema shows. However, it omits details like idempotency, error handling, or what happens for invalid target IDs, so it is not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact—two sentences with the core purpose front-loaded and action semantics immediately following. It wastes no words, though the structure could be slightly improved by separating the action spec more clearly, but it is still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and three parameters, the description is incomplete. It doesn't mention return values, error conditions, or what happens if some target IDs are invalid. It also fails to explain target_ids entirely. The description covers only part of what an agent needs to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain all parameters. It mentions 'tags' and 'action' (including its default and allowed values) but completely omits 'target_ids,' which is a required parameter. The description does not explain what target_ids are (e.g., list of integer IDs) or how they are used, leaving a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Add, remove, or replace tags on multiple targets at once.' The verb 'add/remove/replace' plus the resource 'tags on multiple targets' is specific and distinguishes it from single-target tag tools like tags_add_to_target and from tags_bulk_add_by_ids (which only adds, not removes or replaces).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the bulk-use case with 'on multiple targets at once,' but does not explicitly mention when to use this instead of alternatives like tags_bulk_add_by_ids or tags_delete_globally. It gives context (bulk operation) but no exclusions or explicit selection criteria beyond the action semantics.
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?
With no annotations, the description carries the burden of behavioral disclosure. It states that the operation returns the target's full tag list after the change, which is a useful behavioral trait. However, it does not mention side effects (e.g., whether the tag is also removed globally), error behavior for nonexistent tags/targets, or idempotency, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the verb and resource, then adds a second sentence for the return value. There is no wasted wording, and the purpose is immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter mutation tool, the description covers the core action and return value. However, it omits edge-case behaviors (e.g., what happens if the tag doesn't exist on the target) and does not elaborate on the output schema beyond stating the returned list. Given the low complexity and presence of an output schema, this is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate by explaining the parameters. It does not: 'tag' and 'target_id' are only named, with no format, examples, or clarification (e.g., whether tag is an ID or name). The agent must infer meaning from names alone, which is insufficient given the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove a tag'), the resource ('from one target'), and the scope ('one target', not bulk). It distinguishes itself from siblings like tags_add_to_target (adds) and tags_bulk_assign (bulk assignment) through the explicit 'remove' and 'one target' phrasing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for removing a single tag from a single target, but does not explicitly address when to choose this over related tools like tags_bulk_assign or tags_delete_globally. No exclusions or alternative conditions are provided, leaving selection partly to inference.
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?
With no annotations, the description carries the behavioral burden. It does disclose the AND combination of criteria and the absence of a tag filter, which is useful. However, it does not explain what 'queue' implies (asynchronous job, return value, side effects), nor any permissions or preconditions. These gaps are significant for a mutation-like tool, but the description is not contradictory or completely silent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundant phrasing. The main action is front-loaded, and the limitation and alternative are placed at the end. Every sentence earns its place, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, no output schema, and no annotations, the description is incomplete. It does not cover parameter semantics, the return format (e.g., job ID or confirmation), or the asynchronous nature of queuing. While the tag-filter workaround is covered, an agent would have to guess critical usage details, so the description falls short of being a complete guide.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not elaborate on any of the four parameters (only_roots, scan_types, online_only, scanned_before). Schema description coverage is 0%, so the description must compensate entirely, but it only refers to 'given criteria' without explaining field meanings, types, or defaults. The agent is left to infer from parameter names alone, which is insufficient for parameters like scanned_before.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Queue a scan for every target matching the given criteria' and explicitly distinguishes itself from scan_bulk_selected by noting the criteria-based vs. selected-target approach. It names the verb and resource precisely, making it unambiguous which tool fits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-not guidance: the lack of a tag filter is called out, and the alternative workflow (list tags, resolve IDs, use scan_bulk_selected) is concretely described. This gives the agent a clear decision path between this tool and its sibling.
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?
No annotations are provided, so the description carries the full burden. It discloses that it returns all unique tags in use per tenant, which is transparent about the scope. However, it does not mention any side effects (though unlikely for a list), authentication requirements, rate limits, or that it's a read-only operation. For a simple list tool this is acceptable but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. It front-loads the core action ('list unique tags') and adds the scope ('in use across this key's tenant's targets') immediately. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, an output schema is present, and the scope is clearly stated ('across this key's tenant's targets'), the description is complete enough for an agent to call it without further clarification. It lacks only a note about read-only behavior, but that is not essential given the sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema reflects that with 100% coverage. The description adds no parameter information, but none is needed. Per the rubric, a baseline of 4 is appropriate when there are no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('list') and resource ('unique tags currently in use across this key's tenant's targets'), which is specific enough. It does not explicitly distinguish from sibling tools, but the siblings are all mutation tools (add, remove, delete, assign), so the read-only nature is implied. This earns a 4 rather than a 5 because it doesn't name alternatives or explicitly note that it's a read operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives. However, the purpose is self-evident – it lists tags, while all sibling tags_* tools are mutations. This implies usage for viewing current tags, but there is no mention of prerequisites, filters, or when not to use it. Adequate but lacks explicit 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that archiving stops scanning, is fully reversible via restore_target(), and is not destructive. This conveys the key side effect and persistence semantics, though it doesn't mention potential edge cases or additional state changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose (archive targets), immediately clarifies the effect (stops scanning), and adds crucial reversibility and non-destructiveness info. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential purpose and non-destructive nature, but given there is no output schema or annotations, it does not mention return values, success/failure indicators, or any batch limitations. For a simple bulk operation, the core is there, but an agent might lack information on expected outcomes or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. While the name 'bulk_archive_targets' and the phrase 'Archive targets' imply the parameter is the list of target IDs, the description does not explicitly explain target_ids or its format. The meaning is inferable, but it lacks direct parameter documentation, so it only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Archive') and resource ('targets'), with an explicit effect: stops them from being scanned. It also distinguishes itself from destructive operations by noting it's reversible and non-destructive, which differentiates it from tools like bulk_delete_targets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (temporarily stop scanning, reversible later) but does not explicitly state when to use this tool versus alternatives like bulk_blocklist_targets or bulk_delete_targets. It mentions restore_target as the reverse operation but gives no explicit exclusions or conditions, leaving the choice somewhat inferential.
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?
With no annotations provided, the description carries the full burden for behavioral disclosure. It does disclose a useful limitation (only a count, not module names) and the trigger condition (circuit-breaker tripped). However, it does not explicitly state whether the call is read-only, has side effects, or any performance expectations. As a 'list' operation it is likely safe, but that is not stated, so the description is only partially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single run-on sentence with multiple clauses and asides, making it structurally messy. Phrases like 'surfaced as part of the same queue-status data queue_status() returns, exposed here as its own discoverable tool' are redundant and convoluted. It could be split into clearer, more concise sentences without losing meaning. It's not overly long, but the structure harms readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Because there is no output schema, the description must specify the return format. It says 'only a count is available' but does not state how that count is returned (e.g., a JSON object with a 'count' field or a plain integer). It also does not explicitly mention the result when no modules are rate-limited (presumably 0). While it references queue_status as a source, the description is not fully self-contained for an agent without prior knowledge of that tool's output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, which sets a baseline of 4 on this dimension. Since there are no parameters, the description cannot add parameter-specific meaning, and none is needed. The baseline is appropriate and nothing detracts from it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it returns the count of scanner modules currently rate-limited by an external target's API. It explicitly distinguishes itself from queue_status by being a focused, discoverable tool for the common 'is anything rate-limited right now' question, and it notes the limitation that only a count is available, not module names. This is specific, unambiguous, and easily separable from 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it is intended for the frequent question of whether anything is rate-limited, and it mentions that the data is part of the same queue-status data that queue_status() returns. This implies that for a full status report, one would use queue_status, while this tool is for a quick count. However, it does not explicitly state 'use this instead of queue_status when you only need the count,' leaving a small gap.
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 no annotations, the description carries the full burden. It discloses that the tool does not queue anything, a key behavioral trait, and explains the scanned_before semantics (matches targets scanned before date or never scanned). It implies non-destructive behavior via 'counting' and 'without queuing', though it doesn't explicitly state all side effects. Still, it provides 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the core purpose ('Count how many targets match... without queuing anything') and then providing targeted parameter detail. Every sentence adds value, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no annotations and no output schema, the description is incomplete. It explains the usage and one parameter, but omits details on the other two parameters, the return type/format, any constraints, or potential errors. An agent would need additional information to confidently invoke it correctly, especially regarding the boolean flags and expected output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It only explains 'scanned_before' with an example and semantics, but does not explain 'only_roots' or 'online_only'. These boolean flags are not self-explanatory in context (what constitutes 'roots' or 'online'?), leaving the agent with ambiguous meaning. The description compensates only partially for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool counts matching targets without queuing, using a specific verb (count) and resource (targets), and explicitly distinguishes itself from scan_bulk_by_criteria by noting it should be used before that tool. This makes the purpose unambiguous and differentiates it 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'use before scan_bulk_by_criteria to see the blast radius first.' It identifies the primary alternative and the condition for its use. It does not enumerate all alternatives, but the main one is covered, and 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral burden. It does disclose a significant side effect ('finding-or-creating the Target') and lists exactly which modules run for each profile. However, it does not mention whether the scan is synchronous/asynchronous, what it returns (e.g., scan ID), or any potential error conditions. It adds value but leaves key operational behaviors uncovered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph with an front-loaded action and a well-formatted list of profiles. It is efficiently written with no redundancy, and the profile section is easy to parse. The only minor inefficiency is that profile details could be considered verbose, but they are directly useful for selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (find-or-create behavior, profile-dependent module execution) and lack of annotations or output schema, the description covers the core functional aspects well. It addresses the creation side effect and module scoping. It does not describe the return value or how to track progress, but these might be covered by sibling tools like get_scan_status. Overall, it is complete for a scan-trigger operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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. It does explain 'profile' thoroughly with all valid values and their module effects. 'target_url' is explained as 'a URL' and the behavior 'by domain' clarifies its expected semantics. While it doesn't specify exact format (e.g., must include scheme), the meaning is clear enough for an agent to use it correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Trigger a scan'), the resource ('a URL'), and an explicit behavioral nuance ('finding-or-creating the Target by domain'). This distinguishes it from the sibling scan_trigger_by_target_id, which presumably operates on an existing target ID, so an agent can tell them apart without extra context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. It implies that if you have a URL and need a scan, this is the tool, and the profile explanation gives some selection context, but there is no explicit guidance on when to prefer scan_trigger_by_target_id or any conditions to avoid this tool. The usage context is inferred rather than direct.
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 no annotations provided, the description carries the full burden. It discloses that the tool returns live status if a scan is running, otherwise the last known state, and provides example states like 'idle' and 'queued'. This gives a clear behavioral picture without contradicting any annotations (none exist).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the purpose and includes the key behavioral detail (live vs last known). Every word earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the essential behavior: what it returns and the distinction between live and last-known status. It mentions possible states, but does not address error handling or return structure. Still, it is sufficiently complete for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no description for target_id and coverage is 0%, so the description must compensate. It says 'for a target', which maps target_id to the target entity but does not explain the integer format or any constraints. This provides minimal but essential meaning, falling short of full compensation for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves scan status for a specific target, using a specific verb (get) and resource (scan status). It distinguishes from sibling tools like queue_status by specifying 'for a target', making it unambiguous which tool to use for per-target status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a target_id, but it does not explicitly mention alternatives or when not to use it. There is no contrast with queue_status or other sibling tools, leaving the agent to infer the appropriate context without direct 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 no annotations, the description carries the burden of behavioral disclosure. It reveals that results are ordered newest first and that limit is capped at 100 server-side, which is important behavioral context. However, it doesn't mention error behavior, pagination, or read-only semantics, but the 'get' verb implies safety. Overall, it adds meaningful value beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that packs the essence: what, scope, ordering, and a server-side constraint. It is front-loaded with the core action and every phrase earns its place. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential aspects needed for correct invocation: the meaning of changes, ordering, and the limit cap. It does not explain error handling or prerequisites, but given that an output schema exists (so return format is covered) and the tool is a simple read operation, the description is quite complete. A slightly fuller note on how to interpret the 'new/changed/removed' categories would push it to 5, but it's sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 clarifies 'limit' with the cap note and implies its usage, but it does not explicitly explain 'target_id' beyond being an identifier (which is fairly self-evident from the name). It also describes the result content ('new/changed/removed findings'), which indirectly helps. Given the low coverage, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('get'), the resource ('target changes'), and the exact nature of those changes ('new/changed/removed findings across scans'), plus the ordering ('newest first'). This distinguishes it from siblings like scan_get_findings (which presumably lists all findings) and get_target (which retrieves target details). It is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to see recent changes) but does not explicitly mention alternatives or exclude cases. It states 'across scans' to clarify scope but gives no guidance on when to prefer this over scan_get_findings or other listing tools. The context is clear, but explicit routing is missing.
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 no annotations, the description carries the full burden of behavioral disclosure. It clearly warns that the operation is irreversible and 'no undo,' requires the 'destructive' scope, and mandates confirm=True to actually execute. This directly addresses the mutation's severity and the guardrail for safe execution. It doesn't elaborate on side effects beyond the primary action, but the core behavioral traits are well-covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tight sentence that front-loads the core action before addressing the safety and confirmation requirements. Every word contributes to clarity, with no redundancy or filler. It's an exemplary model of concise, well-structured tool documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description is nearly complete. It covers the operation's scope, irreversibility, required scope, and confirmation mechanism. It doesn't specify the response format, but without an output schema that's not essential. It also omits edge-case behavior (e.g., missing tag), which a caller might infer. Overall, it provides all critical operational context an agent needs 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must clarify parameters. It explicitly explains the confirm parameter ('Set confirm=True to actually perform this'), which is critical for safety. However, it does not elaborate on tag_name beyond the action context, leaving the agent to infer its role from the overall meaning. Since the schema already defines the types and names, the description adds meaningful value for confirm but not for tag_name, making it adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Remove a tag from every target in this key's tenant that has it.' It specifies the verb (remove), resource (tag), and scope (every target in the tenant), which distinguishes it from related tag tools like tags_remove_from_target (which likely targets a single resource) and tags_bulk_assign (which adds tags). This is a precise, unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides contextual clues about when to use this tool—it is global, irreversible, and requires destructive scope—but does not explicitly name alternatives or state when not to use it. An agent must infer that for targeted removal, tags_remove_from_target would be appropriate. The guidance is implicit rather than explicit, so it's adequate but not fully directive.
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?
With no annotations provided, the description carries the full burden. It describes the output fields but does not disclose any side effects, permission requirements, or rate limits. However, as a read-only summary getter, the behavior is mostly implied; the description adds value by enumerating return contents, but it could mention that it does not modify data or require special auth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core purpose and output fields, then two clear directives for alternatives. Every sentence earns its place, with no redundant fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with one parameter, the description is remarkably complete: it explains the return contents, routes to alternatives, and even warns about a sibling's scope. Given the lack of an output schema, it gives the agent enough to correctly invoke and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, target_id, has no description in the schema (0% coverage), and the description does not explain it beyond implying a target identifier. Since the schema provides no help, the description should at least state that target_id is the unique integer ID of the target, but it does not. This leaves the agent to infer from context, making it insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a 'lean summary' of a single target, enumerating specific fields (domain, scan status, tags, archive state, creation/last scan dates, module count). It distinguishes itself from siblings by explicitly naming scan_get_findings and get_target_changes, so an agent knows exactly what this tool does versus others.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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 (for a summary) and when not to: it points to scan_get_findings for per-module data and get_target_changes for change history. It also warns about scan_get_findings returning tenant-wide data, which helps the agent filter properly. This is high-quality routing.
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?
With no annotations provided, the description must bear the full burden of behavioral disclosure. It does disclose the tenant restriction and the statuses it applies to (queued/reserved/active), which is useful. But it does not state whether cancellation is reversible, what happens if an active task is cancelled mid-scan, or what the response indicates — gaps that matter for a mutation tool with no annotation 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero filler. The action and target are front-loaded, and the two critical constraints (source of ids, tenant scope) are packed in without bloating the text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter cancellation tool with no output schema, the description covers the essential operational details: what it cancels, how to get the id, and the tenant restriction. Minor gaps remain around success/failure signaling and post-cancel behavior, but these are modest given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the schema only shows task_id as a plain string. The description compensates by explaining task_id is a Celery task id and explicitly tells the agent where to obtain valid values (queue_status's active_tasks/reserved_tasks), adding real meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (cancel), resource (scan task), and scope (single task by Celery task id). It distinguishes itself from siblings like queue_purge by specifying it operates on one task at a time, and it disambiguates from queue_status by pointing to it as the source of ids rather than the action 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It routes the agent to queue_status to obtain valid task ids and states the tenant-scoping restriction ('Only cancels tasks belonging to this key's tenant'). However, it does not explicitly contrast with queue_purge or other cancellation siblings, leaving the when-not-to-use decision partially to inference.
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 no annotations, the description carries the burden of behavioral disclosure. It explicitly surfaces a non-obvious behavior: the operation is fleet-wide, not tenant-scoped. This is valuable context for an agent deciding whether to use this tool. It does not detail error handling or idempotency, but for a simple queue resume that 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus a short note, both front-loaded and free of filler. Every word adds value, with the scope caveat placed after the core action for emphasis.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema and a simple action, the description is complete. It covers what the tool does and the key contextual caveat (fleet-wide scope). No additional information is needed 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so per the rubric the baseline is 4. The description does not need to add parameter details, and there is nothing beyond the schema to explain. The empty parameter list is fully self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (resume) and the resource (scan queue), and implicitly differentiates from queue_pause by being the inverse operation. The scope note adds precision without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use after a pause but does not explicitly mention queue_pause as the sibling to pair with, nor does it state when not to use it (e.g., if tenant-scoped action is desired). The fleet-wide note hints at a key distinction but stops short of explicit routing guidance.
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 are absent, so the description carries the full burden. It discloses the time-based limitation and the scope (tasks not yet started), which is useful. However, it omits potential failure modes (e.g., what happens if undo_batch is invalid or the 60-second window has passed) and does not state whether the operation is idempotent or reversible. The behavior is described, but not as exhaustively as a mutation tool without annotations might warrant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, tightly packed with the core action and then critical constraints. It is front-loaded with the verb and resource, and every clause carries meaning. No redundant information or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose, the parameter, and the two key constraints (time limit and task state). It lacks explicit information about return values or error handling, but given the simplicity of a single-parameter tool with no output schema, this is a minor gap. The reference to the sibling queue_purge provides the necessary context for when this tool is intended to be used.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description coverage for the single parameter 'undo_batch' (0%). The description compensates fully by explaining that it is 'the undo_batch id from that call's response', giving both the source and purpose of the value. This is sufficient for an agent to know how to obtain and use it correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it re-queues tasks previously purged by a specific queue_purge call, using the undo_batch id from that call's response. This is a specific verb-resource pairing that distinguishes it from sibling tools like queue_cancel_task or queue_purge, and it explicitly references the prerequisite operation (queue_purge).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage conditions: it is only valid within 60 seconds of the purge and only for tasks that hadn't started running. This effectively tells the agent when this tool is applicable. It does not explicitly name alternative tools for scenarios where these conditions fail, but the constraints are unambiguous and sufficient for most realistic decision-making.
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?
Discloses a key behavioral trait: the operation is reversible via restore_target(). It also explains the selection criterion (DNS scan returned empty records). Without annotations, the description carries the burden and does so reasonably, though it omits details about permissions, rate limits, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The core action is front-loaded, and the additional details (tenant-wide, no IDs, reversible) are packed efficiently without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description covers the essentials: the action, the selection criteria, and the recovery path. Minor omissions like potential failure modes or permission requirements are acceptable for this simple automation, but could be added for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the description explicitly clarifies that 'no target_ids needed', which is the only parameter-related information an agent needs. This meets the baseline for 0 params and adds clarifying value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('archive'), resource ('targets'), and the precise condition ('most recent DNS scan returned empty records'). It clearly distinguishes from sibling tools like bulk_archive_targets by emphasizing 'tenant-wide sweep, no target_ids needed', 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use this tool: a tenant-wide bulk operation for dead targets, explicitly noting that no target_ids are required. However, it does not explicitly mention alternatives or state 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so excellently. It explicitly states the irreversibility beyond a 60-second window, what is restorable (domain/tags) versus not (scan history), the required permission scope, and the mandatory confirm flag. This gives the agent a complete picture of side effects and prerequisites before 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (two sentences) and front-loads the most critical facts: permanence and the irreversible consequence. It then efficiently covers the undo window, restorability, permission requirement, and confirmation flag without superfluous text. Every clause serves a purpose, making it exemplary in structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive two-parameter tool with no output schema and no annotations, the description covers the essential context: side effects, irreversibility, undo reference, permission scope, and confirmation requirement. It does not mention error handling or edge cases (e.g., what happens if target_ids are invalid), but given the tool's simplicity and the rich behavioral coverage, it is nearly complete. A mention of the response (e.g., success status) would fully round it out.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Given the schema has 0% description coverage, the description must explain parameters. It explains 'confirm' well ('Set confirm=True to actually perform this'), but it does not explicitly describe the 'target_ids' parameter (e.g., that it's an array of target IDs or how they are specified). The schema only provides a title 'Target Ids' and type, so the description adds value for confirm but leaves target_ids inferred from the tool name, which is insufficient given the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Permanently delete targets and all their scan history/findings' with specific verb (delete) and resource (targets) plus the scope of what gets removed. It distinguishes from siblings like bulk_archive_targets and restore_target by emphasizing permanence and the inclusion of scan history, making the tool's unique 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage context: it notes the 60-second undo window and points to undo_bulk_delete_targets as an alternative, and it specifies the required 'destructive' scope on the API key. It implicitly guides when to use this (permanent deletion) versus alternatives (e.g., archiving), though it doesn't explicitly say when not to use it beyond the irreversibility warning. The confirm flag is also clearly explained as the gate for execution.
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 no annotations, the description carries the full burden. It discloses the key behavioral trait: the pause is fleet-wide and not scoped to the tenant, which is a potentially surprising side effect. It also clearly states the effect on workers. It does not mention what happens to in-flight tasks or whether the operation is idempotent, but for a pause action this is a solid 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The core purpose is conveyed first, followed by a critical scope note. Every word earns its place, and the structure is ideal for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of parameters and output schema, the description provides the essential information: what it does and its fleet-wide scope. It could go deeper on edge cases like side effects on running tasks or permission requirements, but for a simple pause tool, it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is fully covered. The description adds no parameter information, but none is needed. Per rubric, 0 params yields a baseline of 4, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Pause', the resource 'scan queue', and the specific effect 'stops workers from picking up new tasks'. It clearly distinguishes from sibling tools like queue_status (monitoring) and queue_resume (opposite action). The scope note further clarifies 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The note about being fleet-wide and matching YADS's dashboard pause behavior gives important context for when to use the tool. It does not explicitly name alternatives or exclusion criteria, but the scope clarification helps an agent decide whether to call this versus a tenant-scoped operation. The lack of explicit 'when not to use' is the only gap, so 4 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?
With no annotations, the description carries the full burden. It discloses the 60-second time limit and the scope of restoration (domain/tags only, not scan history), giving the agent key expectations beyond the raw operation. It does not mention failure behavior on expired batch, but that is minor for a simple undo 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The main action is front-loaded, followed by the temporal constraint and restoration scope. Every clause adds information, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter undo operation with no output schema, the description covers the prerequisite (undo_batch), the time constraint, and the restoration scope. It omits only error-handling details, which are not critical for correct invocation. Overall, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no description coverage (0%), so the description must compensate. It explains that the single parameter 'undo_batch' is the identifier from the prior delete call's response, which is essential meaning beyond the schema label 'Undo Batch'. This is sufficient given the simple one-parameter case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Re-create'), the resource ('targets deleted by a prior bulk_delete_targets call'), and ties the action to a prior delete call. It also clarifies what is restored (domain/tags only) and what is not (scan history), clearly distinguishing it from the delete counterpart and other restore 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to use: it requires an undo_batch from a previous bulk_delete_targets call and a 60-second validity window. It does not explicitly name alternatives like restore_target, but the bulk-deletion prerequisite implies the appropriate scenario. Lacks explicit exclusion guidance, hence not 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?
With no annotations provided, the description carries the full burden. It discloses irreversibility beyond a 60-second undo window, the requirement for the 'destructive' scope, and the need for confirm=True. This goes beyond a simple 'clears scans' and informs the agent about safety and irreversible side effects. It does not describe potential side effects like impact on scheduled scans or data, but given the single-purpose nature, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The primary action is stated first, followed by critical caveats (irreversibility, scope, confirmation) in a logical order. Every sentence adds essential information, and nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action, safety requirements, and the one parameter. It does not explain return values (no output schema, so not required) or further consequences, but for a single-purpose destructive operation, it provides all necessary information to call the tool correctly. It could mention that it clears both queued and running scans, which it already does, so it is near-complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has only one parameter, confirm, with no description coverage (0%). The description compensates fully by explaining that confirm=True is required to actually perform the action. This directly clarifies the parameter's role and the tool's behavior without confirmation. This is a high-value addition beyond the bare boolean schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (clear), a specific resource (every queued/running scan), and the scope (this key's tenant). It clearly distinguishes itself from siblings like queue_cancel_task (which targets a single task) and queue_pause/resume (which pause/resume rather than clear). The phrase 'for this key's tenant' adds a scoping detail that prevents confusion with tenant-wide 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/5Does 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 want to clear all queued/running scans) and explicitly references queue_undo_purge for the undo window, telling the agent about an alternative for reversal. However, it does not explicitly state when not to use it or contrast it with other queue management tools (e.g., queue_cancel_task for a single task). It provides clear context but lacks explicit exclusions or alternative routing beyond the undo case.
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?
With no annotations provided, the description carries the full burden of disclosure and meets it: it flag the destructive scope requirement, the compound two-part side effect, the non-clean reversal path (restore_target plus manual blocklist removal), the missing-tool limitation, and the confirm=True safety gate. This is rich behavioral disclosure an agent needs before mutating data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action in the first clause, then layers caveats in dependency order. It is dense with qualifiers (exact match, conservative destructive scope, reversal path, confirm gate), but every clause earns its place for a compound destructive action; it reads as appropriately compact rather than padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a compound destructive tool with no annotations and no output schema, the description covers everything an agent needs to invoke it correctly: what it does, how to confirm, why it's destructive, how reversal works, and what tools don't exist. No critical gap remains for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it does for the critical confirm parameter — 'Set confirm=True to actually perform this' explains the safety-gating boolean clearly. target_ids semantics are implied by the action description (the targets whose domains get blocklisted and archived), which adds value beyond the bare 'Target Ids' schema title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a precise compound action — blocklist each target's domain AND archive the target — with exact-match semantics spelled out ('future Discovery runs won't re-add it'). It clearly distinguishes itself from plain archiving by name, so an agent can separate it from bulk_archive_targets and bulk_delete_targets without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear decision context by contrasting with 'plain archiving' and disclosing that no blocklist-management tool exists for reversal, which tells the agent this is the permanent alternative. It stops short of an explicit when-not-to-use statement or naming the sibling tool directly (bulk_archive_targets), but the trade-off framing gives enough selection 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?
Without annotations, the description discloses idempotency (find-or-create), the SSRF restriction, and that it does not trigger a scan. It covers safety and side effects well, though it could mention response format or error conditions, which are not critical given no output 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences with critical information front-loaded; no extraneous words. The core purpose and behavior are stated immediately, followed by restrictions and next steps.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description fully covers purpose, behavior, restrictions, and next steps. Nothing essential is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no description for 'domain', but the description clarifies it is the target's domain and acts as the identifier for find-or-create. It adds meaning beyond the bare string type by implying domain uniqueness and validation context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('add a target by domain') with find-or-create behavior, clearly distinguishing it from scan and other target tools. It conveys the resource and input precisely and differentiates from siblings like scan_trigger.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly notes SSRF blocking for internal/private domains and directs follow-up to scan_trigger_by_target_id() for scanning, providing clear when-to-use and when-not-to-use guidance. This removes ambiguity about appropriate invocation.
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:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/MrMarco74/yads-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server