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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered structurally. The description adds nothing beyond that: it does not say what a 'diagnostics' payload contains, what happens if jobs=true and job_id are combined, whether missing IDs error or return empty, or whether results are paginated.

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 front-loaded sentence with no filler, which is structurally good. However, for a three-mode polymorphic tool the terseness becomes under-specification rather than efficiency.

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?

Three optional parameters, no output schema, and three distinct return shapes mean the description needs to explain mode selection and error behavior. It does neither, so an agent cannot reliably invoke this tool correctly on the first attempt.

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 all three parameters, so the description must carry the burden. It hints at the mapping (integration_id → binding, jobs/job_id → diagnostics) but never states precedence, defaults, or that 'parser catalog' apparently requires no parameter at all — leaving the polymorphic selection logic ambiguous.

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 verb 'get' is paired with three distinct resources (parser catalog, integration binding, ingestion job diagnostics), which tells the agent the domain but not how the tool discriminates between them. It is not a tautology, but an agent cannot tell from the description which parameter selects which of the three payloads, so it is only partly distinguishable from siblings like opencdr_settings_get.

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 statement of when to use this tool versus the many sibling getters, and no guidance on when each of the three modes applies. The agent has to infer usage entirely from the parameter names.

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?

Annotations already declare readOnly=true, idempotent=true, destructive=false, so the 'Read-only.' line is redundant. The description does add genuinely useful context about rollback lifecycle semantics (pending/succeeded/failed, error on failure, back-compat mirroring), though most of this is return-value semantics rather than operational behavior such as auth or rate limits.

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 action is stated in the first sentence and the rollback details follow as supporting context. Slightly dense parenthetical enumerations, but every clause carries information about the returned fields.

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 no output schema, the description usefully documents the rollback-related return fields, including the back-compat aliasing rule. However, it leaves the required detection_id argument entirely undefined, which is a real gap for a by-ID fetch 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% and the single parameter, detection_id, is never explained in the description. The agent gets no hint about the format, source, or scope of the identifier (e.g., whether it is the detection ID returned by a list call). With one undocumented required param, the description fails to compensate.

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 specific verb-plus-resource: 'Get a specific executed IR action.' The word 'specific' distinguishes it from opencdr_ir_actions_list without naming it. Clear enough for an agent to tell fetch-by-id from list apart, though naming the sibling would push it to 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 explicit when-to-use or when-not-to-use guidance and no reference to the list tool for discovery. Usage is only implied by the 'specific executed IR action' phrasing. An agent must infer that detection_id comes 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so "Read-only" merely restates structured data and earns no credit. The one genuinely additive piece is that results are limited to executed, rollback-eligible actions, but nothing is said about ordering, result volume, or pagination behavior.

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

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

Two short, front-loaded sentences with the scope constraint stated first. The trailing "Read-only" is the only wasted clause, since annotations already establish 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?

There is no output schema, but for a simple read-only list tool the description conveys the essential filter (executed, rollback-eligible) and the safety profile is fully covered by annotations. The main gap is the absence of any pagination or result-shape hint, which matters given the two undocumented parameters.

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 never mentions the two parameters (page_size, next_token). Their names are conventional enough that an agent can guess pagination, but the description adds no meaning about defaults, max page sizes, or token lifetime, leaving the schema to carry a burden it does not meet.

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 ("IR actions") with a meaningful scope qualifier ("executed, rollback-eligible"), which implicitly separates it from the singular sibling opencdr_ir_actions_get. It does not explicitly name that sibling, so an agent must infer the distinction rather than being routed.

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 phrase "rollback-eligible" implies the use case (finding actions that can be rolled back), but there is no explicit when-to-use guidance, no prerequisites, and no named alternative such as opencdr_ir_actions_get for fetching a single action's detail.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so 'Read-only' merely restates structured data. The description adds nothing behavioral beyond that — no note on what happens when the account has no mapping (error vs. empty), no permission/auth context, no rate or caching behavior.

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

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

