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

With no annotations, the description carries the burden well: it discloses that expiration is mandatory, that findings reactivate automatically on expiry unless reactivate_expired=False, and that an explicit justification and named approver are required. It stops short of stating permission/auth requirements, keeping it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Front-loads the critical constraint (mandatory expiration) in the opening line. The Args block is long but justified given zero schema coverage; only minor redundancy between the prose and the parameter list.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter mutation tool with no annotations but an existing output schema, the description supplies the missing behavioral and parameter context. It does not explain side effects on related findings beyond expiration or the risk of creating duplicates, leaving a small gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, and the description fully compensates: it documents all 12 parameters, decodes the decision/recommendation enum letters (A/V/M/F/T), specifies the ISO date format and future-date constraint for expiration_date, and lists defaults for reactivate_expired, restart_sla_expired, owner_id, and name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Accept the risk of one or more findings', 'Creates a RiskAcceptance object') with a scope detail. Clear on its own, but it never distinguishes itself from close siblings like create_risk_acceptance or accept_risks_vulnerability, so the agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It offers one directional cue ('Risk acceptance is discouraged in favor of fixing'), which implies the preferred alternative is remediation. However, it names no concrete sibling tool to use instead and gives no conditions for choosing this over close_finding_mitigated or create_risk_acceptance.

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

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 this is a bulk mutation scoped to the current engagement and names the backend endpoint, which is real behavioral context. However, it says nothing about required permissions, reversibility, or whether previously accepted findings are overwritten; for a destructive bulk mutation with zero annotation coverage that leaves gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The core distinction from accept_risk() is front-loaded in the first two sentences, then the Args block documents each parameter economically. The endpoint aside is slightly redundant with the purpose sentence but overall well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained. For a 3-required-param bulk mutation with no annotations, the description covers purpose, scoping, sibling routing, and parameter format, which is nearly everything needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaning beyond the schema by exemplifying the format ('CVE or advisory IDs, e.g. ["CVE-2024-1234"]') and clarifying that accepted_by is a name/email and justification applies to all findings matching those IDs. With no schema coverage and only three params, this is meaningful compensation, though it could say whether IDs are single or comma-separated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource ('Bulk accept risk for findings matching vulnerability IDs') and explicitly names the endpoint used. It also distinguishes the tool from its sibling accept_risk() by spelling out the exact difference: matching by vulnerability_id vs explicit finding IDs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit when-to-use-instead instruction: 'Use accept_risk() instead when you need explicit finding IDs and an expiration date.' It also constrains scope to the CURRENT engagement context, so the agent knows this is engagement-bounded.

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

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 says nothing about permissions required, whether notes are editable/deletable, or the effect of the private flag beyond a tautological restatement. For a mutation tool with zero annotation coverage this is a real gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is short and front-loads the purpose, but the Args section largely duplicates what the schema already exposes, spending words without adding value. It is efficient though somewhat redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained, but for a mutation tool with no annotations and 0% parameter coverage the description omits behavioral context (auth, defaults, editability) and any usage framing. It is inadequate for correct invocation alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but its Args block only restates param names: 'engagement_id: The engagement ID' and 'private: Whether the note is private' are tautologies. Only 'entry: Note text content' adds minor meaning, which is insufficient for three undocumented parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Add a note to an engagement'), making it distinguishable from siblings like add_test_note and add_finding_note by the 'engagement' target. It is clear, though it never explicitly contrasts itself with those near-identical siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus add_test_note, add_finding_note, or list_engagement_notes, and no prerequisites are stated. The agent must infer the context entirely from the tool name.

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

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

With no annotations, the description carries the full behavioral burden, and it discloses almost nothing: it does not say whether an existing key is overwritten or duplicated, whether the change is auditable or reversible, what permissions are needed, or how the mutation affects the finding. 'Add metadata' is the only behavioral content.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The purpose sentence is front-loaded and short, but the Args block is auto-generated filler that re-lists schema fields without adding information, which is noise rather than value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an un-annotated mutation tool with 0% schema description coverage, the description is inadequate: it omits key-collision behavior, permission requirements, and any pointer to list_finding_metadata for reading existing metadata. The presence of an output schema only excuses the absence of return-value documentation, not these gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it only restates parameter names with generic glosses ('The finding ID', 'Metadata key name', 'Metadata value'). It adds no format, constraint, length, or uniqueness semantics — notably whether 'name' must be unique per finding. Output schema exists, so return semantics are correctly omitted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and resource: 'Add metadata to a finding.' It is unambiguous about the operation. However, it does not differentiate from the sibling list_finding_metadata (or the broader finding-edit tools), so an agent must infer the add-vs-read split.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus list_finding_metadata, update_finding, or add_finding_note. There are no preconditions, no mention of required permissions, and no statement of when not to use it.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does add real behavioral context for 'private' (visible only to you and superusers), which the schema does not convey, but it says nothing about required permissions, whether the note can later be removed or edited, or any side effects of the write.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Front-loaded with the one-sentence purpose before the Args block, and there is no filler prose. The 'Args:' docstring scaffolding is slightly verbose but each line carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. For a simple notes mutation the definition is serviceable, but with zero annotation coverage and no mention of permissions, sibling disambiguation, or note lifecycle, it leaves gaps an agent would want filled.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the docstring accounts for all four parameters. Two entries add genuine meaning beyond the schema: 'private' is explained as visibility to you and superusers, and 'note_type' is cross-referenced to list_note_types. The finding_id and entry glosses are largely restatements.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Add a note to a finding'), so the action is unambiguous. It does not distinguish itself from the near-identical siblings add_test_note and add_engagement_note, so an agent must infer the scope from the name rather than the description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this versus alternatives such as add_test_note, add_engagement_note, or add_finding_metadata, nor any prerequisites. The only navigational help is 'see list_note_types', which concerns a parameter rather than usage context.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not explain permissions required, whether notes are appended or replaced, rate limits, or the effect of the 'private' flag beyond its literal name, leaving significant behavioral gaps for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The purpose is front-loaded in one short sentence, and the args block is compact and free of filler. The Python docstring formatting ('Args:') is boilerplate rather than optimized prose, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple three-parameter mutation with an existing output schema (so return values need no explanation), the description covers the core action and params. It remains thin on permissions and side effects, but the tool's low complexity keeps this adequate rather than incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does list all three parameters with brief meanings (test_id, entry, private). The additions are minimal—'test_id: The test ID' is largely tautological—but entry and private gain some clarity not present in the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Add a note to a test'), which is clear and actionable. However, it does not differentiate itself from near-identical siblings such as add_finding_note or add_engagement_note, so the agent must infer which object type applies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use guidance, and no mention of alternatives like list_test_notes or the finding/engagement note tools. Usage is only implied by the tool name.

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

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

