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

Annotations already declare a non-read-only, non-destructive, open-world mutation, so the safety profile is covered. The description adds the validity matrix, which is genuinely behavioral, but says nothing about duplicate-link handling, reversibility, permission requirements, or what happens when an invalid type pair is supplied.

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

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

The core action is front-loaded in the first line and the remaining text is a compact rule table with no filler sentences. The compressed arrow notation is terse but readable; nothing is redundant.

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

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

An output schema exists, so return values need not be described. Still, for a seven-parameter open-world mutation with zero schema descriptions, the missing semantics for product_id and comment and the absence of failure/duplicate behavior leave real gaps an agent would want filled.

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

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

Schema description coverage is 0%, so the description must carry the load: it documents association_type values and constrains source/dest type combinations well. However, comment and product_id — two of the seven parameters — get no explanation at all, so the coverage gap is only partially compensated.

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?

Opening verb+resource pair 'Link two artifacts' is specific and distinct from sibling creators like product_create_artifact and create_comment. It does not explicitly name a sibling to contrast with, but the action is unambiguous enough that an agent won't confuse it with artifact mutation 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 allowed source->dest matrix per association_type is effectively a legality guide: an agent can determine before calling whether a given pair is permitted and which association_type applies. What is missing is guidance on prerequisites (do both artifacts need to pre-exist, is product_id required for cross-product links) and on alternatives.

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=false, destructiveHint=false, and openWorldHint=true, so the write/safety profile is known. The description adds no behavioral context of its own: nothing about who the comment is attributed to, whether it can be edited or deleted afterward, whether product_id is required for certain artifact scopes, or any permission/visibility constraint.

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

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

Two short sentences, action first and the read-side pointer second. Nothing is padded or repeated from the schema or annotations.

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

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

An output schema exists, so return values need no explanation, and annotations cover the safety profile. However, for a four-parameter mutation with 0% schema description coverage, the description should at least clarify the artifact targeting and optional product_id, which it omits entirely.

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

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

Schema description coverage is 0% across four parameters, so the description carries the burden and does not meet it. It never mentions artifact_id, artifact_type, text, or the optional product_id, and leaves ambiguous when product_id must be supplied and how artifact_type interacts with artifact_id.

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

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

States a concrete verb and resource ("Add a comment to an artifact"), which is immediately distinguishable from siblings like product_create_artifact or create_association. It does not enumerate which artifact types accept comments, but the schema enum covers that, so it is clear without being redundant.

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 the read path to product_get_artifact with include=["comments"], giving the agent a concrete alternative for the inverse operation. It stops short of stating when a comment is the right action versus updating the artifact or when the tool should not be used (e.g., unsupported artifact types).

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

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

Annotations already declare this as a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds real behavioral detail: the exact return shape and the existence of an error branch that carries valid_types. That error-path disclosure is genuinely useful for recovery. It stops short of noting pagination or cost, but for a small read-only lookup that is a minor gap.

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

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

Front-loaded purpose sentence, then the value list and return shape. Every element is compact. Slight redundancy in restating the return shape, which the output schema already defines, keeps it just under top marks.

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

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

An output schema exists, so return values need no further explanation, and the description still supplies the accepted input values and error shape. Nothing an agent needs in order 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 0% and the single parameter has no enum in the schema, so the description carries the full burden — and it does, enumerating all eleven accepted artifact_type values plus the error payload that returns valid_types. It adds substantial meaning beyond the bare 'type: string' schema.

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

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

States a specific verb and resource ('Returns the field schema for a Spira artifact type as JSON') and an explicit output format. It is clearly distinguishable from every sibling, which are search/get/create/update artifact tools rather than schema introspection.

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 enumeration of valid artifact types implies the tool's role (discovering fields before creating or updating artifacts), but the description never states when to call it, when not to, or that it should precede product_create_artifact or product_update_artifact. Usage is inferable rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the 'assigned to current user' scoping idea, and says nothing about pagination behavior (despite limit/offset), ordering of results, or how 'assigned' is determined.

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

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

