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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, and the description adds important non-obvious behavior: the aggregate counts are server-instance-wide across ALL users, not just the caller. It also discloses the minimum viewer role requirement and the shape of the returned snapshot.

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 well-structured: purpose first, then usage guidance, then the important instance-wide caveat, then a compact Args/Returns block. Every sentence earns its place and there is no filler or redundancy.

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

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

For a read-only health-check tool, the definition is complete: it covers when to use it, auth requirements, data scope, return contents, and alternative tools for the non-health use case. The annotations already cover mutability and idempotence, so nothing critical 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?

The Args section only lists 'token, client_id' without explaining their semantics, defaults, or relationship to auth. The nested schema does contain short descriptions, but the description itself adds no value beyond the schema, and the context signal indicates 0% schema description coverage, so 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?

Description opens with a concrete verb and object: 'Return server health status and instance-wide aggregate counts.' It clearly distinguishes itself from account-specific tools by stating it is not for checking your own usage, and the annotation title 'Server Health Check' reinforces the purpose.

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 when to use this tool ('confirm the server is reachable', 'see which model families are supported') and when not to use it ('not to check your own account's usage'). It also names the alternative tools for the excluded use case: rca_model_list, rca_graph_list_versions, and rca_analysis_list_results.

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 carry destructiveHint=true, readOnlyHint=false, idempotentHint=false, and the description adds substantial context beyond them: irreversibility, the confirm=true guard with its 'aborted' failure mode that deletes nothing, the no-cross-account boundary, Enterprise plan gating with the specific error lower tiers receive, and single-namespace granularity. No contradiction with annotations.

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

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

Longer than typical, but the length is earned for a destructive admin tool: purpose, irreversibility warning, scope boundary, plan gating with alternatives, parameter mapping, and return shape each carry distinct weight. The safety-critical warning is front-loaded in the first sentence, and the Args/Returns sections are efficient.

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?

Covers every dimension an agent needs to invoke a high-risk tool correctly: the action, failure modes ('aborted', 'security_violation'), boundary conditions (own data only, one namespace at a time), plan eligibility, per-item alternatives, and the return format ({namespace, deleted_count}). Nothing material 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 reported at 0% at the top level, so the description compensates for the two behaviorally meaningful parameters: namespace ('purges only that one namespace, not all three at once') and confirm ('must be true, or this returns an aborted error without deleting anything'), adding failure-mode semantics beyond schema text. Token and client_id are structural and adequately described in the nested 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 ('Permanently delete') with a precise resource ('storage namespace') and explicit scope ('ALL of YOUR OWN records... graphs/models/results'). The bulk nature is clear and it differentiates itself from the per-item siblings by naming them explicitly, leaving no ambiguity about what this tool does that others don't.

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 complete when/when-not guidance: use for one-call bulk purge of own records, do not use on Free/Starter/Pro plans (which return security_violation error), and names the exact alternatives (rca_graph_delete, rca_model_delete). Even covers the gap that no per-item results delete exists.

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; the description adds substantial behavior beyond that: plan-gated execution with a security_violation-style error, strict privacy scope (never another user's activity), and snapshot semantics. It also describes the return shape. No contradiction with annotations.

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

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

The description is front-loaded with the core behavior and uses short paragraphs for plan requirements, use cases, args, and returns. It is slightly longer than strictly necessary because 'one entry per tool call' is repeated, but every major block 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?

For a tool with plan gating, privacy constraints, and snapshot semantics, the description is complete: it covers prerequisites, failure mode, intended use, limitations, parameter format, and return JSON structure. An agent has enough to decide when and how to invoke it, with the schema filling in token/client_id details.

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 description enriches hour_key with a concrete YYYYMMDD_HH format, an example, and the default-to-current-UTC-hour behavior. The schema already documents token, hour_key, and client_id, so the description does not need to repeat all fields, though mentioning client_id in the Args block would have been slightly more complete.

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 names a specific verb and resource: reading the caller's own structured audit log entries for a given hour bucket. It also clarifies granularity (one entry per tool call) and content (tool, timestamp, success/denied), which distinguishes it from all sibling tools. No ambiguity about what the tool does.

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

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

It gives explicit use cases: investigating why a call was denied or confirming a destructive action, plus an exclusion: not suited to real-time monitoring because it's an hourly snapshot. It also states the prerequisite audit_log_export feature/Pro plan and names rca_admin_show_plan_info as a way to check eligibility.

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 readOnly, idempotent, and non-destructive behavior, so the description does not need to repeat that. It adds useful context by describing the exact return payload and the upgrade_url nuance on Enterprise, and it clarifies that no configuration parameters beyond authentication are needed.

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 a clear purpose and then gives focused usage guidance and return format. It is slightly verbose in the usage paragraph, but each sentence provides necessary context for correct invocation.

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 plan lookup, the description covers what the tool returns, when to call it, and what parameters are needed. The return shape is explicitly outlined, and the annotations cover safety properties, so nothing essential is missing for correct use.

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 description says there are no parameters beyond authentication)Skip? It clarifies that no additional configuration is expected, which is helpful. However, it does not add meaningful detail about client_id semantics; the schema already describes token and client_id, so the description provides only marginal added value for 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 clear verb ('Show') and a specific resource: current plan, feature limits, and locked features. It is easily distinguishable from sibling admin tools like rca_admin_health and rca_admin_read_audit_log.

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 tells the agent when to call the tool: proactively before quota-consuming operations such as rca_analysis_batch, rca_model_create, rca_report_compare, and the ai_summary flag. It also explains the benefit—avoiding plan_required errors mid-workflow—making the usage guidance concrete and actionable.

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 are all false/neutral, so the description carries the behavioral burden. It discloses plan gating, the identical application of the model across incidents, and the per-incident plus cross-incident ranking output. It stops slightly short of stating side effects such as whether results are persisted or whether a failing incident fails the whole batch, which would make it fully transparent.

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

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

The description is organized into purpose, prerequisites, alternative, args, and returns. It is detailed yet each sentence earns its place, and the most important scope information is front-loaded.

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 batch operation with plan limits and cross-references to another tool, the description covers purpose, usage, limits, parameter meaning, and return shape. The only gap is the lack of error behavior for partially invalid batches, but the presence of an output schema and the detailed Returns section makes this a minor 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?

Schema coverage is marked low, but the description compensates for model_id and incidents by explaining 'applied identically to every incident' and 'matching the same shape rca_analysis_run expects.' It does not add much for token/client_id, but those are sufficiently described in the schema and are less decision-critical.

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 concrete verb and resource: 'Run the same RCA model over multiple incidents in one call' and states the output's purpose (ranking recurring root causes to spot systemic issues). It clearly distinguishes from the sibling rca_analysis_run by specifying the batch-vs-single-incident scope.

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 when-to-use guidance: 'use this to spot a systemic cause behind several similar incidents' and explicitly routes single-incident use to rca_analysis_run. It also gives plan-tier constraints and names rca_admin_show_plan_info as the way to check limits.

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 and idempotentHint, so the safety profile is covered. The description adds behavioral context beyond annotations: it returns raw JSON for programmatic use, names the output fields (consensus_causes, model_disagreements), and documents the not_found failure mode for invalid or foreign result_ids.

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 two sentences are punchy and front-loaded: behavior first, differentiation second. The Args/Returns section is a bit redundant with the schema (repeating result_ids constraints), but the block is compact and organized, so it doesn't become bloat.

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 description covers the core comparison behavior, the alternative rendering tool, the source of result_ids, the return format, and the not_found error condition. Coupled with the output schema and safety annotations, an agent has everything it needs to decide whether and how to invoke this 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?

The schema_description_coverage is 0%, so the description needed to compensate by explaining all parameters. It only addresses result_ids (and mostly repeats the schema's own phrasing), while token and client_id are not mentioned in the description. The Args line is also slightly misleading because it presents 'params' as if it were result_ids rather than an object containing multiple 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 opens with a specific verb ('Compare') and a precise object ('multiple RCA results'), and enumerates what the comparison surfaces: overlapping root causes, confidence agreement, and model disagreements. It also explicitly contrasts itself with rca_report_compare, so an agent can distinguish it from the closest sibling without inspecting schemas.

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 instructs using rca_report_compare when a rendered markdown/HTML document is desired instead of raw JSON, and identifies where result_ids come from (rca_analysis_run or rca_analysis_list_results). This is clear 'when to use this vs alternative' 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?

The description discloses the algorithm steps (dispatch_rca, weighted scoring, normalization), the Pro+ feature requirement, the default save=true persistence behavior, and possible error types (bad_input/not_found). Annotations are all false and thus provide little behavioral signal, so the description carries the burden and handles it well. It could additionally caution about the side effect of persisting results by default, but the save parameter is at least mentioned.

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 organized with a front-loaded purpose, usage guidance, a numbered algorithm, structured Args, and a Returns section. There is minor redundancy between the Args section and the schema descriptions, but the length is justified by the algorithm complexity. No filler words or vague statements.

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 description covers when to use, the algorithm, the 2-5 model constraint, the shared payload requirement, default save behavior, output JSON structure, and error cases. An output schema exists, so detailed return-value documentation is not required. The only slight gap is not elaborating on payload validation across model families, but it acknowledges this with 'shape depends on the models' families.'

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 Args section enriches the schema meaningfully by noting weights must be 'same length as model_ids,' defaulting to equal weighting, and describing payload as 'shared input, shape depends on the models' families.' The schema already provides solid descriptions for all fields, so this is additive rather than necessary, but it adds useful constraint context. Token and client_id are left to the schema, which is sufficient.

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 precise operation: 'Run 2-5 different RCA models on the SAME payload and combine their root-cause scores via weighted voting.' It is a specific verb (run/combine) with a clear resource (RCA models/payload), and it explicitly contrasts with rca_analysis_batch by saying 'for the SAME model run over multiple different incidents instead, use rca_analysis_batch.' This makes the tool's purpose unmistakable and distinguishes it from siblings.

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

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

The description gives explicit guidance: 'Use this when you're unsure which single model family fits the data best and want cross-validation across families,' and it names the exact alternative tool and condition. This is a clear when-to-use and when-not-to-use statement, leaving nothing 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 non-destructive behavior. The description adds significant behavioral detail beyond that: the output shape varies by detail_level, recommended actions are ranked and heuristic, and it returns a not_found error when the result is missing or owned by another user.

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 well-structured: a front-loaded purpose statement, an explicit contrast with the sibling tool, a compact Args list, and a clear Returns section. Every sentence adds useful information; no filler exists.

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 read-only explanation tool, the description covers the input requirements, the supported detail levels with concrete output differences, the return format, and the error case. Together with the annotations and schema, an agent has everything needed to call this tool 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?

The description adds real meaning to result_id (must come from a prior analysis call) and detail_level (exact value meanings and resulting output shape), which goes beyond the schema's brief labels. It does not discuss token or client_id, though those are auth/namespace parameters already described in the schema, so the omission is minor.

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: 'Turn a stored RCA result into a human-readable explanation' with recommended actions. It explicitly contrasts itself with rca_analysis_get_result's raw JSON, making the tool's unique role clear among 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 description states why this tool is useful ('for a chat response or incident writeup') and directly names the alternative it should be chosen over ('as opposed to rca_analysis_get_result's raw JSON'). This gives an agent explicit selection 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: it returns the 'full stored RCAResult' as a JSON string and specifies that a not_found error occurs if the ID does not exist or belongs to another user.

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 well-structured with a clear purpose statement, usage guidance, Args, and Returns sections. It is reasonably concise, though the Args block duplicates schema information and could be trimmed without losing 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 a simple read-only retrieval tool, the description covers the invocation flow, prerequisites, error behavior, and return value. The schema covers required fields and defaults, and the annotations cover safety and idempotency. No important information is missing for an agent to select and call this tool 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?

The schema already describes token as the API key, client_id as the client namespace, and result_id as a prior analysis result ID. The description's Args section mostly repeats the result_id semantics, so it adds little meaning beyond what the schema provides. This is acceptable because the schema carries the parameter documentation burden.

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: 'Retrieve a previously saved RCA result by result_id.' It clearly identifies this tool as a fetch-by-ID operation and differentiates it from rca_analysis_list_results by stating that list_results is the tool to use when you do not yet have a result_id.

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 when-to-use guidance: call it after rca_analysis_run or rca_analysis_run_async + rca_analysis_poll_task when you already have the result_id. It also names concrete downstream uses (rca_report_generate, rca_analysis_compare) and tells the agent to use rca_analysis_list_results instead if no result_id is available.

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 safety profile is covered. The description adds valuable behavior: results are ordered newest-first, only IDs and counts are returned, pagination works via limit/offset, and the response has a specific JSON shape. This goes beyond the annotations without contradicting them.

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

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

The description is front-loaded with a clear one-sentence summary, then compactly structured Args and Returns sections. It is spare and readable. It loses a point because the Args section is incomplete and partially duplicates schema-provided default 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?

For a read-only paginated list tool, this description covers purpose, ordering, pagination, return shape, and follow-up behavior. The response format is described explicitly, and the annotations handle safety. Missing explicit token/client_id guidance is the main gap, though the schema covers those fields, so the description is still largely 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 description adds useful semantics for limit and offset, including bounds, default, and how offset pages past limit. However, it omits token and client_id from the Args section, and with the schema description coverage signal at 0% for the top-level params object, the description does not fully compensate for those missing parameters. The nested schema descriptions cover them, but the tool description itself leaves the agent to discover them.

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 uses a specific verb ('List'), identifies the resource ('stored RCA result IDs'), and specifies ordering ('newest first') and pagination. It also explicitly distinguishes itself from rca_analysis_get_result by stating that it returns IDs and a count only, not the full results.

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 clearly tells the agent when to use this tool: to list all stored result IDs with pagination. It also directs follow-up to rca_analysis_get_result for full content. However, it does not explicitly contrast with rca_analysis_query_results for filtered/search use cases, so it stops short of full exclusion guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the full polling state machine (pending → running → completed/failed), when result/error are populated, the feature-gate requirement, and the not_found behavior for invalid or other-user task IDs. This gives the agent a realistic model of the tool's runtime 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?

The description is well-structured and front-loaded with the core purpose, followed by actionable polling instructions, a state summary, and return shape. Each sentence adds functional value, and the bullet under Args keeps parameter wiring clear without unnecessary fluff.

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 async polling tool, the description covers the full lifecycle: submission source, polling cadence, state transitions, result/error fields, feature gate, and error cases. The output schema exists and the description also sketches the returned JSON, so the agent has enough context to invoke and interpret the tool 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?

The description adds the important semantic that task_id comes from rca_analysis_run_async's response, which is necessary for correct invocation. However, it does not describe token or client_id in the description itself, and the stated schema description coverage is 0%, so the description only partially compensates for the parameter documentation 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: 'Poll the status of an async RCA task submitted via rca_analysis_run_async.' This clearly identifies the tool's function and distinguishes it from related analysis tools like rca_analysis_get_result or rca_analysis_run_async by focusing on polling an already-submitted async task.

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 when-to-use guidance: call repeatedly every few seconds until status is 'completed' or 'failed', and notes there is no push notification. It clearly ties usage to tasks submitted via rca_analysis_run_async, though it does not explicitly name alternative tools or exclusion conditions.

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 mark readOnly/idempotent/non-destructive, and the description adds meaningful behavior: it does not load every full result, it returns lightweight index entries, and it returns a JSON structure with total/results/has_more. Pagination semantics are also disclosed. No contradiction with annotations.

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

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

Well-structured and front-loaded: purpose first, alternative routing second, return behavior third, then concise parameter bullets and return format. Every sentence serves a purpose and the length is justified by the richness of the 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?

Complete for a read-only filtered query tool. It explains what it returns, how pagination works, which sibling to use for unfiltered listing, and how to get full result bodies. Required auth is captured in the schema, so nothing critical 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?

The description adds valuable semantic detail beyond the schema: examples for model_family, confidence ranges, ISO timestamp format, tag matching behavior, and pagination limits. It omits the required token and client_id from the Args summary, but the input schema fully documents those, so an agent can still invoke the tool correctly.

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 ('Query') and resource ('stored RCA results') with explicit filter dimensions (model family, confidence, time, tags) and the lightweight-index behavior. Explicitly distinguishes itself from the sibling rca_analysis_list_results by naming the alternative, so an agent can tell them apart without inspecting 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?

Explicitly states when to use this tool instead of rca_analysis_list_results ('whenever you need to filter') and directs plain unfiltered listings to the sibling. It also tells the agent to follow up with rca_analysis_get_result for full content when needed, providing clear routing 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?

The description adds behavioral context beyond the annotations: it blocks until the model finishes (synchronous), saves results by default, and explains that ai_summary is quota-limited with a graceful fallback. This is valuable since annotations only indicate it's not read-only and not destructive. No contradictions with the annotations.

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

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

The description is well-structured with an Args section and a Returns section. The primary purpose and alternative routing are front-loaded, and every sentence adds information without redundancy or fluff.

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 description covers the essential aspects: the synchronous blocking behavior, alternative tools, parameter usage, and return format (including _saved_as and ai_summary fields). With an output schema available, this is complete for an agent to call the tool 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?

The description adds meaningful context for parameters: 'save' is explained with a practical use case ('throwaway check'), 'ai_summary' gets quota and error-handling details, and the payload shape is deferred to the schema with a family-specific breakdown. This goes beyond the schema's descriptions and helps the agent decide how to use the 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 clearly states the action ('Execute an RCA analysis'), the resource ('using a registered model'), and the outcome ('return ranked root causes'). It explicitly labels itself as the primary synchronous entry point and contrasts with async and batch alternatives, making it easy to distinguish from 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?

Provides explicit guidance on when to use this tool vs. alternatives: 'For a model that might take a while, use rca_analysis_run_async + rca_analysis_poll_task instead (Pro+); for multiple incidents through the same model in one call, use rca_analysis_batch instead (Starter+).' This is clear, specific, and leaves no ambiguity.

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 description discloses important behavior beyond the annotations: it returns a task_id immediately, requires the async_tasks feature, and must be polled with rca_analysis_poll_task. This is meaningful context that annotations alone do not provide, though it does not cover failure modes or cancellation 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?

The description is well-structured and front-loaded: the first sentence explains the core behavior, followed by prerequisites, alternative, return value, and parameter details. Every sentence adds information and 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?

The description is complete for a background-task tool: it covers when to use it, prerequisites, the immediate return value, how to poll, and the parameter semantics. The sibling list provides additional context, and the description names the exact polling tool to use next.

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 of explaining parameters. It adds valuable context for model_id, payload, save, and tags, including that model_id must already exist and that payload matches rca_analysis_run's expected shape. It omits token and client_id, but those are less central and are described in 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 clearly states the verb and resource: submitting a long-running RCA analysis as a background task rather than blocking. It also names the synchronous sibling rca_analysis_run, which makes the distinction between the two immediately obvious.

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 when to use this tool (long-running analysis / large datasets) and when not to (most models on typical data sizes), and points to rca_analysis_run as the simpler alternative. It also instructs the caller to use rca_analysis_poll_task to retrieve results, leaving no ambiguity about the follow-up workflow.

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?

Discloses that the key does not expire, cannot be recovered later, and that roles are for audit only. These go beyond the annotations (readOnlyHint=false, etc.) and provide necessary 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?

The description is well-structured with a clear lead sentence, usage instructions, plan details, and param breakdown. It is slightly verbose but earns its length with useful 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?

Covers all aspects: purpose, usage, parameter details, return value (JSON with api_key), plan limitations, and security notes. The output schema is referenced, so return format is clear.

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?

Despite 0% schema description coverage, the description explains each parameter's purpose: roles are audit-only metadata, key_id is ignored, key_label is optional. This adds meaning beyond the raw schema.

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

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

The description clearly states 'Generate a new API key for authenticating all other tools' and specifies it issues the Free plan. This distinguishes it from sibling auth tools like rotate and revoke.

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 says 'Call this FIRST before using any other RCA-MCP tool' and provides instructions on storing the key and passing it as the 'token' field. Also clarifies that paid plans are handled separately.

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?

Beyond the readOnlyHint, idempotentHint, and destructiveHint annotations, the description reveals that key material is never returned, that plan restrictions cause a specific error, and what fields the returned JSON contains. This gives the agent a clear behavioral model.

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 focused and well-structured: purpose, security guarantee, plan requirement with follow-up usage, and return format. It is slightly detailed for such a simple listing tool, but every sentence adds meaningful information and nothing is 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?

The definition covers the purpose, security expectations, error conditions, sibling tool integration, and return structure. The schema covers parameters and annotations cover read-only/idempotent behavior, so an agent has everything needed to call this tool 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?

The description does not elaborate on the token or client_id parameters, but the input schema itself provides descriptions: token is 'API key to authenticate this request' and client_id is 'Client namespace ID' with a default. Thus the agent already has parameter-level meaning, and the description adds no extra parameter semantics 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 starts with a specific verb and resource: 'List your own API keys and their metadata.' It also distinguishes itself from sibling tools by explicitly stating it never returns raw or hashed key material and by pointing to rotate/revoke tools for acting on keys.

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 clearly states when the tool is usable: requires the multi-key feature, with Pro/Enterprise limits, and that Free/Starter plans will get a security_violation error. It also tells the agent to use returned key_id values with rca_auth_rotate_key or rca_auth_revoke_token for follow-up actions.

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 destructiveHint and idempotentHint, so the description goes beyond by explaining plan-tier behavior, the risk of revoking your only key, and the recovery path via rca_auth_generate_token or dashboard. This adds useful operational context beyond the structured hints.

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 usage, then practical caveats, then parameters. Slightly longer than necessary because the Args section partly duplicates schema descriptions, but every section adds meaningful decision-relevant detail.

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 destructive auth tool, this description is unusually complete: it covers when to use it, sibling alternatives, permission/plan implications, unknown-key-id fallback, and post-revocation consequences. The only minor omission is client_id, which is optional and defaulted.

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 schema already describes token and key_id_to_revoke clearly, and the description mostly restates them. It does not mention the optional client_id parameter, but that parameter has a default and is peripheral to the core destructive action.

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 ('Deactivate'), resource ('one of your own API keys'), and immediacy, with concrete use cases (compromised key, retired integration). It explicitly contrasts itself with rca_auth_list_keys/rca_auth_rotate_key, making sibling differentiation 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?

Gives explicit when-to-use guidance ('compromised' or 'retired'), and clarifies a key selection criterion: no plan gate, unlike sibling key-management tools. It even handles the edge case of Free/Starter users who cannot list keys and directs them to the dashboard.

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?

Beyond destructiveHint, the description discloses that the old key is deactivated and that the new raw api_key is returned only once and cannot be recovered later. This one-time-recovery warning is essential and not conveyed by the annotations.

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

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

The definition is front-loaded with the core operation, followed by prerequisites, usage guidance, and input/output details. Each section earns its place and 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 destructive auth operation, it covers the multi-key feature prerequisite, how to get key_id, the response shape, and the cannot-recover-later constraint. An agent has enough context to select and invoke this tool 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?

The description adds valuable semantics for key_id: it is a UUID from rca_auth_list_keys, not the raw key string. The other parameters are covered by the input schema, and the return description ties the result back to the parameters clearly.

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 action on a specific resource: deactivate an existing API key and generate a replacement in one call. It also distinguishes itself from rca_auth_revoke_token, making its purpose 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?

It gives an explicit prerequisite and workflow: use rca_auth_list_keys first to obtain key_id. It also tells the agent exactly when to prefer this tool over rca_auth_revoke_token, which is clear routing 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?

The description discloses key behavioral aspects: the iterative nature (call repeatedly), the response structure (status, question/diagnosis, progress_pct, ai_summary/error), and quota limits on ai_summary. It does not contradict annotations (readOnlyHint=false, destructiveHint=false). While it doesn't mention authentication (token is in schema) or error handling, it adds value beyond schema by describing the quota and the resolution trigger. Given the sparse annotations, this is strong transparency.

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 well-structured with an Args and Returns section, and the purpose is front-loaded. It is slightly verbose with the emoji and 'Starter+' branding, but every sentence carries meaning. The instructions about repeated calls and follow-up report generation are concise. It earns a high score but loses a point for minor verbosity and unnecessary branding elements.

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 description is complete for a stateful tool in a multi-step workflow. It explains the iteration requirement, the resolution condition, the follow-up report tool, and the response format. It covers both the ai_summary generation and its quota. Since the output schema is present, the return fields are already specified. Nothing essential for correct usage 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?

The schema already provides descriptions for all parameters (token, answer, client_id, ai_summary, session_id, measurement), so baseline is 3. The description adds contextual meaning by explaining the answer values ('yes|no|unknown'), the purpose of measurement ('Optional actual reading'), and the ai_summary behavior ('if this answer resolves the session'). It does not mention token/client_id, but those are self-explanatory. Overall, it enhances the parameter understanding beyond the raw schema.

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

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

The description clearly states the tool's purpose: 'Answer the current diagnostic question to advance the decision tree.' It identifies the specific verb (answer), resource (diagnostic question), and the action's effect (advance the tree). This distinguishes it from siblings like rca_dtree_start (starts a session) and rca_guide_generate_report (generates a report), which are mentioned as follow-up steps.

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 calling pattern: 'Call repeatedly until status == "resolved".' It also provides the next step after resolution: 'use rca_guide_generate_report to turn the session into a shareable report.' Additionally, it clarifies the ai_summary parameter's behavior ('if this answer resolves the session') and quota limits, giving the agent clear guidance on when and how to use the 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?

The description discloses persistence behavior when save_as_guide=True, the fact that the tree is ingested as a json_dtree guide, and the return of a guide_id only in that mode. This is meaningful context beyond the annotations, though it leaves the save_as_guide=False side effect mostly implicit.

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 core purpose, uses compact paragraphs for workflow details, and ends with an Args/Returns block. The 'Starter+' label and emoji add little, but the overall length is justified by the tool's branching behavior.

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?

It covers prerequisites, the default ingestion path, the alternative on-the-fly path via rca_dtree_start, and the return shape. With an output schema and sibling context, not much is missing; an explicit statement of the save_as_guide=False behavior would make it 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 nested schema already documents most field meanings, and the description adds the important workflow context that fmea_result_id comes from rca_analysis_run and that save_as_guide controls guide ingestion. However, the Args block only lists names and omits token/client_id, so parameter semantics are adequate rather than thorough.

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: 'Auto-generate a diagnostic decision tree from a completed FMEA analysis.' It also distinguishes itself from rca_dtree_start by explaining the alternative guide_id='auto' path, so an agent can tell these tools apart.

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 prerequisite ('Get fmea_result_id first by running rca_analysis_run against a model created with family='fmea''), states the default save behavior, and describes when to use rca_dtree_start instead ('skip this tool entirely and pass guide_id='auto'').

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 mark the tool as read-only, idempotent, and non-destructive. The description adds valuable non-obvious behavior: free-plan keys receive a plan_required error instead of results, the resolved_only flag excludes in-progress sessions when true, and returned data includes status and diagnosis only when resolved.

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 well structured with a clear purpose statement, usage guidance, compact Args section, and Returns shape. It front-loads the main action and each section earns its place without unnecessary 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?

The description gives everything an agent needs to decide to call this tool and interpret the response: session source, filtering, resolved status semantics, plan-gating behavior, returned JSON shape, and follow-up workflows with sibling tools. The output schema exists for structured return details, so the prose return description is a helpful supplement.

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 description summarizes the two meaningful parameters, equipment_id as an optional filter and resolved_only with its default false behavior. The input schema does describe these fields, so the description is partly redundant, but it also connects them to the return contract and expected session lifecycle. It omits token and client_id, though those are covered by 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 clearly states the operation: 'List your equipment diagnostic sessions' and specifies the source ('started via rca_dtree_start') plus what each session contains ('status and diagnosis if resolved'). It differentiates this tool from the related workflow tools by explaining it produces session_id values for rca_guide_generate_report and rca_dtree_answer.

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 when to use it: 'find a session_id for rca_guide_generate_report, check whether a session is already resolved before continuing it with rca_dtree_answer, or review diagnostic history.' This gives clear selection context and naturally excludes cases where another tool should be used.

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 description richly discloses non-obvious behavior beyond the annotations: session_id resume semantics, silent fallback to a new session for missing/resolved/foreign session IDs, ignored parameters during resume, and lack of error on typo'd IDs. This is exactly the kind of behavioral context an agent needs and is not available from the 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?

The description is long but every section earns its place: purpose, mode selection, session resume caveats, parameter list, and return value. The non-obvious session behavior is front-loaded and clearly separated. No filler or redundant 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?

For a session-starting tool with complex mode logic and subtle resume behavior, the description covers all necessary calling conditions, required parameters, response fields, and the follow-up protocol. The output schema further confirms the return structure, and the description explains semantics that the schema cannot convey.

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?

Despite the low schema description coverage signal, the description adds substantial meaning for guide_id, session_id, fmea_result_id, equipment_id, and symptom, including mode-specific requirements and resume behavior. It omits token and client_id, but those are authentication/namespace parameters already described in the schema and are less decision-critical.

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

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

The description clearly states a specific action ('Begin an interactive diagnostic session using a decision tree guide') and identifies the expected output and follow-up tool (rca_dtree_answer). It also distinguishes the two modes of operation and is unambiguous against sibling tools like rca_dtree_answer and rca_dtree_generate_from_fmea.

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 context for when to use this tool: to start a session, with either a concrete guide_id or auto-generation from completed FMEA results. It also explains the required fmea_result_id for auto mode and describes the resumption behavior. It does not explicitly list conditions for avoiding this tool in favor of a sibling, but the workflow guidance is clear enough.

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?

Beyond the annotations, the description discloses important behavior: DAG enforcement via automatic cycle rejection rather than silent acceptance, error results when nodes are missing or cycles would form, and the semantic distinction between weight and confidence. This adds genuinely useful behavioral context beyond the 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?

The description is well-structured and front-loaded: the core operation and key constraint appear first, followed by a concise parameter list and return behavior. Every sentence adds information, and bullet-style formatting makes it easy for an agent to parse.

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 graph mutation tool, the description covers the essential context: required ordering (nodes first), DAG constraints, parameter semantics, and return/error behavior. The output schema exists and the description still explains what the returned JSON contains, so an agent has enough to call the tool 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?

Although schema description coverage is listed at 0%, the description compensates by walking through key parameters: graph_id, source, target, weight, confidence, and method. It adds interpretive meaning—especially the weight-versus-confidence distinction and the display-only nature of method—but omits token and client_id parameters, which slightly reduces completeness.

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 directed causal edge (source → target) to a graph.' It also distinguishes itself from the sibling rca_graph_add_node by explicitly instructing that nodes must be added first, making the tool's role 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 description gives clear context: nodes must already exist and should be created via rca_graph_add_node, and cycle-causing edges will be rejected. It provides a useful prerequisite and an implied exclusion, though it does not explicitly contrast with every nearby sibling such as rca_graph_remove_edge.

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?

Discloses important behaviors beyond the annotations: duplicate names raise an error rather than overwriting, node_type only classifies the node for reports/views and does not affect analysis, and the return value includes added_node, node_type, and total_nodes. This complements annotations like readOnlyHint=false and destructiveHint=false without contradicting them.

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

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

The description is compact and well-organized: a two-sentence intro, a bulleted Args list, and a Returns line. The uniqueness constraint and replacement note are front-loaded and actionable. Some schema details like defaults and optional flags are repeated, but this does not meaningfully bloat the text.

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 graph mutation tool with an output schema and annotations, this description covers the action, the error case, all decision-relevant parameters, and the return shape. The only omissions are token and client_id, which are visible in the schema and not central to deciding when or how to invoke the tool. An agent can call this tool correctly without further lookup.

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 Args section explains all user-meaningful parameters: graph_id, name, node_type with accepted values and default, and description/metadata marked as optional. It adds semantic nuance not fully explicit in the schema, such as 'doesn't affect analysis' for node_type and the uniqueness guarantee for name. Token and client_id are omitted but are standard authentication/namespace fields present in 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 starts with 'Add a typed node to a causal graph' — a specific verb, resource, and scope. The uniqueness constraint and node_type enumeration further clarify what the tool does, distinguishing it from siblings like rca_graph_add_edge and rca_graph_remove_node without needing to inspect their schemas.

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 routes replacement behavior to rca_graph_remove_node ('remove the existing one first with rca_graph_remove_node if you want to replace it'), which is clear when-not-to-use guidance. The primary use case is evident from the tool name and opening sentence, though it does not explicitly discuss alternatives like rca_graph_add_edge.

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 mark this as non-read-only and non-destructive, and the description adds that the graph starts empty and must be populated afterward. It also discloses the return shape. It does not mention auth requirements or client namespacing, but the schema exposes token and client_id, and the creation behavior is otherwise clearly described.

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 compact and front-loaded: the core action appears first, followed by workflow guidance and the alternative tool. The Args and Returns sections are minimal and useful, and every sentence 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?

For a simple graph-creation tool, the description covers the purpose, the workflow, the alternative, and the return value. The only notable gap is that the prose Args section omits the required token and client_id parameters, though these are present in the input 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 reported as 0%, so the prose description carries the burden of explaining parameters. It only documents name and description, omitting the required token and the optional client_id. While the schema itself contains descriptions for all nested fields, the tool description fails to compensate for the coverage gap and would not fully prepare an agent to invoke it correctly.

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: 'Create a new, empty causal DAG.' It also differentiates itself from rca_graph_discover by clarifying the hand-built versus inferred graph path, and references sibling tools rca_graph_add_node and rca_graph_add_edge for the next steps.

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 tells the agent when to use this tool versus rca_graph_discover: use this when hand-building the graph, and use discover when observational data is available for inference. It also states the follow-up tools (add_node, add_edge), leaving no ambiguity about the intended workflow.

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 description goes well beyond the destructiveHint annotation by stating the action is IRREVERSIBLE, that versioning/restore cannot rescue the record, that confirm=false aborts without deleting, and that a not_found error is returned for missing or other-user graphs. This is useful behavioral context the annotations alone cannot convey.

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 critical irreversibility warning is front-loaded, usage guidance follows, and the Args/Returns sections are clearly structured. The repetition of permanence is intentional emphasis rather than fluff.

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 destructive tool, the description covers prerequisites, alternatives, error behavior, return value, and ownership caveats. There is no missing information an agent would need to select and 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?

The description adds meaningful behavior to graph_id and especially confirm, including the abort-if-false outcome. It omits token and client_id, but the nested GraphDeleteInput schema already describes those unambiguously, so the gap is minor.

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: 'Delete a causal graph permanently.' It immediately distinguishes the tool from graph-editing siblings and from version restore, so an agent can tell exactly what this tool is for.

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 explicitly states when deletion is needed ('only need this to remove a graph entirely') and when it is not, naming rca_graph_add_node/remove_node/add_edge/remove_edge as alternatives for fixing a graph. It also gives the mandatory confirm precondition.

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 indicate readOnlyHint=false, so mutation is expected, and the description transparently states it 'Creates and saves a new graph.' It adds valuable context beyond annotations by noting the feature requirement and that 'statistical discovery finds correlational structure... not guaranteed ground truth.' It does not cover overwrite/collision behavior, but the main behavioral traits are 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 logically structured: purpose, feature requirement, alternative tool, trust caution, then Args and Returns. It is somewhat long but each major section earns its place, and the most important usage guidance is front-loaded.

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 rich input schema and output schema, the description covers the core decision of when to use this tool, what it returns, and what caveats apply. It does not discuss failure modes or naming collisions, but those are not essential for correct invocation. Overall it gives an agent enough context to select and call the tool effectively.

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 Args section restates name, data, and significance constraints that are already fully described in the input schema, including min 30 rows, max 50 variables, and the p-value default/bounds. It adds no new semantic meaning beyond the schema, and it omits token/client_id, though the schema documents those clearly. This is a solid baseline case.

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: 'Automatically discover a causal skeleton from observational metric data' via partial-correlation and Fisher-Z tests. It also distinguishes itself from the sibling tool rca_graph_create by saying it is 'same as rca_graph_create, but with edges inferred from data instead of asserted by hand.'

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 explicitly names the alternative workflow: 'use rca_graph_create + rca_graph_add_edge instead if you already know the causal structure.' It also warns to 'Always review the discovered edges (rca_graph_get or rca_graph_score) before trusting them,' giving clear post-invocation 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description only needs to add context beyond that. It usefully discloses the not_found error condition for nonexistent graphs or graphs belonging to another user, and it specifies the return type as a string in the requested format. This is consistent with the annotations and adds meaningful behavioral detail.

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 well-organized: a one-sentence purpose, a format-guidance line, an Args block, and a Returns block. It is front-loaded and free of filler. The format list slightly overlaps with the schema enum, but the added semantic explanations justify the repetition.

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 retrieval tool, this description is largely complete: it states the resource, the available formats, and the error behavior. It does not mention token or client_id in the Args list, but the schema provides those details and annotations cover the safety profile, so the agent has enough information to select and invoke the tool correctly.

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

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

The description explains graph_id and adds meaningful semantics to the format values ('full node/edge detail', 'Graphviz source', 'simple mapping'). However, it omits the required token parameter and the client_id namespace parameter, and context signals indicate 0% schema description coverage, so the description does not fully compensate for the missing parameter documentation.

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: 'Retrieve a causal graph's current state.' It also distinguishes among three output formats (json, dot, adjacency), making the tool's purpose concrete and differentiable from sibling tools like rca_graph_create, rca_graph_delete, and rca_graph_list_versions.

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 clear format-selection guidance: use 'json' for programmatic inspection, 'dot' for Graphviz rendering, and 'adjacency' for a simple source->targets mapping. It does not explicitly contrast this tool with an alternative, but the retrieval intent is clear enough for an agent to select it over mutation or versioning siblings.

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?

Beyond the readOnlyHint=true and destructiveHint=false annotations, the description discloses meaningful behavior: automatic snapshotting on every save, lack of a separate save-version step, newest-first ordering, and the feature requirement. This gives the agent a strong model of what will happen when invoked.

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 well-organized and efficient: purpose, snapshot behavior, feature requirement, follow-up usage hint, then Args and Returns. Every sentence adds useful information and the most important facts are front-loaded.

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 read-only list tool, the description is complete: it states the resource, the versioning mechanics, the prerequisite feature, the return JSON structure, the ordering, and the natural follow-up action. Nothing an agent needs to call this correctly 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 description coverage is signaled as 0%, so the description should compensate by explaining the parameters. It only mentions graph_id, restating the schema's own description, while token and client_id are left out. The nested schema does describe those fields, but the description itself adds little value beyond what the structured schema already provides and does not fully 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 opens with a specific verb and resource: 'List all historical versions of a causal graph.' It also clarifies how versions are created and distinguishes this from related tools like rca_graph_restore_version and rca_graph_get, so an agent can identify the correct 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 gives clear context: versions are snapshotted automatically on save, there is no manual save step, and the feature requires graph_versioning (Starter+). It also tells the agent to use returned version_id values with rca_graph_restore_version. It does not explicitly state when not to use this tool versus alternatives, so it stops short of a 5.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the return format (JSON with parents, children, co_parents, full_blanket), the not_found error behavior for missing node/graph, and the requirement that the node must exist. This gives the agent a clear model of what will happen when the tool is invoked.

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 tightly organized: definition first, then practical use case, then args and return behavior. Every sentence adds useful signal, and the core meaning is front-loaded so an agent can quickly decide whether to invoke 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?

For a read-only graph query, the description covers what the tool computes, why/when to use it, what inputs matter, what the output looks like, and the error case. The schema covers the remaining auth/namespace parameters, so nothing an agent needs to call this correctly 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?

The Args section adds actionable meaning for graph_id and node ('the graph to search', 'must exist in the graph; check with rca_graph_get') beyond their schema descriptions. Token and client_id are not elaborated in the description, but the schema already documents their purpose, and the description compensates well for the reported low coverage of the main operational 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 names a specific verb ('Return'), a concrete resource ('the Markov blanket of a node'), and exactly defines the result as 'parents ∪ children ∪ co-parents'. It clearly distinguishes itself from whole-graph reasoning and other RCA graph tools by emphasizing the minimal node set for one incident node.

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 tells the agent when to use this tool: to scope an investigation to relevant metrics for one incident node before targeted analysis or data pulling. It also advises checking with rca_graph_get if the node may not exist, but it does not name explicit alternatives or give a 'do not use' condition, so there is a small gap in 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?

Beyond the sparse annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint all false), the description reveals key behaviors: duplicate edges keep the higher-weight version, cycle-introducing edges are 'dropped and counted, not silently ignored', source graphs are 'left untouched', and a not_found error is returned for missing or foreign graphs. This is substantial context the annotations do not convey.

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

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

The description is front-loaded with purpose and behavioral rules, then cleanly organized into Args and Returns sections with every sentence carrying information. It is on the longer side and the Args section partially duplicates the schema, but the added ownership and side-effect notes justify the 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?

For a mutation tool with sparse annotations, the description covers purpose, prerequisites, side effects, edge-conflict behavior, parameter semantics, return format, and error conditions. An agent has everything it needs to select and correctly invoke this tool; the optional output schema only reinforces the documented return value.

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?

Even though the context signal reports 0% schema description coverage, the description compensates fully in its Args section: it adds ownership semantics ('both must be yours'), side-effect clarification ('graph_id_a/b are left untouched'), and explains conflict_resolution ('union' default keeps all nodes, 'intersection' keeps only shared nodes). This adds meaning well beyond the schema's terse property descriptions.

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+resource: 'Merge two causal graphs into a unified graph for cross-system RCA', with a concrete example (combining network-layer with application-layer graphs). This clearly distinguishes it from sibling graph tools like rca_graph_create, rca_graph_add_node, or rca_graph_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?

The description provides clear usage context via the cross-system RCA example and explicit prerequisites ('Requires the causal_discovery feature (Pro+); both source graphs must belong to you'). It does not explicitly name alternatives or state when-not-to-use scenarios, so it stops short of a 5.

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

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

The description explicitly notes the operation is destructive and irreversible via this tool, and provides undo alternatives: re-add the edge with rca_graph_add_edge or restore an earlier version. It also states the edge must currently exist and describes the return value and error conditions, matching the destructiveHint and idempotentHint annotations.

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 concise and well-structured, with no redundant sentences. Each sentence serves a purpose: stating the action, noting destructiveness and undo options, providing usage context, and explaining parameters and return values.

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 description provides a complete context for calling the tool: what it does, when to use it, how to undo it, important parameter constraints, and expected return/error behavior. It is sufficient for an agent to invoke this tool correctly without needing additional external information.

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 description adds meaningful semantics for graph_id, source, and target by explaining exact node names are case-sensitive and the edge must currently exist. The token and client_id parameters are not described in prose, but they are already well-described in the schema, so the description still adds 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 clearly states the tool removes a directed edge (source → target) from a causal graph, using a specific verb and resource. It also differentiates from related sibling tools like rca_graph_remove_node, rca_graph_add_edge, and rca_graph_restore_version.

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 when-to-use guidance: use when an edge was added in error or a causal hypothesis is disproven. It also directs users to rca_graph_remove_node instead when removing a node, and suggests rca_graph_get to verify edge existence.

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?

Even though destructiveHint=true already flags mutation, the description adds valuable context: the operation is destructive and irreversible through this tool, and it explains the only undo paths. It also discloses error behavior (not_found/value error) and warns that the node name is case-sensitive, going well beyond the annotation.

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 core purpose, then logically covers usage disambiguation, undo/recovery, parameter semantics, and return behavior. Each section earns its place and the text remains structured and readable despite covering a destructive operation with several caveats.

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 description is complete for this complexity level: it states the operation, destruction semantics, undo strategy, when-to-use guidance, parameter hints, and return format. It even handles the edge case of an unknown node name, leaving no critical ambiguity for an agent.

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 description adds meaning to key parameters by explaining graph_id as 'the graph to modify' and name as the exact, case-sensitive node name, plus advising rca_graph_get to confirm the name. While the top-level schema coverage is low, the nested schema already describes token/client_id, so the description's partial parameter guidance is sufficient and actionable.

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: 'Remove a node and all its incident edges from a causal graph.' This clearly distinguishes it from rca_graph_remove_edge, rca_graph_add_node, and rca_graph_delete, so an agent can immediately understand what operation this tool performs.

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 states when to use the tool ('correct a mistaken node') and when not to use it ('not to prune weak paths'), pointing to alternatives like adjusting edge weights or using rca_graph_score_paths first. It also gives recovery guidance via rca_graph_add_node/rca_graph_add_edge or rca_graph_restore_version.

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?

Despite destructiveHint=true already being declared in annotations, the description adds substantial behavioral context: the restore is itself snapshotted and undoable by restoring forward again, confirm=false yields an 'aborted' error, and the graph_versioning feature is required. It also discloses what the operation returns (graph_id, restored_from, node/edge counts). No contradiction with annotations.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by behavioral nuance, requirements, and a structured Args/Returns breakdown. It is longer than strictly necessary — the Args list partially recapitulates the schema — but every section earns its place by adding error semantics or return-shape 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?

For a destructive version-restore operation, the description covers prerequisites, sequencing (list_versions first), the confirmation gate, failure mode, undoability, and the return payload, which is ample given an output schema exists. Minor gaps remain: the required token's role and client_id default are left to the schema, and no limits on which historical versions can be restored are stated.

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 schema description coverage reported at 0%, the description compensates meaningfully for three of five parameters: graph_id (target), version_id (tied to rca_graph_list_versions), and confirm (must be true or an 'aborted' error is returned). It omits token and client_id, though those are self-evident in the schema's own descriptions and default 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 — 'Restore a causal graph to a specific historical version' — and sharpens the scope with the snapshot semantics ('creates a new current state from the version snapshot... the version history itself is preserved'). This clearly distinguishes restore from siblings like rca_graph_get, rca_graph_delete, and rca_graph_list_versions, especially by naming list_versions as the source of version_id.

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 clear operational context: 'Use rca_graph_list_versions first to find a version_id', plus the confirm=true gate and the Starter+ feature prerequisite. It does not explicitly state when-not-to-use or contrast against a competing tool, but for a version-restore operation the sequencing and prerequisites are concrete and actionable.

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, covering the safety profile. The description adds meaningful behavioral context by listing the structural metrics returned, including that the two scores are in [0,1], and clarifying this operation does not perform root-cause analysis. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, then provides usage context, args, and return values. Every sentence or block is informative and there is no filler or redundancy.

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

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

For a simple scoring tool, the description is complete: it explains what it does, when to use it, what it returns, and how the scores behave. The annotations and input schema cover safety and parameters, while the return-values listing fills any gap for agents that cannot infer output shape.

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 schema already provides descriptions for token, graph_id, and client_id, so the baseline is adequate. The description only repeats 'graph_id -- the graph to score' and does not mention token or client_id, but the schema fills that gap. It adds little 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 action and resource: 'Compute structural quality scores for a causal graph'. It also explicitly scopes the tool as a structural sanity check, not root-cause analysis, and mentions checking for valid DAG and connectivity, which distinguishes it from related tools like rca_analysis_run and rca_graph_score_paths.

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 when-to-use guidance: after building or editing a graph by hand, or after rca_graph_discover, before running rca_analysis_run. It also clearly states a when-not-to-use condition by saying this is 'not a root-cause analysis', which prevents misuse.

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 mark the tool read-only, idempotent, and non-destructive; the description adds the scoring formula, the root-node precondition, backward tracing semantics, and empty-list behavior when no path exists. It also notes that target_node must already exist in the graph, giving a useful precondition beyond what annotations convey.

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

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

The description is compact and front-loaded: action first, then scoring formula, then a short usage rule, then a bulleted argument list, then the return contract. There is no filler and no repetition of information already carried by 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?

Given the tool's complexity, the description covers the algorithm, scoring, prerequisites, the manual-graph use case, the alternative tool, and empty-result behavior. The output schema exists and the description still summarizes the return shape, leaving no obvious gap for an agent to call it correctly.

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

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

With schema description coverage at 0%, the description compensates well for graph_id, target_node, and top_k by explaining what the graph is searched for, requiring target_node to exist, and giving top_k's range and default. It does not restate token/client_id, though those are auth/namespace fields already present in the schema, so the gap is minor.

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 action ('Find and rank all causal paths') tied to a concrete resource (root-to-target paths in an RCA graph) and a precise scoring formula. It distinguishes the tool from data-driven analysis by naming rca_analysis_run as the alternative, so an agent can select it without inspecting 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?

Explicitly states when to use: on a hand-built graph created via rca_graph_create + rca_graph_add_edge, to compare manually asserted causal chains. It also gives a clear exclusion: for data-driven ranking use rca_analysis_run with granger_causality or dowhy_causal_inference instead, and directs checking target existence with rca_graph_get.

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?

Beyond the destructiveHint=true annotation, the description adds critical behavioral details: the action is irreversible, confirm=true is required, ownership must match exactly, and deleting a guide referenced by an active decision-tree session does not disturb in-progress state. It also discloses the return contract and not_found error cases, making the destructive behavior fully transparent.

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

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

The description is front-loaded with the most important facts—permanent deletion, confirm requirement, irreversibility—before moving to edge cases and arguments. Every sentence earns its place, and the structured Args/Returns section makes the lengthy content easy to scan.

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 destructive tool, the description fully covers purpose, preconditions, scope restrictions, irreversibility, edge cases, and error behavior. The only omitted items, token and client_id, are documented in the schema, and the output schema exists, so nothing an agent needs to invoke the tool correctly is left unresolved.

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?

Although the top-level params wrapper has no schema description, the nested GuideDeleteInput properties are documented and the description adds further meaning: guide_id should come from rca_guide_list or rca_guide_search, and confirm must be true or an 'aborted' error is returned. The description does not discuss token or client_id, but those are straightforward and already described in the nested 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 opens with 'Permanently delete an equipment guide you ingested,' a specific verb and resource that clearly identifies the operation. It also distinguishes the tool's scope by noting the 4 built-in shared sample guides cannot be deleted, which separates it from broader deletion tools among the 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 description explicitly says deletion is scoped to your own guides and that the built-in samples can never be deleted this way, giving clear when-not-to-use guidance. It also names re-ingest alternatives (rca_guide_ingest or rca_guide_ingest_pdf) if the guide is needed back, providing concrete recovery routing.

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 mark this as read-only, idempotent, and non-destructive, and the description adds useful behavior beyond them: it returns plan_required for Starter users requesting Pro formats, it errors on unresolved sessions, and it lists the report's contents. No contradiction exists between the description and annotations.

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 organized with a clear purpose statement, prerequisite warning, report-content summary, and arg bullets. It is somewhat long and repeats the 'resolved session' requirement twice, but the structure is readable and front-loaded with the most important call condition.

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 has an output schema, so return-value details are not required here. The description adequately covers prerequisites, failure behavior, plan gating, and parameter semantics, making it complete enough for an agent to call correctly. It could have addressed sibling alternatives like rca_report_generate, but that is a minor 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?

Despite the reported 0% schema-description coverage, the description adds significant parameter context: session_id must be resolved, format has plan-level restrictions, and include_guide_refs/custom_title are explained. It omits token and client_id in the prose arg list, but the input schema supplies descriptions for those, so the overall parameter guidance is strong.

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 ('generate') and a specific resource ('maintenance/troubleshooting report from a completed diagnostic session'), and it clearly connects the tool to the diagnostic workflow. It also distinguishes this tool from siblings like rca_report_generate by requiring a completed diagnostic session via rca_dtree_answer.

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 conditions: the session must already be resolved, in-progress sessions will error, and the user should check rca_dtree_list_sessions. It also explains when the PDF/HTML formats are allowed based on plan level. It does not explicitly name alternative tools, but it provides clear prerequisite and error 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 mark the operation read-only, idempotent, and non-destructive; the description adds valuable behavioral context beyond that: built-in sample guides are readable by every account, only user-created guides are deletable via rca_guide_delete, and a not_found error is returned when a guide/section does not exist or is not the caller's. Return shapes are also disclosed, which goes well beyond the annotations.

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

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

The description is front-loaded with a one-sentence summary and then uses structured Args/Returns blocks; every line adds sourcing, ownership, or return-format context. It is slightly verbose and the emoji/plan note is minor noise, but there is no significant redundancy.

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

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

For a read-only retrieval tool, the definition covers what it returns, how IDs are obtained, error behavior, and shared-guide visibility; the schema and output schema fill in remaining field-level details. No critical call-time behavior is left unexplained.

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?

Context signals report 0% schema description coverage, so the description carries the burden of explaining parameters. It meaningfully explains guide_id and section_id with sourcing and effect, but token and client_id are not addressed in the description even though token is required and client_id affects namespace, so compensation is partial.

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 uses a specific verb ('Retrieve') and resource ('troubleshooting guide' or a named section), and immediately distinguishes whole-guide vs single-section retrieval. It also references sibling tools for provenance and ownership, which helps an agent tell it apart from guide-management 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 explains where guide_id and section_id come from (ingest/search/list, search results, or a prior get call), and clarifies ownership/visibility rules for shared vs user-created guides. It does not give an explicit 'use this instead of rca_guide_search when...' decision rule, so exclusions are implied rather than fully stated.

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 only say readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden. It adds valuable process detail: fault codes (F-###, ERR-###) are auto-extracted for markdown, plain text is split on double newlines, the guide is immediately searchable after ingestion, plan limits apply, and the return JSON contains guide_id, section_count, symptom_count, and fault_code_count. No contradiction with annotations.

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

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

The description is well-structured and front-loaded, with bulleted formats, plan limits, and return shape. Nearly every section earns its place, but the emoji decoration and the partially redundant Args block add slight noise, so it is not perfectly concise.

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 moderate complexity of a nested input and the absence of a visible output schema, the description covers comparable essentials: what formats are supported, how each is processed, what happens after ingestion, plan constraints, and return fields. It does not cover error/duplicate behavior or auth requirements, but the schema documents token and the annotations cover the safety profile.

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 nested schema already documents every field in GuideIngestInput, so the description's Args list is mostly redundant. The real added parameter value is in the format explanations: markdown auto-extracts fault codes, plain splits on double newlines, and json_dtree routes to interactive diagnostics. The Args summary omits token and client_id, which keeps this from a 5.

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 names a specific verb and resource: 'Upload and index an equipment troubleshooting guide into the knowledge base.' It also distinguishes itself from a clear sibling by saying 'Use rca_guide_ingest_pdf instead if you're starting from an actual PDF file.' An agent can tell exactly what this tool does and what it is not for.

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 explicitly tells the agent when to use the PDF sibling versus this tool, and it gives format-selection guidance: markdown is recommended, plain splits on double newlines, and json_dtree is for interactive diagnostics via rca_dtree_start. It also notes the guide becomes searchable via rca_guide_search, which clarifies the post-ingestion workflow.

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 description discloses several important behaviors beyond the annotations: non-PDF rejection via file signature, 50MB size cap, automatic quality gate, bypass behavior, plan limits, and return fields. This goes well beyond the readOnly/destructive/idempotent hints and gives the agent a realistic model of what will happen.

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 well organized and front-loaded with the core purpose and constraints, followed by workflow, quality gate, plan limits, and returns. It repeats the 50MB limit twice and includes a minor emoji distraction, but the length is largely justified by the tool's complexity.

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 description covers input validation, size limits, quality threshold behavior, plan limits, a recommended workflow, and the expected return payload. Given the annotations and schema, an agent has enough context to understand when and how to invoke the tool successfully.

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 narrative adds useful context for min_quality_threshold and skip_preview_check, and the Args section lists most parameters. However, the schema description coverage signal is 0%, and the description does not fully compensate by explaining each parameter's meaning; it also omits the required token parameter from its parameter list, relying on the schema to fill in those details.

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: parse a PDF equipment manual and ingest it into the RCA knowledge base. It also distinguishes the tool by its PDF-specific input handling and file-signature validation, which separates it clearly from siblings like rca_guide_ingest and rca_guide_pdf_preview.

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 an explicit recommended workflow: preview first, ingest if quality is adequate, then search to verify. It also explains when to bypass the quality gate with skip_preview_check and names the related sibling tools, giving an agent concrete routing 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 declare read-only, idempotent, non-destructive behavior, so the description doesn't need to restate that. It adds useful non-obvious behavior: results include the 4 built-in shared samples and availability spans all plans. This is sufficient extra context beyond the structured hints.

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 core behavior, then moves compactly through args and return shape. No sentence is wasted: the built-in sample note, filter semantics, downstream-ID usage, and JSON return format all earn their 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?

For a simple read-only list operation, the description covers the important behavioral nuance (built-in samples), return shape, and downstream usage. It lacks only minor details such as pagination/limits or ordering, but the presence of an output schema and the read-only annotations keep the tool callable without those.

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 description explains the two user-meaningful filter parameters (equipment_type, tags) with 'omit for all' semantics. It does not mention token or client_id in prose, and the schema-description coverage signal is low, so the agent must rely on the nested schema for auth/client context; this is a clear but acceptable 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 opening sentence names a specific action ('List') and a concrete resource ('ingested troubleshooting guides'), and adds a distinguishing detail: the 4 built-in shared samples are included. It also points forward to related tools (rca_guide_get, rca_guide_delete, rca_dtree_start) that consume the guide_id, which disambiguates it from the surrounding guide 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 says this is the list/listing step and explicitly tells the agent to use the returned guide_id with rca_guide_get, rca_guide_delete, or rca_dtree_start. Optional filtering by equipment_type/tags gives clear context for when it applies, though it stops short of explicitly contrasting with rca_guide_search.

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 the tool read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: this is a pre-ingestion verification step, OCR requires Tesseract as a dependency, and the tool returns rich preview data such as detected_strategy and estimated_quality. No contradiction with annotations.

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

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

The description is well organized and front-loaded with the core purpose and mandatory ordering before ingestion. The strategy and return sections are clear and compact. Minor deductions for the noisy 'Starter+' label and an Args line that is incomplete, missing token and client_id.

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 read-only preview tool with rich annotations and an input schema, the description is largely complete: it states purpose, ordering, strategy options, dependencies, and return fields. It does not explicitly mention authentication, but the schema requires token, so that information is available to the agent. Overall, it gives enough context to select and invoke the tool correctly.

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

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

The description adds real meaning for the strategy parameter, explaining each strategy's intended use case and recommending auto as the default. However, it only lists pdf_base64, n_pages, and strategy in the Args section, omitting the required token and client_id. Given the low schema description coverage signal, it does not fully compensate for all parameter semantics, though the schema itself covers the omitted 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 specific action ('Preview a PDF document'), a clear resource ('a PDF document'), and the goal ('verify parsing quality'). It is immediately distinguishable from the sibling rca_guide_ingest_pdf, which is the full ingestion step.

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 explicitly says 'Always call this BEFORE rca_guide_ingest_pdf', giving a precise ordering rule. It also provides strategy selection guidance by explaining when to use text_native, ocr, table, mixed, or auto, which helps the agent choose the right parsing mode.

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 mark it readOnly and idempotent; the description adds genuinely useful behavior: TF-IDF relevance ranking, a free-plan cap of 3 results, and the fact that both private and shared sample guides are searched. No contradiction with annotations.

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

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

The description is compact and structured: purpose is front-loaded, scope follows, then Args and Returns are clearly labeled. No filler 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?

It covers search scope, ranking method, plan cap, and return shape. It is slightly incomplete because the Args summary omits token/client_id, but the nested schema and output schema supply most of the remaining detail.

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 Args section lists only symptom, equipment_type, tags, and top_k, omitting required token and defaulted client_id. It gives no types or constraints beyond the top_k range, and with 0% schema description coverage reported, the description does not carry enough of the parameter-documentation burden.

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: 'Search the equipment knowledge base by symptom description using TF-IDF relevance ranking.' It also clarifies search scope (own ingested guides plus 4 shared sample guides), which separates it from sibling retrieval/list tools like rca_guide_get and rca_guide_list.

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 (when matching symptom descriptions against guides) and provides plan constraints, but it does not name alternatives or say when not to use it, such as when an exact guide ID is already known.

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 indicate this is a write operation that is not idempotent and not destructive, and the description adds valuable behavioral details: the model starts in 'draft', creating doesn't run anything, and hitting the plan limit returns a plan_required error. This goes beyond the annotations and helps the agent predict side effects, though it could also mention what happens on duplicate names or whether deletion is required before recreating.

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 well-structured with purpose front-loaded, followed by limits, lifecycle, families, args, and return. It is a bit long and partially duplicates the family enum already present in the schema, but every major section earns its place by adding operational or semantic context.

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

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

Given the tool's complexity and the lack of top-level schema descriptions, the description is complete: it explains status, side effects, plan limits, lifecycle routing, parameter semantics, and the return value including an error case. An agent has enough information to decide whether and when to call this tool and what to pass.

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?

Although schema description coverage is reported as 0%, the description compensates thoroughly by explaining each key field's meaning and purpose: name is for reference only, family selects the algorithm, config is passed through at run time, and description/tags/version are optional organizational metadata. This adds real semantic value beyond the bare schema field names.

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

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

The description clearly states the specific verb ('Register'), the resource ('a new RCA model spec'), and the immediate outcome ('starting in draft status'). It also explicitly contrasts with other lifecycle tools ('it doesn't run anything') and names the siblings in the lifecycle, so the agent can distinguish it from rca_model_update_status, rca_analysis_run, and rca_model_delete.

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 when-to-use guidance: create is the first step in a typical lifecycle, and the full sequence is laid out. It also provides operational context by mentioning plan limits and pointing to rca_admin_show_plan_info to check capacity, and it clearly says create only stores the spec, preventing misuse as an execution 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?

Beyond the destructiveHint=true annotation, the description discloses irreversibility, that existing results remain retrievable via rca_analysis_get_result, and that new analyses can no longer use this model_id. It also documents error behavior for confirm=false and for missing or non-owned models. This is exactly the operational context needed 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 well-organized into a warning, an alternative usage path, Args, and Returns. No sentence is wasted, and the critical irreversibility warning is front-loaded before the details.

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 destructive deletion tool, the description covers prerequisites, postconditions, error cases, and return value. It also routes to the appropriate sibling for the non-destructive alternative, making it complete for correct invocation and decision-making.

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 Args section adds useful plain-language meaning to model_id and confirm, including the 'aborted' error when confirm is not true. It omits explicit descriptions of token and client_id, but the nested schema already provides clear descriptions for those fields, so the description still adds meaningful 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 opens with a specific verb and resource: 'Permanently delete a model from the registry and storage.' It clearly distinguishes this tool from rca_model_update_status by explaining that delete is irreversible and for when you no longer need the spec. An agent can immediately tell what this tool does and how it differs from its 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 description explicitly states when to use this tool: 'delete is for when you're certain you won't need the spec again.' It also names the alternative, rca_model_update_status, for marking a model deprecated while keeping it available. It further specifies that confirm=true is required and explains the consequence for future analyses.

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. The description adds useful behavioral context by scoping results to the caller's own registered models, explaining optional filters, and documenting the JSON return shape. No contradiction with annotations.

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

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

The description is compact and front-loaded with the core purpose. It uses clearly labeled Args and Returns sections, and every sentence adds functional value with 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 simple read-only listing tool with safety annotations and an explicit return format, this is nearly complete. It does not discuss pagination or specifically call out the token requirement, but those are either implied by the schema or low-risk for this operation.

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 Args section explains family_filter and status_filter with 'omit for all' semantics, which aligns with the schema, but it does not mention the required token or client_id. The schema documents those properties, so the description partially compensates but does not add much meaning beyond the schema's own parameter descriptions.

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 uses a specific verb and resource: 'List all of YOUR registered RCA models'. It also states concrete downstream use cases (finding a model_id for rca_analysis_run and checking plan-model-count usage), making it clearly distinct from analysis, graph, and guide listing 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?

It explicitly tells the agent when to use the tool: to find a model_id for rca_analysis_run or to check model-count usage against the plan, and it references rca_admin_show_plan_info for the limit. It does not enumerate when-not-to-use alternatives, but the intended contexts are unmistakable.

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 description discloses that no state-machine validation is enforced and that deprecated models remain queryable, which adds valuable behavioral context. It does not mention idempotent behavior or auth-required details, but those are partially covered by annotations and 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?

The description is organized into clear purpose, usage guidance, args, and returns sections. Some repetition occurs (e.g., the 'no enforced order' point is made twice), but it remains focused and scannable without significant fluff.

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 description covers the key behaviors, return format, and error case (not_found), plus relationships to delete/validate tools. It does not explicitly address client_id, token, or idempotency, but annotations and schema fill those gaps sufficiently for this tool'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?

The description explains model_id and new_status, including the allowed enum values inline. It omits token and client_id, but those have explicit descriptions in the schema, so the added value is adequate though not maximal.

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 action ('Set a model's lifecycle status'), enumerates all allowed values, and distinguishes it from related tools like rca_model_delete. An agent can immediately understand what the tool does and when it 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?

It explicitly explains when to use 'deprecated' vs 'failed', clarifies that the operation is an unguarded direct field update, and directs users to rca_model_delete when deletion is intended. This gives clear conditional guidance beyond what annotations provide.

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 description discloses a key side effect not visible from the annotations: it sets the model status to 'validated' on success. It also sets accurate expectations about the lightweight nature of the check and mentions possible error returns, adding behavioral context beyond the schema and annotation 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?

The description is front-loaded with the core purpose, then adds usage caveats, side effects, and parameter details in a clear, scannable structure. The Args/Returns sections are compact and every sentence contributes useful information without redundancy.

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

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

The description covers what the tool does, how to provide inputs, what side effect occurs, how it relates to sibling tools, and what return value to expect. For a validation tool with this complexity, nothing essential is missing for an agent to select and 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?

Although the raw parameter names appear in the schema, the description adds critical semantics: model_id comes from rca_model_create, validation_data must match the shape of an rca_analysis_run payload's 'data' field, and target refers to a variable inside validation_data. This meaningfully reduces ambiguity beyond the schema descriptions.

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: 'Run a quick correlation-based sanity check of a model against hold-out data you supply.' It clearly distinguishes this from full cross-validation or backtesting, and from rca_model_update_status, which is a sibling tool with a different purpose.

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 when to use it ('catch an obviously broken model') and when not to ('not to certify accuracy'), clarifies that hold-out data must be supplied separately rather than auto-split, and explains that calling rca_model_update_status afterward is unnecessary for 'validated' but can be used for other statuses.

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 and idempotentHint=true, and the description reinforces this by calling the operation a documentation lookup. It adds behavioral context by enumerating the supported providers and stating the return type, which goes beyond the annotations. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the core purpose, followed by a useful enumerated provider listches, an Args summary, and a return type. Every section earns its place and the length is justified by the provider enumeration.

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 documentation-lookup tool with readOnly/idempotent annotations, the description is complete: it gives the use case, provider list, parameter behavior, and return type. The output schema exists, and the safety profile is fully covered by annotations, so no critical operational information 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?

The description explains the key 'provider' parameter and the omit-to-list-all behavior, but it does not mention the required 'token' parameter or 'client_id' in the Args section. The nested schema does define these fields, but with schema description coverage reported as 0%, the description only partially compensates for the low coverage.

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 action ('Get MCP client configuration and setup instructions') and a clear resource ('for a specific provider or list all supported providers'). It also distinguishes itself from sibling tools by noting this is documentation lookup and does not affect RCA-MCP's own behavior.

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 trigger condition: 'Use this when a user asks how do I connect RCA-MCP to X'. It also clarifies what the tool is not for ('not something that affects RCA-MCP's own behavior'), providing a clear context. It does not explicitly name alternative sibling tools, but the use case is sufficiently scoped.

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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint: false), the description explains the actual algorithm: z-score thresholding, comparing normal vs. incident windows, and flagging metrics as candidates. It also discloses the output shape and ranking by |z_score|. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with purpose and algorithm. The Args and Returns sections make it scannable. The attribution and citation add some length beyond what an agent strictly needs, but they do not obscure the actionable content.

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 description covers what the tool does, how it works, when to use it versus alternatives, prerequisites, key parameters, and the return format. Combined with the rich annotations and output schema, an agent has enough context to select and invoke the tool correctly.

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

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

With 0% schema description coverage at the top level, the Args section compensates by explaining normal_data, anomaly_data, sli_metric, and epsilon including the default 3.0 and its meaning. It omits token and client_id, but those are auth/namespace boilerplate and their schema descriptions already provide enough context.

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: 'Identify anomalous metrics contributing to a Service Level Indicator (SLI) anomaly'. It also explains the z-score mechanism and explicitly distinguishes this tool from causal siblings like rca_pyrca_ht_diagnosis and rca_pyrca_random_walk by noting it requires no causal graph.

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 explicitly states when to use this tool: 'Best used as a FIRST STEP in RCA to narrow down candidate metrics before applying more compute-intensive causal methods'. It also names the alternatives and notes the prerequisite 'Requires the pyrca feature (Starter+)'.

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 the tool read-only, idempotent, and non-destructive, so the description does not need to restate safety. It adds meaningful behavioral context beyond annotations by explaining the statistical mechanism, the descendant adjustment that reduces indirect cause scores, and the return format identifying root causes. It also discloses the algorithm's provenance and adaptation from PyRCA, increasing trust and predictability.

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 longer than average, but it earns its length: it front-loads the core algorithm summary, then gives selection guidance, a compact parameter list, return format, and attribution. The attribution and citation lines are slightly extraneous for tool invocation, but they provide useful provenance. Overall, the structure is logical and each section serves a purpose.

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 complex statistical RCA tool, the description is nearly complete: it explains the algorithm, when to use it versus alternatives, the required feature tier, key parameters, and the return format. Minor gaps exist around the exact adjacency structure and authentication token requirement, but these are covered in the nested schema. The description gives an agent enough context to select the tool correctly and invoke the main causal-analysis 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?

Despite the context signal indicating 0% schema coverage, the description compensates by enumerating the meaningful parameters: data, adjacency, sli_metric, anomaly_start_idx, significance, and use_descendant_adjustment, each with a concise semantic and, where relevant, a default value. It does omit the auth token and client_id parameters, but those are less algorithmically central and may be obvious from the schema. It also does not restate constraints like the p-value range or min pre-period points, though those are present in 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 uses a specific verb phrase ('Tests whether the SLI anomaly can be statistically explained by causal propagation from each ancestor node') and clearly names the resource: PyRCA HT-ADJ / CIRCA hypothesis-testing RCA. It explicitly differentiates itself from sibling tools by naming rca_pyrca_epsilon_diagnosis and rca_pyrca_random_walk as alternatives, so an agent can disambiguate without opening schemas.

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 when-to-use guidance: recommended when you have a well-validated causal graph and sufficient pre-anomaly data. It also states concrete alternatives with conditions: use epsilon if you don't have a graph yet, use random walk if you have a graph but not enough pre-anomaly history. The prerequisite 'Requires the pyrca feature (Starter+)' further clarifies eligibility.

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 indicate readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail: how the algorithm propagates through the graph, that it weights transitions by anomaly scores, and that it returns ranked root causes with convergence information. It also clearly states what inputs it does not compute, preventing incorrect expectations.

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 well-structured and appropriately sized. The core algorithm is stated first, followed by prerequisites and sibling contrast, then a concise parameter list and return description. The attribution line is at the end and does not interfere. Every sentence contributes to correct invocation.

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 relatively complex tool with prerequisites, algorithm-specific behavior, and a nuanced relationship to sibling tools. The description covers what the tool needs, what it does not compute, how to invoke it at a parameter level, and what it returns. Nothing critical for correct use 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 description coverage is reported at 0%, so the description carries the burden of explaining parameters. It does so thoroughly: adjacency is a {source: {target: weight}} causal graph, anomaly_scores are metric magnitudes, sli_metric is the starting node, and restart_prob is explained as personalisation where higher means more proximity-weighted. This adds real semantic value beyond raw schema field names.

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 algorithm and resource: 'Graph-based root cause localisation via personalised PageRank random walk.' It clearly explains the mechanism (propagating backward through a causal adjacency graph from the SLI node) and distinguishes itself from a sibling tool (rca_pyrca_epsilon_diagnosis). This gives an agent a precise mental model of what the tool does.

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

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

The description explicitly specifies when to use this tool: it requires the pyrca feature (Starter+), an existing adjacency graph, and precomputed anomaly scores. It also names the alternative rca_pyrca_epsilon_diagnosis and notes the key difference—this tool does not compute anomaly scores itself. This is strong usage guidance with clear prerequisites and sibling differentiation.

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; the description reinforces this with 'read-only diagnostic, not an action.' It adds useful behavioral context beyond the annotations by explaining what the tool checks, that the call needs no configuration, and that the recommendations field indicates what to fix — helpful for agents handling unexpected PyRCA errors.

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 well-structured and front-loaded: purpose first, usage next, then a succinct checklist, and finally a compact return summary. Every sentence earns its place, and the bulleted checks improve scannability without bloating the text.

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 description is complete for a read-only validation tool. It covers what the tool does, when to call it, what conditions are checked, and what the response contains. It names the upstream dependent tools and handles the error-recovery case, so an agent has everything needed to select and 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?

The schema already describes token and client_id, so the baseline is 3. The description adds meaning beyond the schema by clarifying that these are purely authentication parameters and that 'there is nothing else to configure on this call,' preventing the agent from inventing configuration steps. It could say a bit more about token/client_id roles, but the schema covers those details.

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: validate the PyRCA integration setup and report which strategy is active. It clearly labels the call as a read-only diagnostic rather than an action, which distinguishes it from the rca_pyrca_*_diagnosis siblings and other rca_* 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?

Explicitly tells the agent when to run this: before the first rca_pyrca_epsilon_diagnosis, rca_pyrca_ht_diagnosis, or rca_pyrca_random_walk call when unsure of the active strategy, or when a PyRCA call errors unexpectedly. This is concrete, actionable guidance that also names the related 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?

Annotations are mostly false/uninformative, so the description carries the behavioral disclosure burden. It does this well: it discloses the default save behavior, plan gating for html, and the output type. It could be more explicit about the side effect of persisting reports, but the save parameter description covers this adequately.

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 well-structured and front-loaded: purpose, sibling differentiation, plan caveat, then clearly organized args and return value. Every sentence adds useful information and there is no filler or repetition of schema content.

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 tool with a nested input object and plan-dependent behavior, the description covers the essential call context: ID source, count constraints, format options, save defaults, and return shape. It does not explicitly describe client_id semantics, but that field is documented in the input schema and is not central to 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%, so the description must compensate. The Args section explains result_ids, format, title, and save semantics, including source tools, defaults, and plan restrictions. It omits token and client_id, but those are less agent-critical and the schema itself provides basic descriptions for them.

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: 'Generate a comparative report across 2–10 RCA results' and lists concrete outputs (consensus root causes, model agreement percentages, per-model summaries). It also explicitly distinguishes itself from rca_analysis_compare by targeting a shareable formatted document rather than raw JSON.

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 use this tool instead of rca_analysis_compare when a formatted document is wanted, giving a clear decision rule. It also provides plan-specific guidance for the html format and free plans, and tells the agent where result IDs come from (rca_analysis_run or rca_analysis_list_results).

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 are all false hints ('readOnlyHint: false', etc.), so the description carries the full burden and delivers richly: plan gating that 'returns a security_violation error, not a silent downgrade', per-format dependency fallbacks ('falls back to plaintext if not installed'), and save semantics (report_id/storage_path only when saved). No contradiction with annotations exists.

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 long (~250 words) but well-structured with purpose, supported formats, common content, args, and returns sections, and the core routing is front-loaded in the first sentence. The Args/Returns sections somewhat duplicate schema and earlier descriptive content, so it could be trimmed, but the length is largely justified by format-specific behavior.

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 tool with three required params and format-dependent behavior, the description covers when to use it versus siblings, per-format gating and fallbacks, shared report contents, save behavior, and return structure — and an output schema exists to back up the return-value claims. Minor omissions such as the auth token source are already visible in the 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 reported as 0% for the top-level wrapper, and the description compensates thoroughly: it explains what each format produces, that include_raw appends a raw model output appendix, and that save persists the report and returns identifiers. It also documents the return payload fields (content_b64, content_text, byte_size, report_id, storage_path), going beyond what the input schema alone provides.

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 names a specific verb ('Generate'), a specific resource ('styled, professional report'), and a scope restriction ('from a SINGLE RCA analysis result'). It explicitly routes to rca_report_compare for the multi-result case, distinguishing it from the closest sibling without needing to inspect 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?

Provides an explicit when-not instruction and alternative: 'use rca_report_compare instead if you want a report covering multiple results together.' It also gives format-selection guidance through plan tiers (Free/Starter+/Pro+) and per-format context (e.g., markdown is 'good for GitHub/Slack/Notion').

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