No annotations are provided, so the description carries the full disclosure burden for a mutation. It says nothing about whether closing is reversible, what happens to associated tests/findings/notes, whether permissions are required, or whether the engagement is archived or hidden. For a state-changing operation 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.

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

The description is two lines with no padding and the action is front-loaded. The 'Args:' block is boilerplate that partly duplicates the schema, but there is no verbose waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained. But for a destructive-ish state-change tool with no annotations, the description supplies no behavioral context, no usage context, and no param detail—leaving the agent underinformed for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It only restates the parameter name ('The engagement ID to close') without adding format, source, or how to obtain a valid ID. Value beyond the schema's bare 'Engagement Id' property is essentially nil.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a verb and resource ('Close an engagement'), which is clear at a surface level. However, it gives no indication of what 'close' actually means relative to siblings like delete_engagement or update_engagement, so the agent must infer the distinction. The semantics of the state change are left undefined.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides no when-to-use guidance, no preconditions, and no alternatives. An agent looking at close_engagement, delete_engagement, update_engagement, and get_engagement gets nothing telling it which to pick. The one-line description-equivalent is purely nominal.

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

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

With no annotations, the description carries the full burden; it does disclose the default behavior (closure_type defaults to 'mitigated', mitigated datetime defaults to now) and the semantics of the out_of_scope and duplicate flags. It does not mention permissions, side effects such as notifications, or reversibility (the sibling reopen_finding hints closure is not final), so it falls short of full disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Front-loaded one-line purpose followed by routing guidance and an Args block; every sentence adds information, no filler or restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained, and the description covers parameters, defaults, and alternatives well. The remaining gap is behavioral context for a mutation (permissions, side effects, whether reopening is possible), which leaves it just short of complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and 7 parameters are present, so the description must compensate — and it does, documenting every parameter: finding_id, closure_type with its enum values, note, note_type (with a pointer to list_note_types), mitigated (ISO 8601 + default), and the two conditional booleans.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Close a finding') and immediately distinguishes itself from the close_finding_false_positive / _mitigated / _duplicate siblings by declaring a preference for them when the caller is unsure.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the three alternative tools, gives their signatures, and states the condition under which each should be used instead ('use the dedicated tools below when unsure', 'Prefer the semantic aliases'). No inference is required to route correctly.

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

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 doesn't state that closing is a mutating operation that deletes or supersedes the finding, whether it requires permissions, whether the action is reversible, or how duplicates are resolved. The Args block only restates parameter names.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The first sentence is front-loaded and efficient, but the Args block is largely duplicative of the JSON schema and adds little value, inflating the description without earning its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values needn't be explained, but for a mutation tool with no annotations and 0% schema coverage, the description should cover state requirements, permissions, and side effects. As written, it is too thin for the operation's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It defines finding_id, duplicate_of, and note at a basic level, but doesn't explain accepted formats (e.g., whether finding IDs come from list_findings), semantics of 'original (canonical) finding', or note usage constraints. The restatement of the schema parameter names with no added semantic detail leaves the agent guessing about validity and constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource+operation: closes a finding as a duplicate of another. The sibling set contains close_finding, close_finding_false_positive, close_finding_mitigated and reset_finding_duplicate_status, but the description is specific enough that an agent can route to it without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the purpose but gives no guidance on when to use this tool vs. the sibling closures or vs. get_finding_duplicates. Nothing states prerequisites, prerequisite finding states, or when the operation is inappropriate.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not disclose that this is a mutating, state-changing operation on a finding, whether it is reversible (reopen_finding exists but is not referenced), or what permissions/effects apply. A mutation tool with zero annotation coverage needs far more disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The one-line purpose is front-loaded and followed by a compact Args list with no wasted sentences. The 'recommended' hint on note and the cross-reference on note_type are efficient and earned.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the four parameters are addressed at a high level. But for a destructive/mutating close operation with no annotations and no schema descriptions, the description omits reversibility, side effects, and when to prefer sibling close variants, leaving meaningful gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it partially does: it explains note as 'Why this is a false positive', points note_type to list_note_types, and clarifies out_of_scope. However, finding_id is only restated ('The finding ID to close') with no guidance on where to obtain it, and the note_type cross-reference is helpful but thin.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Close a finding as a false positive') and names the exact disposition, which cleanly distinguishes it from siblings like close_finding_duplicate and close_finding_mitigated. An agent can discriminate between the close_finding_* variants without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use it (a finding determined to be a false positive) but never states when not to use it or routes the agent to the sibling close tools for other dispositions. The '(and optionally out of scope)' clause hints at a secondary behavior but does not say when that should be set.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose useful traits: 'mitigated' defaults to now server-side, 'note' is recommended, and note_type points to list_note_types. However it says nothing about permissions or reversibility (reopen_finding exists as a sibling), leaving meaningful gaps for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Purpose sentence is front-loaded and every parameter entry earns its place. The Args block is slightly verbose but standard and non-redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained. For a mutation tool with no annotations, the definition documents every parameter, defaults, and a cross-reference, which is nearly sufficient; only permission and reversibility context is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate, and it does document all four parameters with meaning: finding_id, note (how/where fixed, recommended), note_type (ID, cross-referencing list_note_types), and mitigated (ISO 8601, server-side default). The cross-reference and default behavior add real value beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Close a finding') and names the reason ('because the vulnerability was remediated (fix applied)'), which implicitly distinguishes it from close_finding_duplicate and close_finding_false_positive. It stops short of explicitly routing the agent away from those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The reason clause ('remediated/fix applied') implies the correct scenario for this tool versus other close_* variants, but there is no explicit when-to-use or when-not-to-use guidance and no named alternatives. Usage is only implied.

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

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 doesn't mention permissions required, whether the operation is idempotent, what happens on duplicate names, or what the response contains. The parameter list gives some idea of what can be set, but there's no behavioral context beyond that. An output schema exists but the description doesn't reference it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is front-loaded with the main purpose, followed by a parameter list. The parameter explanations are minimal, and some are redundant. It's not overly verbose, but the structure is just a flat list without grouping or emphasis on required vs optional. Every line does serve to document a parameter, but the overall conciseness is undermined by low information density in the parameter descriptions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a 14-parameter creation tool with no annotations, 0% schema description coverage, and an output schema, the description is incomplete. It doesn't explain required vs optional parameters (though the schema does), doesn't mention permissions, doesn't describe the return value (though output schema exists), and doesn't guide on usage context. For a mutation tool with this complexity, the description should do more to inform safe and correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% – the input schema only has parameter titles with no descriptions. The description does list each parameter with a brief explanation (e.g., 'target_start: Target start date (YYYY-MM-DD)'), which adds meaning beyond the schema, especially the date format. However, many explanations are tautological (e.g., 'description: Description', 'lead_id: Lead user ID') and don't fully compensate for the lack of enum details (engagement_type, status values are mentioned but not constrained) or format specifics for other fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb+resource: 'Create a new engagement.' This is specific and unambiguous, and the sibling set contains create/update/delete/list/get engagement tools. However, it doesn't distinguish this tool from siblings like update_engagement or create_test beyond the verb, which it does sufficiently for a create operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no when-to-use guidance whatsoever. It doesn't say when to create an engagement versus importing scans (which may auto-create engagements), nor does it state prerequisites like requiring a product to exist first. There are no alternatives mentioned despite siblings like import_scan and reimport_scan that might create engagements implicitly.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it largely falls short. It confirms the mutation ('Create') but says nothing about permissions required, whether the call is idempotent, what happens on duplicate titles, or any rate/side-effect considerations; the only behavioral hints (active defaults True, verified defaults False) are already present as schema defaults.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The one-line purpose is front-loaded correctly, but the body is a raw Args dump rather than curated guidance. Most lines add no information beyond the parameter name, so the block is longer than its informational value warrants.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 19 parameters, no annotations, and an output schema (so return values need not be explained), the description should at least cover invocation context and key parameter semantics. It nominally touches every parameter, which is the minimum, but leaves the agent without usage context or relationship to sibling finding tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 19 parameters, so the description must compensate, and it only partially does. It usefully supplies the severity vocabulary (Critical, High, Medium, Low, Info) and the numerical_severity scale (S0-S4), which the schema lacks as enums, but most other entries are bare restatements of the property name ('component_name: Affected component', 'cwe: CWE identifier number').

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence 'Create a new finding' gives a specific verb and resource, so the operation is immediately identifiable. However, it offers no differentiation from the many sibling tools that also act on findings (update_finding, get_finding, list_findings, delete_finding), so an agent gets no help routing between them beyond the verb.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says nothing about when to use this tool versus update_finding, import_scan, or the various close_finding_* tools. There is no statement of prerequisites, such as the fact that test_id must reference an existing test, nor any exclusion guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden for a creation/mutation tool. It does not disclose whether credentials are stored, whether the tool validates a live JIRA connection, what side effects occur, or what permissions are needed. Only the parameter list adds any substance, which is semantic rather than behavioral.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The purpose statement is front-loaded in a single line, followed by a clean Args block. Given the 0% schema coverage, enumerating the parameters earns its place. It is slightly list-heavy but wastes no words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. For a 12-parameter mutation tool with no annotations, the parameter documentation is adequate but the description omits prerequisites, auth expectations, and side-effect behavior, leaving meaningful gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate and largely does: it explains all 12 parameters, including non-obvious ones like epic_name_id ('Custom field ID for epic name'), open/close_status_key ('Transition ID'), and the severity-to-priority mappings. It adds real meaning beyond the bare schema titles, though it omits format details (e.g., expected URL format, integer ID ranges).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear specific verb and resource: 'Create a new JIRA instance configuration.' An agent can distinguish this from read siblings like get_jira_instance and list_jira_instances. However, it does not explicitly name or contrast with those siblings, so it earns a 4 rather than 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites (e.g., required JIRA server access or admin permissions), and no mention of alternatives such as get_jira_instance or list_jira_instances. The description simply asserts what the tool does without helping the agent decide when to select it.

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

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