The description is short and front-loads the purpose, which is good. But the second block merely duplicates the schema enum, a sentence that does not earn its place, while leaving more valuable information out.

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

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

An output schema exists so return values need not be explained, but with 6 undocumented parameters, no usage guidance, and ambiguous sibling tools, the definition leaves an agent without enough to invoke it correctly.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate and does not: limit, offset, status, priority and fields are entirely unexplained. The one parameter it does mention, artifact_type, only repeats the enum already present in the schema, adding no meaning.

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 ('Retrieve ... artifacts') and narrows the scope to the current user's assigned items. However, it never distinguishes this tool from the similarly named siblings product_search_artifacts and program_search_artifacts, so an agent cannot tell from the text alone which search surface to pick.

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

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

There is no statement of when to use this tool versus the sibling search tools, no mention of prerequisites or authentication context. The only guidance is a restatement of the artifact_type enum values, which is not usage 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 this as a non-read-only, open-world, non-destructive creation tool. The description adds useful behavioral context about required fields and type-dependent parameters. It does not mention permissions or side effects, but with annotations covering the safety profile and an output schema present, this is adequate.

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?

Four tightly written sentences, front-loaded with the core action and followed by conditional requirements. Every sentence adds relevant guidance 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?

Given the output schema and annotations, the description covers the main creation requirements and routes agents to get_artifact_schema for type-specific fields. The main remaining gap is that the 'fields' parameter format is not described, but the schema pointer mitigates this for a tool with eleven artifact types.

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

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

Schema description coverage is 0%, so the description must compensate. It explains conditional roles for parent_id and release_id, and hints at fields content via required name/description and the get_artifact_schema pointer. However, it leaves the core 'fields' array structure and product_id semantics unexplained, so compensation is only 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 description states a specific verb and resource: 'Create artifacts in a Spira product.' This clearly distinguishes it from siblings like product_update_artifact and product_get_artifact. It does not explicitly contrast with create_association or create_comment, but the resource and action are unambiguous.

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

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

It provides clear conditional guidance: name and description are required for most types, sub-artifacts require parent_id, builds require release_id, and optional fields are discoverable via get_artifact_schema. It lacks an explicit 'use this instead of update_artifact' statement, but routing to the schema tool is a strong usage signal.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by explaining that include can expand test_steps, mitigations, steps, comments, associations, and coverage, and that release_id is required for builds.

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

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

The description is short, front-loaded, and line-oriented by parameter. Every line adds useful information about valid types, conditional requirements, or include behavior, 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 get-by-ID tool with an output schema, the definition covers the critical enum and conditional-parameter behavior. The only minor gap is that product_id is not explained, but the overall retrieval contract 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?

Schema description coverage is 0%, so the description must carry parameter meaning. It fully enumerates artifact_type values, documents the conditional release_id requirement for build, and lists valid include values, but it does not explain product_id or artifact_id beyond their 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 verb and resource: "Retrieve a single artifact by ID from a Spira product." It also enumerates all supported artifact types, and the phrase "single artifact by ID" distinguishes this direct lookup from the sibling search 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 makes the retrieval context clear: a single artifact fetched directly by ID, rather than a search or list operation. It does not explicitly name search_artifacts as the alternative, but the distinction from sibling search tools is strongly implied.

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

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

Annotations already disclose that this is a non-read-only, open-world, non-destructive mutation. The description confirms it records a test result and adds useful field-level constraints, but it does not explain side effects, duplicate behavior, permissions, or what happens on failure.

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

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

The purpose is front-loaded in the first sentence, followed by only the parameter details that need clarification. There is no redundant or filler 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 output schema exists, and annotations cover safety, so return values and side-effect profile are partially handled. However, for a seven-parameter mutation tool, the description does not fully explain several parameters or provide usage guidance, leaving clear gaps.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It valuably explains the execution_status_id enum mapping, test_case_id format, and short_message length, but leaves product_id, error_count, long_message, and test_name without added semantic guidance.

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: recording an automated test result in Spira. It is clear enough to distinguish this specialized test-run recording tool from general artifact search/get/create/update siblings, though it does not explicitly name those alternatives.

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

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