Two short sentences, front-loaded with the resource and scope. Minimal waste, though the trailing 'Read-only' is redundant with annotations and consumes part of an already tiny budget.

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 single-parameter read with no output schema, the definition covers the input format and the general return concept, but leaves the shape of the role mapping and the not-found case unspecified. Annotations carry the safety profile, so this is 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% — aws_account_id is documented only by type and title. The description partially compensates by constraining the format to a 12-digit AWS account id, which is real value the schema lacks, but it says nothing about leading zeros, formatting, or validation failures.

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 (IR role mapping) plus the scoping key (a 12-digit AWS account id), which is enough to distinguish it from opencdr_ir_roles_list. It does not name that sibling explicitly, so differentiation is inferred 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?

Usage is only implied: 'for a 12-digit AWS account id' suggests it is the single-account lookup, with opencdr_ir_roles_list presumably for enumeration. There is no explicit when-to-use, when-not-to-use, or prerequisite statement.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the trailing "Read-only." is largely redundant. The description does add real semantic context by explaining what a role mapping actually is (IAM role per AWS account), but it says nothing about pagination behavior even though page_size and next_token are exposed.

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 short sentences, front-loaded with the resource, with the clarifying parenthetical doing real work. The only wasted content is the redundant "Read-only" clause.

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?

A simple two-parameter read tool with no output schema needs at minimum pagination semantics, which are missing. The concept explanation is a genuine plus, but an agent still cannot predict paging behavior or the shape of returned mappings.

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 carries the full burden for page_size and next_token, and it provides no information about either. It does not state that results are paginated, what the default page size is, or how next_token is used to continue — the agent must infer all of this from parameter names alone.

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 IR role mappings") and adds a clarifying gloss explaining that a mapping ties an AWS account to the IAM role the responder assumes. This is clear enough to distinguish it from the plural-list siblings and from opencdr_ir_roles_get, though it never names the get sibling 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?

Usage is implied by "List" plus the absence of any identifier parameter, so an agent can infer this is the enumerate-all variant. But there is no explicit guidance on when to prefer this over opencdr_ir_roles_get or on prerequisites for enumeration.

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?

The only behavioral statement, "Read-only," restates readOnlyHint=true and destructiveHint=false that the annotations already declare, adding no information. Nothing is said about volume, pagination, or whether the list is filtered by account scope.

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 short sentences, front-loaded with the payload. The second sentence is largely redundant against the annotations, so it is not quite waste-free.

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 no-argument read tool this is close to adequate, but with no output schema the description could say what a detection list record contains or how it relates to opencdr_rules_list / opencdr_lists_show. The agent is left to discover the return shape by calling 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?

Zero parameters and 100% schema coverage, so there is nothing for the description to compensate for. Baseline 4 applies.

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 all detection lists"), which is distinguishable from opencdr_lists_show by the word "all". It never names the sibling, though, so differentiation is implied rather than explicit.

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 opencdr_lists_show, opencdr_rules_list, or any other list endpoint. The agent must infer that this is enumeration-only and must open the sibling schemas to confirm.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so "Read-only" merely repeats structured data and adds no value. Nothing is said about error behavior for unknown list_ids, result size, or how pagination works (openWorldHint hints at variability but is left unexplained).

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 terse fragments with no wasted words and purpose is front-loaded, but the brevity comes at the cost of under-specification rather than crispness.

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?

No output schema exists, so the description must convey what a "list's values" look like (shape, size, ordering) and it does not. For a retrieval tool keyed on an undocumented identifier, this leaves the agent guessing.

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?

One parameter with 0% schema description coverage and the description never explains what a list_id is, its format, or how to obtain one. With the schema silent, the description should have compensated and does not.

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?