With no annotations, the description carries the full behavioral burden, yet it only implies a creation/mutation. It says nothing about required permissions, uniqueness or duplicate-name behavior, side effects, or error conditions for a write operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The lead sentence is front-loaded and the description is short. The Args block largely duplicates the input schema titles, adding bulk with little value, but it is not egregiously long.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be described. But for a creation tool with no annotations and 0% parameter coverage, the description omits auth requirements, duplicate handling, and field meaning, leaving the definition under-specified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It lists the four parameters but only restates their titles ('name: Organization name', 'description: Description', 'critical_product: Is critical product flag'), adding no real semantics such as what 'critical product' or 'key product' actually mean.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Create a new organization'), which is clear enough on its own. However, the parenthetical '(product type)' is ambiguous and, rather than distinguishing this tool from the sibling create_product, it muddies the relationship between the two. No sibling differentiation is provided.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no when-to-use guidance, no prerequisites, and no mention of alternatives such as create_product or update_organization. The agent is left to infer the context entirely from the tool name.

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

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

With no annotations, the description carries the full burden. It implies a write operation, but doesn't disclose permission requirements, whether the created product is immediately usable, what side effects occur, or what the response contains (though output schema exists). 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.

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

Reasonably concise and front-loaded. The parameter list is structured and readable, though the format (Args: name: ...) is somewhat raw. It doesn't waste words but could be slightly tighter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema, the description needn't explain return values. It covers all parameters, which is good. However, for a create tool with no annotations, it lacks important context: whether an organization must exist, permission requirements, and any constraints. It's minimally adequate but incomplete for a mutation tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It helpfully enumerates all 10 parameters with brief explanations and, crucially, provides allowed values for lifecycle, platform, origin, and business_criticality, which are plain strings in the schema (no enums). This adds real meaning beyond the schema. However, the descriptions are terse and don't fully document required/optional status or formats.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource: 'Create a new product (asset)'. This distinguishes it from siblings like update_product, delete_product, and list_products. However, it doesn't clarify the relationship between 'product' and the security/scanner domain context established by other sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs. alternatives. There's no mention of prerequisites (e.g., an existing organization), or when a product should be created. Nothing tells the agent when this is the appropriate action.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose key traits beyond the schema: this is a low-level operation, accept_risk enforces expiration, and reactivate_expired/restart_sla_expired control what happens to findings when an acceptance expires. However, it omits permissions required, side effects on the accepted findings, failure modes, and reversibility.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The purpose and alternative-tool guidance are front-loaded, and the remaining content is an efficient Args list where each line earns its place. The description is dense but appropriately sized for an 11-parameter tool with zero schema descriptions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained. For a complex creation tool with 11 undocumented parameters and no annotations, the description covers purpose, alternative, and all parameters well. It still lacks behavioral coverage around permissions and side effects, which is the main remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must fully compensate. It documents all 11 parameters with meaningful semantics: what each field represents, valid recommendation/decision codes (A, V, M, F, T), expiration date format, default values for the boolean flags, and which field is mandatory in the recommended alternative.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource: 'Create a new risk acceptance.' The parenthetical immediately distinguishes it from the sibling accept_risk by noting this tool is 'low-level' and that accept_risk enforces expiration, so an agent can route correctly without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to prefer accept_risk because it enforces expiration, giving a clear condition for choosing the alternative. It does not mention the other sibling accept_risks_vulnerability, nor does it spell out precisely when this low-level tool should be used instead (e.g., only when bypassing automatic expiration is required).

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing beyond 'Create'. It does not mention permissions required, whether the test is created in an active state, why an engagement_id is needed, or any side effects. For a 13-parameter mutation 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.

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