The description gives no explicit guidance about when to use this tool versus alternatives such as product_create_artifact or product_update_artifact. The word 'automated' implies a context, but there are no prerequisites, exclusions, or routing instructions.

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 this as a read-only, non-destructive, open-world operation. The description adds useful context beyond that, such as the filter object shape and the conditional build requirement for release_id, but it does not describe pagination behavior, result limits, or other operational traits.

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 action and then provides two compact usage notes. It is efficient and mostly waste-free, though it is perhaps too terse for a tool with this many parameters.

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 16 parameters, very low schema description coverage, and multiple sibling search tools, the description is not complete enough to guide an agent on most optional parameters or distinctions. It does point to get_artifact_schema and an existing output schema covers returns, but large parts of the input surface remain 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?

Schema description coverage is only 13% across 16 parameters, so the description carries a heavy compensation burden. It explains the filters format and release_id conditional requirement, and points to get_artifact_schema, but leaves most parameters such as owner_id, priority, component, include, fields, and pagination undocumented.

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 artifacts") and scopes it to a Spira product, which helps distinguish it from mywork_search_artifacts and program_search_artifacts. It is clear but does not explicitly name those sibling alternatives, so it falls short of a 5.

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

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

It provides implied usage guidance: product-scoped search, use get_artifact_schema for filter fields, and release_id is required for builds. However, there is no explicit statement of when to use this tool versus mywork_search_artifacts or program_search_artifacts, nor any when-not guidance.

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

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

Annotations already establish readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds real context (parent_id requirement for sub-artifacts, null to clear custom properties) but omits the most important behavioral question for an update tool: whether `fields` merges into existing values or replaces them entirely.

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

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

Three short sentences, front-loaded with the core action, followed by the two non-obvious caveats. No filler; every sentence carries information an agent would otherwise have to guess.

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

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

Output schema exists, so return values need not be described. However, this is a mutation tool with a nested free-form `fields` object at 0% schema coverage, and the description never states whether omitted fields are preserved or wiped — a gap an agent cannot resolve from structured data alone.

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

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

Schema description coverage is 0% across 5 parameters, so the description must carry the load. It explains parent_id's conditional requirement and that `fields` keys are discovered via get_artifact_schema, which partially compensates, but product_id, artifact_id, and the structure/merge semantics of the free-form `fields` object are left undiscussed.

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

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

States a specific verb and resource ("Update a single artifact by ID") plus the scoping system (Spira product), so it is clearly distinct from product_create_artifact and product_get_artifact in the sibling list. It does not explicitly name the sibling it complements, but the verb alone disambiguates.

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 concrete conditional guidance: sub-artifact types (test_step, mitigation, requirement_step) require parent_id, and it routes the agent to get_artifact_schema for writable fields. Also tells the agent how to clear a custom property. Missing explicit when-not-to-use guidance (e.g., bulk updates or creating new artifacts).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds essentially nothing beyond them: 'program_id: required, no default' repeats the schema's required list, and it says nothing about how filters, status, priority, or pagination behave or how large result sets are returned.

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

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

Three short lines, front-loaded with the core action and the key constrained parameters. The telegraphic style wastes no space, though it borders on under-specification rather than crisp concision.

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

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

With eight parameters, 0% schema coverage, and no output-schema explanation needed, this description is far too thin — a caller cannot form a valid filters value or know how starting_row/number_of_rows interact with the default 100-row page. It covers only the two required fields.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it only explains artifact_type and program_id. The six other parameters — fields, status, filters, priority, starting_row, number_of_rows — get no semantics, and 'filters' in particular is an untyped array of objects whose shape is never hinted at.

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 artifacts') and scopes it to 'a Spira program', which distinguishes it from siblings like mywork_search_artifacts and product_search_artifacts operating in other scopes. It never names those siblings explicitly, so the differentiation is implied rather than stated.

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

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