"Show a list's values" names a specific verb (show/retrieve) and resource (a list's values), which is distinguishable from opencdr_lists_list (enumerate lists) and from the rules_* siblings. It stops short of stating whether this returns raw items or list metadata plus items, but the core intent 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?

Usage is only implied: the required list_id suggests it is called once an ID is known, implying opencdr_lists_list is the discovery step. There is no explicit when-to-use/when-not, nor a named alternative.

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?

Goes well past the readOnlyHint/idempotentHint annotations by disclosing a backend constraint (dedicated indexes, no AND-combination), a hard range cap (max 31-day), default lookback (7 days), pagination via next_token, and a list of unsupported correlation fields. These are behavioral facts the agent could not obtain from annotations or schema.

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

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

Front-loads the purpose in the first line, then in three short paragraphs covers selector rules, date caveats, pagination, and unsupported paths. Dense but every sentence carries operational information; nothing is redundant with the schema or annotations.

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 8-parameter search tool with no output schema and no schema descriptions, the description covers the decision-critical semantics: mutual exclusivity, date scoping, defaults, and pagination. Remaining gaps — result shape, limit bounds, and ordering field — are minor but would help an agent tune queries.

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 carry the load, and it does for service, event_id, event_name, date_from/date_to (YYYY-MM-DD, UTC, inclusive, conditional applicability) and next_token. It leaves limit and order unexplained — no max limit and no statement of which field order sorts on — so two of eight parameters remain semantically opaque.

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 ('Search audit/CloudTrail logs') and immediately flags it as read-only. It does not, however, name opencdr_signals_search or any other sibling, so an agent must infer that this tool covers audit/CloudTrail events rather than detection signals from 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?

Explicitly requires exactly ONE selector and names the three valid choices (service, event_id, event_name). It further states when date filters apply (service only, ignored otherwise), what their defaults are, and redirects unsupported correlation attempts to event_id — a clear use/do-not-use contract.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the description's "Read-only" sentence adds nothing beyond the structured data. Nothing is said about behavior when the id does not exist, whether lookup is scoped to a workspace, or what openWorldHint=true implies about external data reach.

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 clipped sentences, correctly front-loading the action before the constraints. The middle sentence duplicates the annotation and the third duplicates the enum, so it is slightly redundant, but there is no filler.

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 two-parameter read tool with no output schema, the definition is just barely adequate: it establishes the lookup key and the discriminator but leaves the id format, not-found behavior, and response shape entirely unspecified.

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 carries the burden, but it only restates the kind enum ("signal" or "correlation") which is already encoded in the schema. The more opaque parameter, rule_id, gets no format, naming, or sourcing guidance at all.

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?

"Get a rule by id" gives a specific verb and resource, which cleanly separates it from sibling opencdr_rules_list. It does not name the sibling or explain the relationship, but the singular-resource nature of the operation is unmistakable.

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 opencdr_rules_list or the ir_* rules-adjacent siblings, and no prerequisite such as needing a rule id obtained from a list call. Usage is only implied by the phrase "by id".

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the 'Read-only' statement is redundant. The genuinely additive content is the pagination contract — pass the returned next_token to continue — but nothing is said about result shape or ordering, and with annotations carrying the safety profile, this is only moderate added value.

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 sentences, front-loaded with purpose and scope, with no filler. The line breaks around the kind explanation are slightly awkward but the size is appropriate for a three-parameter list tool.

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 no output schema and a 0% schema coverage rate, the description carries most of the burden. It covers filtering and pagination adequately but leaves page_size undefined and says nothing about what a returned rule contains, which an agent needs to plan follow-up calls.

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 explains the semantic meaning of 'kind' (signal vs correlation, omit for both) and how next_token drives pagination, which is real added meaning, but page_size is never mentioned and no value guidance or limits are given.

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 specific verb and resource ('List detection/correlation rules') and immediately scopes it as read-only. It names the sibling opencdr_lists_list as the destination for detection lists, though it does not explicitly contrast with opencdr_rules_get.

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 explicit inclusion criteria for 'kind' ('signal' or 'correlation', omit for both) and routes a related use case to opencdr_lists_list. What is missing is guidance on when to prefer opencdr_rules_get for a single rule versus listing.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Read-only' is essentially a restatement. The only added behavioral fact is the 'global' default scope, which is also present in the schema default; nothing is said about what a settings document contains or what happens if the id doesn't exist.

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 front-loaded sentence with the resource, key parameter, and default in one pass. No filler or redundant clauses.

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-only getter with one optional parameter and no output schema, the description covers the call mechanics. It omits what the returned document looks like and error behavior for unknown ids, which leaves the agent guessing at return shape given no output schema.

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 one parameter, but the description supplies the key semantic: the id identifies a settings document and defaults to 'global'. It does not clarify id format (slug vs UUID) or valid values, so it only partially compensates 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 and resource: 'Get an OpenCDR settings document by id', with the default scope noted. It is distinguishable from the rules/lists/signals siblings by resource, though it never names 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?

There is no guidance on when to call this versus opencdr_settings-related siblings or how a settings document relates to rules/lists. The agent must infer usage from the tool 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?

Annotations already establish read-only, idempotent, non-destructive behavior, and the description layers on real backend constraints: dedicated per-selector indexes that cannot be AND-combined, a max 31-day range, a 7-day default window, and silent ignoring of date params for some selectors. Those silent-ignore semantics are the kind of trap an agent cannot infer from structured fields.

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 paragraphs, front-loaded with the verb and the single most important constraint (one selector). Every sentence carries actionable information, including the negative-space note about unsupported correlation fields.

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 9-parameter, no-output-schema, zero-schema-description tool, the description covers selectors, date semantics, pagination, and backend limits well. Gaps remain on limit/order behavior and on what a returned signal record looks like, though next_token signaling implies a paginated result envelope.

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 largely does: it defines the mutual exclusion of severity/event_id/category/integration_id, the YYYY-MM-DD UTC inclusive format and 31-day cap on date_from/date_to, and pagination via next_token. Only limit and order, which have schema defaults but no stated meaning or interaction with next_token, go unexplained.

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 ("Search detection signals") and flags read-only up front. It distinguishes itself implicitly from opencdr_logs_search and opencdr_signals_stats by naming the 'signals' domain, but never explicitly routes to those siblings, so an 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?

Explicitly states the exactly-one-selector rule, names the four valid selectors, explains which parameters the date range governs and which it is ignored for, and documents an unsupported capability (correlation by source_ip/principal/resource/account/region) with the workaround (pivot via event_id). That is genuine when/when-not guidance.

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

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

Annotations already cover read-only/idempotent/no-destruction, so the description wisely spends its words on traits annotations don't carry: the 7-day default when no dates are supplied, UTC YYYY-MM-DD inclusive semantics, and a hard 31-day maximum range. It even explains that the 31-day bound matches the date-range constraint used by opencdr_signals_search's severity selector, which is real cross-tool behavioral context. The lone redundancy is the bare 'Read-only.' line, which merely echoes readOnlyHint=true.

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 summary-vs-listing distinction is front-loaded in the first two lines and every subsequent sentence adds a concrete constraint or the return shape. No filler, no 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?

With no output schema, the description correctly supplies the return shape ({date_from, date_to, counts by severity, total}) and all range constraints, so an agent can call it and interpret results. Only the one-sided date-range behavior and whether unreported severities are omitted from 'counts' are unaddressed.

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 has to carry the two nullable date params, and it does: format, UTC, inclusivity, the no-dates default, and the max span. The remaining gap is the single-date case — it says what happens if 'neither' date is given but not what the other bound defaults to when only one is supplied.

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 ('Signal counts by severity for a date range') and immediately positions the output as an aggregate summary rather than a list. It names the sibling opencdr_signals_search and states the distinction, so an agent can tell the two apart without opening either schema.

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

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

'A dashboard/summary view, not a substitute for opencdr_signals_search's paginated item listing' gives both the when (aggregate counts) and the when-not (per-item listing), naming the exact alternative to use instead. Nothing about selection is left to inference.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Read-only' merely restates structured data and earns no credit. The description adds nothing beyond that — no auth requirements, rate-limit behavior, or what the health result conveys.

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 terse sentences, purpose front-loaded, zero waste. Nothing could be removed without losing meaning.

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 no-argument read-only health probe with full annotation coverage, the description is nearly sufficient. The only minor gap is that it doesn't indicate what the response reports (e.g., status field or version), but no output schema exists and that is a small omission.

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 there is nothing for the description to document. No parameter information is needed or missing.

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 ('Check OpenCDR API health'), which is clearly distinct from the data-retrieval siblings such as opencdr_rules_list or opencdr_signals_search. It does not explicitly name a sibling or contrast itself, but the diagnostic purpose is unambiguous.

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

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

The health-check framing implies usage (verify connectivity/liveness before or during other calls), but there is no explicit when-to-use, when-not, or reference to alternatives. An agent can infer intent but receives no routing guidance.

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