The one-line purpose is front-loaded and the Args list is compact and scannable with no filler prose. The listing is mechanical rather than economized, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be documented. What remains missing is the mutation context an agent needs before calling a create tool: required-vs-optional distinction is left to the schema, and permissions/state effects are absent. Adequate as a parameter glossary, incomplete as a tool description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and listing every parameter is a genuine step up from the bare schema. The compensation is shallow, though: entries like 'Test type ID', 'Build identifier', and 'Commit hash' are near-tautological, and only target_start adds real meaning with the '(YYYY-MM-DD or ISO format)' hint. It gives the parameter vocabulary but not identifiers, sources, or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource ('Create a new test'), so an agent immediately knows what the tool does and can distinguish it from update_test/delete_test in the sibling list. However, it makes no effort to differentiate from adjacent create_* tools beyond the resource name, so it stays one notch below top marks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus alternatives (e.g., create_finding or import_scan), no prerequisites such as needing an existing engagement or test type, and no note about which fields are mandatory. The Args block lists what can be passed, not when or why.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not state required permissions, whether the user is immediately active, any validation rules, or side effects. For a write operation creating an identity record, this leaves critical behavioral context undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The first line is appropriately front-loaded and concise. The Args block adds length without value since each line is a tautology of the parameter name. Not excessively long, but the structure wastes lines on redundant labels.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained. However, with no annotations, 0% schema coverage, and a purely tautological Args block, the description is insufficient for a six-parameter creation tool. It is barely adequate rather than complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description is the only documentation. The Args section merely restates the parameter names as human-readable labels ('Username', 'Email address') without adding any semantic detail like format, constraints, or defaults. One required parameter is not called out.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a new user'), which is unambiguous against siblings like create_organization or create_product. It does not explicitly differentiate from update_user or delete_user, but the verb itself does that work.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus update_user or other creation tools, and no prerequisites mentioned. The description simply names the operation without any routing context, leaving the agent to 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.

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

No annotations are provided, so the description carries the full behavioral burden, and it adds nothing beyond the word 'delete'. It does not disclose irreversibility, whether attached tests/findings are cascaded or orphaned, or required permissions — significant gaps for a destructive operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The text is short and the purpose sentence is front-loaded, which is good. The 'Args:' block is redundant boilerplate that restates the single obvious parameter rather than earning its space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained, but for a destructive tool with zero annotations the description should at minimum cover cascade behavior, irreversibility, or preconditions. None of that is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but there is only one parameter and its name is self-explanatory; the description restates it as 'the engagement ID to delete' without adding format or sourcing details. This is adequate but adds no meaning beyond the schema title.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (delete) and resource (engagement), which is unambiguous on its own. It does not, however, differentiate itself from the many other delete_* siblings (delete_organization, delete_product, delete_finding, delete_test), so an agent gets no help choosing among them from the text alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use, when-not-to-use, or prerequisite guidance. Nothing states whether the engagement must be closed or empty first, or that findings/tests inside it may be affected, which matters given the sibling close_engagement and reopen-style tools.

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

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, and it says nothing about irreversibility, cascade effects (notes, metadata), or required permissions. 'Delete' implies a destructive write, but no consequences or safety information is disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is short and front-loads the purpose in a single sentence. The 'Args:' block is boilerplate that restates the schema, but overall there is no wasted prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even with an output schema covering return values, a destructive tool with zero annotations needs to explain consequences, reversibility, and prerequisites. The description omits all behavioral context, leaving the agent under-informed before an irreversible deletion.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the single parameter 'finding_id' already has the title 'Finding Id', so the description's 'The finding ID to delete' adds essentially no new meaning. At minimum it could state the expected ID format or where the ID comes from.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Delete a finding'), which is unambiguous on its own. However, it offers no differentiation from the many sibling mutation/close tools (e.g. close_finding, close_finding_duplicate, delete_test), so an agent cannot self-route on the description alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as closing, accepting risk, or marking a false positive, all of which are relevant siblings. The description only says what the tool does, never when to reach for it over another tool.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it does almost nothing. It does not state whether deletion is irreversible, whether it cascades to child resources (products, engagements, findings), or what permissions are required — all critical for a destructive tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is short and front-loaded, with the operation stated in the first sentence. The Args block is boilerplate but not bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained, but for a destructive, annotation-free tool the description omits the information an agent most needs: irreversibility, cascade scope, and authorization requirements.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for the single parameter, and the description only restates the name ('The organization ID to delete') without adding type, format, or sourcing information. It does not compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Delete an organization'), which is unambiguous. However, it makes no attempt to differentiate itself from sibling destructive tools like delete_user, delete_product, or delete_engagement, leaving the agent to infer the distinction from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. For a destructive operation sharing a namespace with create_organization, update_organization, and get_organization, the agent gets no help deciding when deletion is the correct action versus update or deactivation.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Delete' signals a destructive mutation, but the description says nothing about irreversibility, required permissions, or whether deleting a product cascades to child resources such as engagements and findings — the most important risk for a destructive tool in this hierarchy.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is very short and front-loads the operation, with no wasted prose. The 'Args:' block is boilerplate but harmless, and the whole thing is easily scanned.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained. However, for a destructive, unannotated delete, the description omits cascade behavior, irreversibility, and prerequisites, leaving an agent without the information needed to invoke it safely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, yet it only restates the parameter name ('The product ID to delete') without adding type, format, or source context (e.g., whether it comes from list_products/get_product). Minimal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Delete a product'), making the operation unambiguous. It does not differentiate itself from the many sibling delete tools (delete_engagement, delete_user, delete_test, delete_risk_acceptance), but the resource is clear enough that an agent can route to it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives, nor any preconditions. It does not warn that this is irreversible, does not mention whether dependent engagements/findings must be removed first, and does not point to any related tool.

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

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