There is no when-to-use guidance and no mention of the many alternative search/get tools (product_search_artifacts, product_get_artifact, mywork_search_artifacts) an agent must choose between. The agent must infer from the tool name whether this is the right search surface.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds that omitted filters return everything and that some sections only apply to certain artifact types — genuinely useful behavioral context. It says nothing about error handling, permissions, or response size, so it is a middling score rather than a high one.

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?

One lead sentence followed by a tight per-parameter list and a one-line return shape. Front-loaded with purpose, no filler, and every line carries information an agent needs.

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

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

An output schema exists, so the brief 'Returns JSON: {template_id, sections, warnings}' line is slightly redundant but harmless confirmation. For a read-only, three-parameter retrieval tool the description covers purpose, scoping, and return shape adequately; the only real omission is how to choose between this and get_artifact_schema.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: it documents all three parameters, including the ID format ('45 for PT:45'), the default-to-all behavior for both optional filters, and an example artifact_type value. It defers enum values to the schema ('see enum') rather than enumerating the eight metadata types, which keeps it 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?

States a specific verb+resource: 'Retrieves template metadata sections for a product template.' An agent can tell this is a metadata-reading tool rather than an artifact search/update tool, which covers most siblings. It does not explicitly contrast with the closest sibling, get_artifact_schema, so it falls short of a 5.

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

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

The parameter notes ('Omit for all', 'filter to one kind', 'severities→Incident, importances→Requirement') give practical guidance on how to scope a call, which is implied usage context. However there is no explicit statement of when to use this versus get_artifact_schema or the search tools, and no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety/mutation behavior is covered structurally. The description adds no behavioral context beyond that — nothing about what happens when the ID doesn't exist, when workspace_type doesn't match the ID's entity type, or about lookup failures.

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

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

Two short, front-loaded sentences with no filler; the verb and resource come first. The enum restatement is slightly redundant with the schema but not wasteful enough to penalize heavily.

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

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

An output schema exists, so return values needn't be described. However, with 0% schema description coverage and a type+ID pairing that must match, the description should explain the relationship between the two parameters and any failure modes; that context is missing.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does clarify that workspace_id is numeric and restates the workspace_type enum values (which the schema already enumerates). It adds no meaning about how type scopes the ID lookup, so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource ('Retrieve a single workspace entity') plus the keying mechanism ('by its numeric ID'), so the operation is unambiguous. It does not, however, distinguish itself from the sibling workspace_search tool, which is the main look-alike.

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

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

The phrase 'by its numeric ID' implies the usage context (you already know the ID, so use this instead of a search), but it never says so explicitly nor names workspace_search as the alternative for lookup-by-criteria. Usage is inferable rather than 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. Beyond that the description discloses nothing: no mention of whether program_id narrows results, whether paging applies, or how many workspaces come back. With annotations doing the safety work, the bar is lower, but there is still no added behavioral context.

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

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

Very short and front-loaded, but the second line duplicates the schema enum rather than spending those words on the undocumented fields and program_id parameters. It reads as under-specified rather than deliberately lean.

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

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

An output schema exists, so return values need not be explained. However, for a three-parameter listing tool with 0% schema coverage, the description leaves two parameters unexplained and gives no usage context, so an agent cannot reliably call it with fields or program_id.

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

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

Schema description coverage is 0%, so the description carries the full burden for three parameters. It only restates the workspace_type enum values, which are already in the schema enum and add no information; fields and program_id get no explanation at all, leaving their semantics (field projection? parent scoping?) entirely undocumented.

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

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

States a specific verb and resource: "Lists workspaces in Spira." An agent immediately knows this is an enumeration of workspace entities. It stops short of differentiating from the sibling workspace_get (single workspace retrieval) or the product/program/template search tools, which would have earned a 5.

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

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

There is no statement of when to use this versus workspace_get or the product_/program_/template_ search siblings. The only hint is the required workspace_type, from which an agent must infer that this tool is scoped to one workspace kind at a time.

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