No annotations are provided, so the description carries the full behavioral burden. Beyond the word 'Delete' implying a mutation, it discloses nothing about irreversibility, required permissions, or whether the acceptance can be restored — all critical for a destructive operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is short and the core action is front-loaded, which is good. However, the 'Args:' block is pure restatement of the schema and adds no value, so space is spent without earning it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained. But for a destructive, unannotated single-parameter tool, the absence of any warning about irreversibility, permissions, or side effects leaves a meaningful gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it only restates the parameter name ('risk_acceptance_id: The risk acceptance ID') — information already conveyed by the schema property title. No format, origin, or lookup guidance is added.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Delete a risk acceptance'), which is unambiguous. However, it does not differentiate itself from the closely related siblings expire_risk_acceptance and reinstate_risk_acceptance, so it lacks the sibling-awareness a 5 would require.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to delete versus expire or reinstate a risk acceptance, nor any mention of prerequisites or consequences. The agent is left to infer usage entirely from the tool name.

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

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

No annotations are provided, so the description carries the full behavioral burden. "Delete" implies a destructive, likely irreversible mutation, but the description says nothing about cascade effects on associated findings/notes, required permissions, or reversibility. It adds only the bare operation name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Very short and front-loaded; the operation is stated in the first line and the argument list follows. There is no padding, though the Args block itself carries almost no information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained, but for a destructive tool with zero annotation coverage the description omits side effects, scope of deletion, and permission requirements. What remains is insufficient for an agent to call this safely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the single param is documented only as "The test ID to delete," which restates the param name and the schema title "Test Id" without adding meaning such as format, source, or where to obtain the ID.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Delete a test"), which is unambiguous against siblings like get_test, create_test, update_test, and list_tests. It does not explicitly name an alternative, but the delete semantics are clear from the verb.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no prerequisites, and no exclusions. Nothing tells the agent whether this is the right call versus update_test or whether related objects must be handled first.

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

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

No annotations are supplied, so the description carries the full behavioral burden. It does not state whether deletion is permanent, whether it requires elevated permissions, whether associated data (tests, findings, notes) is cascaded, or whether it is reversible. 'Delete' implies destruction but no consequence detail is given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Very short and front-loaded, which is good, but the 'Args:' block largely duplicates the schema and the overall text is under-specified rather than efficiently informative. Adequate structurally with no waste to cut, but no substance added.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. However, for a destructive tool with zero annotations and no permission/cascade/reversibility context, the description is thinner than the operation warrants. It is minimally complete but leaves significant behavioral gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It restates the single required parameter ('user_id: The user ID to delete') but adds no meaning beyond the property name and type already in the schema. Marginal value only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Delete a user'), which is clear on its own. However, it offers no differentiation from siblings like delete_organization, delete_product, or delete_engagement, and nothing distinguishes it from update_user semantics beyond the verb. Minimum viable clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use, when-not-to-use, or alternative guidance is provided. For a destructive, irreversible operation there is ample opportunity to explain context (e.g., use update_user to deactivate instead, or confirm authorization) and none is taken.

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

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 does disclose the key side effect (reactivates findings), which is valuable, but does not state permission requirements, reversibility, or whether already-expired acceptances error out.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The one-line summary is front-loaded with the critical side effect, and the Args block is minimal. Slightly mechanical formatting adds minor overhead but no real waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists so return values needn't be explained, and the side effect is covered. But with no annotations and 0% schema coverage on a mutation tool, the definition leaves permissions, error cases, and interaction with delete/reinstate siblings unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate; it names both parameters and clarifies that reason is optional, but adds no format, constraints, or meaning (e.g., whether reason is stored in audit history) beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (expire a risk acceptance) and immediately clarifies the consequence (reactivates its findings), which distinguishes it from siblings like delete_risk_acceptance or reinstate_risk_acceptance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The parenthetical 'reactivates its findings' implies when this is used (ending risk acceptance before natural expiry), but there is no explicit when-to-use vs. delete_risk_acceptance or reinstate_risk_acceptance, and no mention of conditions or prerequisites.

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

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

With no annotations, the description carries the full behavioral burden, and it partially meets it by disclosing the real performance trait 'May be slow for large queues'. It still omits the read-only nature, whether it touches or resolves tasks, and any pagination or timeout behavior, which matters for an operation the description itself warns can be slow.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Three short declarative sentences, with the core purpose front-loaded and the performance warning following immediately after. Every sentence carries distinct information: purpose, payload, and cost.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description does not need to enumerate return fields. It covers purpose, output shape at a high level, and a meaningful latency caveat; the remaining gap is sibling differentiation from get_celery_status.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so per the baseline rubric the schema is the only concern and the description has nothing extra to document. There is no parameter-level ambiguity for the description to resolve.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Get per-task breakdown of the Celery queue', with the unit of granularity (per-task) distinguishing it from a generic status call. It does not, however, name or contrast with the closest siblings get_celery_status, purge_celery_queue, or purge_celery_task, so the agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance and no named alternative. The description never explains how this differs from get_celery_status or when a task-level breakdown is preferable, leaving routing entirely to inference from the tool name.

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

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

No annotations are provided, so the description carries the burden. It discloses the three return categories (liveness, queue length, configuration), which is useful, but says nothing about freshness, cost, permissions, or whether it is read-only. Adequate but with clear gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two sentences, front-loaded with the purpose, then a compact enumeration of the return values. Nothing wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description needn't explain return structure, and it sensibly summarizes the return categories instead. Combined with zero parameters this is largely complete; only the missing sibling differentiation and usage context keep it short of 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Parameter count is 0, so the baseline is 4. The description correctly introduces no parameter concepts and needs none.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (get) and resource (Celery worker and queue status), and names the returned fields. Siblings get_celery_queue_details and purge_celery_queue are related, but the description doesn't explicitly differentiate itself from get_celery_queue_details, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no conditions, and no mention of alternatives despite get_celery_queue_details being a clear sibling for queue-specific inspection. The agent is left to infer that this is the general overview tool.

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

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

No annotations are supplied, so the description carries the behavioral burden. 'Get' reasonably implies a read-only, idempotent operation, and with no parameters there is little that could be destroyed or misconfigured. However, it says nothing about authentication requirements or whether the result is scoped to the caller's session, leaving the safety/behavior profile to inference.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

A single well-formed sentence with no filler, and the distinguishing scope qualifier sits immediately after the verb-resource core.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read tool with an output schema covering the return shape, the description provides everything needed to invoke it correctly. The only substantial omission is explicit routing guidance relative to get_user/list_users.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, which is the baseline-for-4 case: there is no argument semantics for the description to explain. The schema is empty and consistent with a self-scoped lookup.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Get ... user's profile') and adds a scoping qualifier ('currently authenticated') that meaningfully separates it from the sibling get_user, which takes a user identifier. It stops short of naming that sibling explicitly, so the differentiation is implied rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use statement or named alternative, but the phrase 'currently authenticated user' implicitly tells the agent to pick this over get_user when the caller's own identity is wanted. Usage is inferable rather than spelled out.

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

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

With no annotations, the description carries the full behavioral burden, and it discloses almost nothing: no permission requirements, no error behavior for an unknown ID, no note on whether the returned endpoint is scoped to an org/product. 'Get' weakly implies read-only, but that is inference, not disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The core sentence is short and front-loaded. The 'Args:' block is boilerplate that duplicates the schema's own endpoint_id property, adding bulk without information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple single-entity getter with a one-field schema and an output schema that already documents the return shape, so the bar is low. The description covers purpose and the required identifier, though the absence of any annotation context keeps it from being fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but there is only one parameter and the description's 'The endpoint ID' merely restates the schema field name without adding format, source, or lookup context. For a single trivially-named param this is the minimum viable level.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get a single endpoint by ID'), and the word 'single' implicitly distinguishes it from the sibling list_endpoints. It is clear but does not explicitly name or contrast with any sibling tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this versus list_endpoints or how an endpoint_id is obtained. The agent must infer the lookup use case entirely from the name.

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

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

No annotations are provided, so the description carries the full burden, yet it discloses nothing about behavior beyond the basic lookup: no error/not-found behavior, permissions, or scoping. It is a simple read, but with zero annotation coverage this is thin.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Very short and front-loaded with the core action in the first sentence. The Args stanza is boilerplate but earns its place as the only parameter documentation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value explanation is not needed, and the tool is simple. However, for a get-by-ID tool with no annotations, the absence of error/not-found and ID-sourcing context leaves it only minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter has 0% schema description coverage, so the description should compensate, but 'The engagement ID' merely restates the name and omits that it is an integer or where such an ID comes from (e.g., list_engagements).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get a single engagement by ID'), which distinguishes it from list_engagements and the create/update/delete engagement siblings. It stops short of explicitly naming those alternatives, but the singular scope is clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this versus list_engagements when the ID is unknown, nor any prerequisite about the engagement existing. Usage is only implied by the tool name.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Get' implies a read-only operation, but nothing states whether the call requires specific permissions, what happens on a nonexistent ID, or any other behavioral trait. Given an output schema exists, return format need not be described, but the description adds no behavioral context at all.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is two short lines that are front-loaded with the essential purpose. It is efficient and contains no filler, though the 'Args:' block largely restates the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-entity getter with an output schema present, the description is minimally adequate: the agent knows what it does and what it needs. But it omits sibling differentiation and any parameter format detail, so it is not fully complete for the surrounding tool landscape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the single parameter is only restated as 'The finding ID,' which is essentially a tautology of the parameter name finding_id. No format, range, or origin of the ID is supplied to compensate for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Get) and resource (finding) with the singular scope, so the agent knows it retrieves one entity. However, it does not differentiate itself from the many sibling retrieval tools (list_findings, get_finding_duplicates) that also operate on findings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance is given. The description does not clarify when to fetch a single finding versus using list_findings or get_finding_duplicates, leaving the agent to infer the distinction 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.

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, yet it says nothing about read-only nature, permissions required, or what a 'duplicate' relationship means in this system. The only signal is the weak implication of 'Get' that this is a read operation, which is not enough for a tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is short and front-loads the core action, which is good. However, the Args block is redundant with the schema and the overall text is terse to the point of under-specification rather than deliberate concision.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, but for a tool embedded in a dense finding-lifecycle sibling set with no annotations, the description should clarify prerequisites, the meaning of duplicates, and its relation to close_finding_duplicate/reset_finding_duplicate_status. It omits all of this.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but 'finding_id: The finding ID' merely restates the parameter name and adds no format, source, or constraint detail. An agent gains nothing beyond what the schema already shows.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Get duplicate findings for a given finding,' which is clear enough for an agent to understand the operation. However, it does not distinguish this tool from closely related siblings like close_finding_duplicate or reset_finding_duplicate_status, which also operate on the duplicate concept.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool, what preconditions apply, or how it differs from the numerous sibling finding tools. The agent must infer usage entirely from the name and sibling list.

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

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

No annotations are provided, so the description carries the full burden. 'Get' implies a safe read, but the description says nothing about required permissions, behavior when the instance_id does not exist, or whether configuration data is cached/sensitive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is short and front-loaded with the core purpose, though the Args block adds nothing over the schema and could be trimmed without loss.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and this is a simple single-parameter getter. Still, it lacks any auth/permission or not-found context that would make it fully self-sufficient for a mutation-free admin read.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate, but it only restates the parameter name as 'The JIRA instance ID' and adds no type, format, or lookup-semantics detail beyond what the schema title already conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (get a JIRA instance configuration) scoped by ID, which cleanly distinguishes it from list_jira_instances, create_jira_instance, and update_jira_instance. It does not, however, explicitly name any sibling tool to route against.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as list_jira_instances or get_system_settings. The agent must infer the context entirely from the name.

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

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

No annotations provided, so the description carries the full burden, but it only says it fetches by ID. It does not disclose permissions required, whether missing IDs raise or return null, or any behavioral traits beyond the obvious read.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Very brief and front-loaded with the core statement. The 'Args:' block is slightly redundant given the schema, but overall it's tight and readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained. However, without annotations or usage context, the description is minimally adequate for a simple lookup tool but leaves gaps around error behavior and permissions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and there is one parameter. The description identifies organization_id as 'The organization (product type) ID', which adds a clarification beyond the bare schema, but doesn't explain format or constraints. Baseline for a 1-param tool with no schema descriptions is around 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (get) and resource (organization) with scope 'single' and 'by ID'. Clear enough to distinguish from list_organizations and create/update/delete siblings, though it doesn't name them explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no mention of alternatives like list_organizations for enumeration, no prerequisites. 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.

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 implies a read operation but says nothing about auth/permission requirements, error behavior when the ID does not exist, or any side effects, which is a meaningful gap for a tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The purpose sentence is front-loaded and terse, but the 'Args:' block duplicates what the input schema already declares, so it does not earn its place. The result is brief but not optimally structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (one required integer param) and an output schema exists to describe return values, so the description is not required to explain the response shape. Still, it omits any note on failure modes or lookup semantics, leaving it minimally adequate rather than complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description's 'product_id: The product ID' merely restates the parameter name and type already visible in the schema. No format, range, or source-of-value guidance is added, so the description does not compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Get a single product by ID'), which clearly separates it from the list_products and create/update/delete_product siblings by implying retrieval of exactly one entity. However, it never names those siblings or explains the retrieval scope (e.g., what a 'product' contains), so it stops short of full differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus list_products or get_product-adjacent lookups, and no mention of prerequisites. 'By ID' is the only hint of the usage condition, which an agent must infer.

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

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

No annotations are provided, so the description must carry the full behavioral burden, but it discloses nothing beyond the basic purpose. It does not mention read-only nature, error behavior for missing IDs, permission requirements, or any 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.

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

The description is appropriately sized and front-loaded with the core action. The Args block is minimal and directly documents the sole parameter, with no wasted sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter retrieval tool with an output schema, the description covers the basic purpose and parameter, but it omits usage context and behavioral details such as not-found handling. With no annotations, these gaps are noticeable, though the low complexity keeps it minimally viable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it only restates the parameter name as 'The risk acceptance ID' without adding format, source, or validation details. This is effectively tautological with the schema title 'Risk Acceptance Id' and adds no meaningful semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get') and resource ('a risk acceptance') and clarifies retrieval by ID, which distinguishes it from sibling list, create, update, and delete operations. The purpose is unambiguous for an agent scanning available tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit when-to-use guidance, prerequisites, or alternatives to consider. While 'by ID' implies that an ID is needed, it does not explain when to choose this tool over list_risk_acceptances or other retrieval methods.

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

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

With no annotations provided, the description carries the full behavioral burden, and it discloses almost nothing: it does not say whether settings are instance-wide or user-scoped, whether the call requires elevated permissions, or whether any of the data is sensitive. Only the verb 'Get' weakly implies a non-mutating read.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

A single short, front-loaded sentence with no filler or redundancy. It is appropriately sized, though the repeated 'DefectDojo' brand adds no discriminating information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description need not enumerate return values, and with zero input parameters there is little surface area to cover. It identifies the resource being read, which is enough for an agent to invoke it correctly, though the absence of annotations leaves permission/scope questions unanswered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to clarify beyond what the empty schema already shows. Baseline 4 applies for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description pairs a specific verb ('Get') with a specific resource ('DefectDojo system settings'), so the agent immediately knows it is a read of configuration. It does not explicitly name the sibling write counterpart update_system_settings, but the verb alone signals the read/write distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to call this versus alternatives, no prerequisites (e.g. admin privileges), and no mention of the sibling update_system_settings or the related get_celery_status/get_jira_instance tools. Usage is only implied by the verb.

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

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

No annotations are provided, so the description carries the full disclosure burden and delivers almost nothing beyond 'it retrieves'. It does not state that the operation is read-only, whether it requires authentication or specific permissions, or how a missing/invalid test ID is surfaced. For a lookup tool this is a real gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The one-line purpose is front-loaded and free of padding. The boilerplate 'Args:' block is redundant against the schema but adds negligible length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value documentation is not required. However, with no annotations and no error/not-found behavior described, a mutation-free but failure-prone lookup is only minimally covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the only argument note ('test_id: The test ID') merely restates the schema property name. It adds no information about ID format, where the ID originates, or whether it must be an existing test, so it fails to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Get) and resource (a single test) with the lookup key (by ID), which is unambiguous. It does not differentiate itself from siblings such as list_tests or get_product/get_finding, but the resource is distinct enough that an agent can route correctly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus list_tests (to enumerate tests) or the update/delete_test siblings. There are no stated prerequisites, no mention of what happens if the ID is unknown, and no indication that the ID must come from a prior list call.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing beyond the lookup itself: no permission requirements, no behavior on missing/not-found IDs, no error semantics. It is a bare description with zero added 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.

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

Very short and front-loaded, with the action stated in the first clause. The Args block is somewhat redundant given the single obvious parameter, but the text is not padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the operation is intrinsically simple. Still, with no annotations and no disambiguation from get_current_user, it is only minimally complete for correct tool selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter, and the description's 'user_id: The user ID' merely restates the parameter name with zero schema description coverage. It adds no format details (e.g. integer ID vs username) or clarification beyond what the schema already shows.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get a single user by ID'), and 'single' partially distinguishes it from list_users. However, it never names the closely related get_current_user sibling, so an agent still has to infer which of the two to pick.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no mention of the alternatives (get_current_user, list_users), and no prerequisites or exclusions. The intent is only implied by the tool name.

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

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

No annotations are provided, so the description carries the full burden, and it delivers: it documents that auto_create_context can create products/engagements, that close_old_findings will close findings absent from the new scan, and the push_to_jira side effect. It omits permission/auth requirements and deduplication semantics, keeping it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Front-loaded with purpose and the two hard requirements before the Args block, and the prose is tight. The per-parameter list is long but each line carries distinct information needed for a 24-param tool, so it is not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 24-parameter import with 0% schema coverage and no annotations, the description manages to explain the requirement combinations and the key behavioral toggles. It does not mention auth prerequisites, import processing/async behavior, or how it differs from reimport_scan, but an output schema exists so return values need not be covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 24 parameters, so the description must compensate, and it annotates nearly all of them ('auto-create product/engagement if they don't exist', 'close findings not present in new scan', severity values, group_by values). The bare group_by enumerations and some terse entries (test_title, tags) leave minor gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb+resource ('Import a scan report into DefectDojo'), and the sibling context (reimport_scan) makes the distinction clear: import creates a new test from a report whereas reimport targets an existing one. The agent can tell what this does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit mutually-exclusive requirements: 'Either engagement_id OR (product_name + auto_create_context=True)' and 'Either file_path or scan_data'. This is real routing guidance that prevents common invocation errors. It does not, however, state when to prefer this over the sibling reimport_scan, so it falls short of a 5.

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

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

With no annotations, the description carries the full behavioral burden, and 'list' implies a non-destructive read. It usefully discloses that host and path use contains-matching, which is real behavioral context beyond the schema. It does not state pagination defaults, ordering, or that no writes occur, leaving some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Front-loads the purpose in one line, then lists parameters compactly with no filler. The Args block is slightly verbose but every entry maps to a real parameter and earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and all params are documented. However, the absence of annotations plus no usage guidance leaves the description only minimally complete for a seven-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning — and it does, documenting all seven with intent (e.g., product_id, host, protocol, limit, offset). The '(contains)' annotations add matching semantics the bare schema does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List endpoints with optional filters'), so the agent immediately knows it retrieves a collection. It does not explicitly distinguish itself from the sibling get_endpoint, but the list/get split is self-evident from the name and description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to choose this over get_endpoint or which filters are appropriate for which scenario. The description merely says filters are optional without stating conditions, exclusions, or relationships to sibling tools.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not state that this is a read-only operation, mention permission/auth requirements, or describe pagination defaults or ordering. Only the incidental 'limit'/'offset' params hint at paging.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The one-line purpose is front-loaded and waste-free, but the Args block is low-value filler that mostly echoes parameter names, and there is no additional context to justify the structure. Adequate, not tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The presence of an output schema means return values need not be explained. However, with zero schema coverage and no annotations, the description is thin on behavior and defaults for a five-parameter list tool, leaving the agent with only the bare minimum to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the Args block is the only documentation. It lists all five parameters, but entries like 'Filter by endpoint ID' and 'Filter by finding ID' largely restate the parameter names; only 'Results per page' and 'Pagination offset' add real meaning. It fills the gap minimally rather than fully compensating.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource ('List endpoint statuses') and clarifies the concept with the parenthetical '(relationship between endpoints and findings)', which helps distinguish it from list_endpoints and list_findings. It does not, however, explicitly name a sibling it is not, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use or when-not-to-use guidance. Given the many sibling list tools (list_endpoints, list_findings, get_endpoint), the description never says when an agent should reach for this relationship view instead of another call. Usage is only implied by the name.

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

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 says nothing about ordering, pagination, size limits, or permission requirements for reading an engagement's notes; it only restates the operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The opening sentence is front-loaded and efficient, but the Args block is pure redundancy that adds no information beyond the schema. It is short, yet part of that shortness comes from omission rather than tight writing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained. For a simple one-parameter read tool the description is minimally viable, but it omits any note on result ordering or scope that would help an agent use it confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for the single required parameter, and the description's 'Args: engagement_id: The engagement ID' merely repeats the parameter name without adding format, source, or lookup guidance. It therefore compensates for none of the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb and resource: 'List notes for an engagement.' That is specific enough to identify the operation, but it offers no differentiation from siblings such as list_finding_notes, list_test_notes, or add_engagement_note, leaving the agent to infer the distinction from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this rather than the many other note-listing or note-adding tools. No preconditions, no statement of what it returns, and no mention of how it relates to add_engagement_note or list_note_types.

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

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 never states that this is a read-only, non-mutating operation, nor mentions permissions, default ordering, or total-count behavior. 'List' implies read semantics, but that is left to inference rather than disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The purpose is front-loaded in the first sentence and the Args block is a tight, scannable list with no filler. Nothing is padded, though the block is a little spartan compared to prose that would flow for an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given seven optional parameters, an output schema that already defines the return shape, and no annotations, the description supplies the parameter detail needed to call it correctly. It does not address ordering or the relationship to other engagement-listing views, but the essentials for correct invocation are present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does: it names all seven parameters and adds real meaning such as 'contains' semantics for name, the enumerated status values (Not Started, In Progress, Completed), the engagement_type values (Interactive, CI/CD), and 'Results per page (default 25)' for limit. Minor gaps remain (e.g., how offset interacts with total results).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource ('List engagements') with the clarifying modifier 'with optional filters.' An agent can distinguish it from get_engagement/create_engagement/update_engagement by the plural-list form, though the description never names those siblings as alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this versus get_engagement (singular), list_products, or the engagement-note tools. It only says filters are optional, which describes the shape of the call, not the conditions that select it.

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

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 does not state whether this is a read-only operation, whether metadata is paginated, what format key-value pairs take, or any authentication requirements. For a list tool with no annotations and no output schema explanation (though output schema exists), 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.

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

The description is very brief (two lines) and front-loads the purpose. The 'Args:' section is a standard docstring format but adds little beyond repeating the parameter. It is concise but not maximally informative per sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there are no annotations, an output schema exists (which the description need not explain), and the tool is a simple list operation with one parameter, the description is missing key behavioral context: read-only status, return structure (key-value pairs), and any usage caveats. It is not complete enough for an agent to call with full confidence.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but there is only one parameter. The description repeats the parameter name ('finding_id') and provides the same information as the schema's title ('Finding Id'). It does not add type hints, constraints, or examples beyond what the schema already implies. Baseline is 3 due to low parameter count (1) and minimal room to add value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'List metadata key-value pairs for a finding.' This is clear and distinguishable from the sibling add_finding_metadata (a write operation). It does not explicitly differentiate itself from other list_* tools, but the resource (finding metadata) is specific enough to identify the target.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. It is not stated whether this is the only way to retrieve metadata, nor whether there are related tools for filtering or searching. 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.

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

With no annotations, the description carries the full behavioral burden. It discloses the ordering behavior (newest first), which is a genuine trait beyond the schema, but omits any permission requirements, error behavior for missing findings, or pagination/volume characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Front-loaded core sentence followed by a compact Args block; there is no filler. The Args boilerplate is slightly redundant but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool backed by an output schema, the description is close to sufficient, and the ordering note helps. It still says nothing about what happens when finding_id does not exist or about result size, leaving small gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, yet it only restates 'The finding ID', which duplicates the parameter name and the schema title. No type, format, or example is added.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (list) and resource (notes for a finding), and the name/description distinguishes it from list_test_notes and list_engagement_notes by scope. No explicit sibling differentiation in the text, but the resource is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, prerequisites, or alternatives are offered. The reader must infer from the name that this is the read counterpart to add_finding_note/remove_finding_note; nothing routes them explicitly.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose useful traits such as pagination (limit default 25, offset), server-side 'contains' matching for product_name/title, and that some filters traverse relations ('via test__engagement'). It omits permissions, ordering defaults, or any note on result size/cost.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Front-loaded purpose sentence followed by a clean 'Args:' block where each line maps to one parameter. The length is justified by 23 parameters, though it reads as generated documentation rather than curated guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value explanation is unnecessary, and all parameters are documented. The main gap is the absence of any guidance about alternatives or interaction with sibling finding tools, but for a filtered list operation the definition is largely sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does: every one of the 23 parameters gets an explanation, including enum values for severity, relation traversal paths, and exact-vs-contains matching distinctions. This meaningfully exceeds the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List findings') and clarifies it takes optional filters. However, it does not differentiate from siblings like get_finding, list_finding_metadata, or get_finding_duplicates, so an agent must infer selection from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this tool versus alternatives (get_finding, list_finding_metadata, get_finding_duplicates). The 'optional filters' phrasing implies a broad listing use case, but neither when-to-use conditions nor exclusions are stated.

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