Cortex

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

No annotations are provided, so the description carries the behavioral disclosure burden. It does disclose an important edge case: 'Returns nothing when the tenant has no AWS integration.' It does not mention pagination, authorization, or error behavior, but for a simple list operation this level of disclosure 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?

The description is two terse sentences with no filler. The primary operation and output fields are front-loaded, and the edge-case sentence earns its place by setting a clear expectation.

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 names the entity context, the returned fields, and the no-integration behavior, while the schema fully documents the parameters. There is no output schema, so a bit more detail on the exact return shape could help, but the tool is simple enough that the current description is largely sufficient.

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

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

The input schema already describes all three required parameters, including a detailed explanation of session_id and tagOrId. The description adds no additional parameter-level meaning, so the baseline of 3 applies given 100% schema description 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 verb and resource: 'List the AWS resources mapped to an entity, with their type and ARN.' It clearly identifies the tool's scope and output fields, and the 'AWS' qualifier differentiates it from similar resource-listing siblings like KubernetesGetK8sResourcesForEntity.

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 intended use is implied: use this when you need AWS resources associated with an entity. However, the description gives no explicit when-to-use vs. alternatives guidance, no exclusions, and does not name comparable sibling tools. It relies entirely on the agent inferring the appropriate context.

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

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

No annotations are provided, so the description carries the burden of disclosing behavior. It adds useful context about primary/secondary on-call, contact information, and rotation schedules, and indicates real-time freshness. However, it does not mention whether results are cached, what happens if no on-call exists, or any access requirements.

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 tight sentences with no filler. The core function is front-loaded, and the second sentence adds valuable return details without bloating the description.

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 no output schema and no annotations, the description does a reasonable job of explaining the return content (primary/secondary, contacts, rotation). It is slightly incomplete around edge cases like missing on-call data or time-zone handling, but enough for a straightforward read-only 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?

Schema description coverage is 100%, so the schema already documents all three parameters. The description references 'entity' matching tagOrId, but adds no new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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 ('Retrieve') with a specific resource ('current on-call personnel for an entity') and adds a real-time qualifier. Among the large sibling list, no other tool mentions on-call, so this clearly distinguishes itself and tells an agent exactly what it returns.

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

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

No when-to-use guidance, exclusions, or references to alternative tools are provided. With dozens of get* siblings, the description does not help an agent decide between this and related retrieval tools such as getEntityDetails or getTeamDetails.

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

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

No annotations are provided, so the description carries the behavioral burden. It adds useful context beyond purpose: scoping to services/resources/domains and pagination support for large result sets. However, it does not disclose the return structure (there is no output schema), behavior for empty results, or any ordering/side-effect details; the read-only nature is only inferred from 'List'.

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 sentences, all of which earn their place: the core action is front-loaded first, the data scope in the second sentence clarifies what 'custom data' means, and the pagination note in the third addresses a real operational concern. 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?

With no output schema and no annotations, the description carries a heavy burden that it only partially meets. It explains the data categories and pagination but never describes what the response looks like, how pages are structured, or what happens with an unknown tagOrId — gaps an agent needs answered before invoking a paginated list tool.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents all five parameters, including the tricky session_id semantics and pagination defaults. The description adds only general context about what the data contains, not per-parameter meaning beyond the schema, so it neither needs to compensate nor adds much.

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 ('List all custom data key-value pairs') and resource ('an entity'), and elaborates on the data kinds covered (metadata, configuration settings, custom attributes). It does not explicitly differentiate itself from siblings like getCustomDataForEntityByKey or retrieveCustomDataForEntityAdvanced, though 'all ... key-value pairs' implies the contrast with key-specific lookup.

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

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

There is no explicit when-to-use guidance or naming of alternatives, despite many similarly scoped siblings (getCustomDataForEntityByKey, retrieveCustomDataForEntityAdvanced, getCustomEventForEntityByUuid). Usage is only implied by the phrase 'List all ... key-value pairs', which leaves an agent guessing which custom-data tool to pick among the overlapping set.

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

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

No annotations are provided, so the description carries the behavioral burden. The verb 'Retrieve' and the phrase 'without fetching all custom data' make the read-only, targeted nature clear. However, it does not disclose return shape, behavior when the key is missing, or any error conditions, so it stops short of being 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 two sentences with no filler. The first sentence states the primary action, and the second adds useful scope and efficiency context. 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 key-based lookup, the description supplies the essential selection logic and distinguishes it from bulk retrieval. The schema covers required parameters, though the lack of an output schema means return format and not-found behavior are left implied rather than 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?

Three of four parameters already have schema descriptions, including detailed guidance for session_id and context. The description reinforces that key selects the custom data value and tagOrId identifies the entity, but it adds little parameter-level detail beyond what the schema 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 description uses a specific verb and resource: 'Retrieve a specific custom data value by key for an entity.' It clearly differentiates from siblings like getCustomDataForEntity by emphasizing the single-key scope and 'without fetching all custom data.' An agent can understand exactly what this 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 provides a clear use case: efficiently access one metadata attribute, configuration value, or custom property without retrieving the full custom-data set. It does not explicitly name an alternative tool or state when not to use it, but the context strongly implies single-key lookup over bulk retrieval.

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

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

With no annotations provided, the description carries the full burden and does disclose what the response contains (title, description, timestamp, type, custom data). However, it says nothing about not-found behavior, error handling, or response format — adequate but thin for a single-item retrieval with no output schema.

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

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

A single, front-loaded sentence with zero filler. It states the action, the target, and the return contents efficiently — appropriately sized for what the tool does.

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 retrieval tool with 4 required parameters, no output schema, and no annotations, the description is on the lean side. It covers the retrieval target and return fields but omits not-found/error behavior and any guidance linking it to its list counterpart (listCustomEventsForEntity). Adequate, with 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 coverage is 75%; the uuid parameter has no schema description (only a uuid format), and the description only reinforces it via 'by its UUID' without adding format or format-context details. The mention of 'custom data' in the return fields modestly overlaps with tagOrId semantics. Adds marginal value but doesn't fully compensate for the undocumented uuid parameter.

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 (Retrieve) with a clear resource (custom event) and identifying key (UUID), and lists the returned fields. The word 'specific' helps distinguish it from the list-style siblings like listCustomEventsForEntity, though it doesn't name the sibling directly.

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

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

Usage is only implied by the name and phrasing 'by its UUID' — the agent can infer it should call this when it already has a UUID in hand. No explicit context distinguishes it from listCustomEventsForEntity or the getCustomDataForEntity family, and no when-not-to-use guidance is given.

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

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

No annotations are provided, so the description carries the burden. It does disclose two useful behavioral traits: the results are paginated and the data is time-series with optional date-range filtering. However, it does not explain how pagination behaves, the shape of each data point, sorting, or empty/error outcomes, leaving several behavioral aspects undisclosed.

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

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

The description is a single sentence with the core purpose front-loaded. It has minimal waste, though 'custom metric data points' and 'time-series data for a specific custom metric' are slightly redundant. Overall it is concise and readable.

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

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

For a complex 8-parameter tool with no output schema and no annotations, the description is too thin. It doesn't describe the structure of the returned time-series data, the relationship between customMetricKey and tagOrId, or how the required context and session_id parameters factor in. It also fails to distinguish itself from the many closely-related sibling tools, leaving significant 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 100%, so the baseline of 3 applies. The description adds general context about pagination and date-range filtering, but it doesn't illuminate specific parameters beyond what the schema already provides. The schema already documents page/pageSize defaults, tagOrId as entity identifier, and customMetricKey as the metric filter key.

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 ('Retrieve custom metric data points for an entity') and adds distinguishing characteristics: paginated time-series data for a specific custom metric with optional date-range filtering. It does not explicitly name any sibling tool, but the 'custom metric' framing helps separate it from generic getCustomDataForEntity and similar 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?

There is no guidance about when to use this tool versus alternatives such as getCustomDataForEntity, getCustomDataForEntityByKey, retrieveCustomDataForEntityAdvanced, or queryPointInTimeMetrics. The description never states exclusions or conditions, so an agent must infer the appropriate choice from name and schema alone.

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

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

With no annotations provided, the description carries the full burden. It communicates that the tool is a getter and reveals that the returned definition includes a JSON schema constraint for its descriptor. It does not cover potential error behavior, permissions, or any side effects, but for a simple read operation the main behavior is adequately 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 a single, front-loaded sentence with no filler. Every phrase adds meaning: the resource, the lookup key, and the notable output 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 simple getter with three required parameters, the description captures the core purpose and a key aspect of the return value. However, there is no output schema, no annotations, and no guidance on how to discover valid entity types or how this relates to sibling tools like listDefinitions. The description is sufficient but not thorough.

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 67%; the 'type' parameter is undocumented in the schema, and the description partially compensates by saying the tool retrieves a definition 'by type.' The session_id and context parameters are already thoroughly described in the schema, so the description adds little beyond clarifying the role of 'type.'

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: 'Get one entity type definition by type.' It also explains what the definition includes ('the JSON schema its descriptor must satisfy'), which clarifies the tool's output. It is clear enough to distinguish from listDefinitions, though it does not explicitly differentiate from every sibling.

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 the tool: when you need a single entity type definition identified by its type. However, it does not explicitly mention alternatives such as listDefinitions or getEntityDescriptor, nor does it state when not to use this tool. The usage context is clear but not fully guided.

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?

There are no annotations, and no output schema, so the description carries the full behavioral disclosure burden. It indicates the result includes method, path, and metadata, but it does not clarify whether the operation is read-only, what happens when no dependency exists, whether method/path act as filters or output fields, or any error/edge behavior.

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

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

Two concise sentences with no filler. The primary action and result content are front-loaded, and the second sentence adds use-case context. It is not bloated, though it could be more precise without adding 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?

The tool has six parameters, four required, no output schema, and no annotations. The description leaves key ambiguities: what callerTag/calleeTag mean concretely, whether method/path are filters or returned fields, and what the returned metadata looks like. This is not enough for an agent to reliably invoke the tool.

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

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

Schema description coverage is only 33%; the core parameters callerTag, calleeTag, path, and method have no schema descriptions. The tool description names method and path but does not clarify their roles or required format. CallerTag and calleeTag are only inferable from their names, not explained.

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 action (get) and resource (specific dependency details between two entities) and mentions the key facets of the result: method, path, and metadata. It is distinguishable from list-oriented siblings like listDependenciesForEntity, though it does not explicitly name an alternative.

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 the tool is 'useful for understanding the nature of the relationship, API contracts, and communication patterns,' which gives some context, but it never states when to prefer this tool over listDependenciesForEntity or getRelationshipTypeDetails, nor gives any exclusion criteria.

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

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It states the operation is a list (implying read-only) and mentions pagination, but does not disclose error behaviors, rate limits, or any side effects. It does not explicitly state that it is non-mutating, nor what happens if the entity is not found, which is a moderate gap for a tool with no annotation coverage.

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

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

The description is two sentences with no filler. The purpose is front-loaded in the first sentence, and the second sentence adds return details and pagination. Every word earns its place, making it highly concise and easy 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?

Given there is no output schema, the description reasonably explains what the response contains (timestamps, environments, SHAs, deployment types) and mentions pagination. However, it does not describe the exact structure of the paginated response (e.g., how to get the next page, whether a next-page token is provided), nor does it mention error conditions. For a read-only list tool, this is largely adequate, but the lack of pagination mechanics 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter-specific meaning beyond the schema; it only mentions the output fields, not the inputs. The parameters (tagOrId, pageSize, page, session_id, context) are already documented in the schema, so the description adds no additional value here.

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 'List' with the resource 'deployments' and the scope 'for a specific catalog entity'. It also lists the return fields (timestamps, environments, SHAs, deployment types) and pagination, which distinguishes it from sibling tools like searchDeploys (search across deployments) and listDeployEnvironments (environments only).

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

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

No guidance is provided on when to use this tool versus alternatives. With many sibling tools like searchDeploys, getEntityDetails, or listDeployEnvironments, the description gives no criteria for selection, leaving the agent to infer from the name and schema alone.

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

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

No annotations exist, so the description carries the burden. It discloses the default output format (JSON), the YAML switch, and what a descriptor contains, but it does not explicitly state side effects, access requirements, or error behavior. For a simple read operation the disclosed core behavior is adequate but not exhaustive.

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 sentences with no filler; the main action and resource are first, followed by format option and competitor distinction. Each sentence contributes unique 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?

Combined with the exhaustive session_id documentation in the schema, the description gives the caller enough to invoke correctly: resource, input requirements, output format, and the differentiating alternative. No output schema exists, but return format is stated; minor gaps like explicit read-only confirmation prevent a 5.

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

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

All four parameters are already fully described in the schema (100% coverage), so the baseline applies. The description adds only the default-JSON detail and reinforces the yaml=true behavior, which is mostly redundant with 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 ('Retrieve') and identifies the resource: an entity's Cortex descriptor, explicitly defined as the x-cortex-* configuration. It also contrasts itself with getOpenApiDocForEntity, making the purpose unmistakable among the sibling 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?

It gives one concrete routing rule: use this for descriptors, not getOpenApiDocForEntity, which returns the service API. It doesn't enumerate all alternatives (e.g., listEntityDescriptors), but the stated context is enough to distinguish from the closest sibling.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns a broad set of information including metadata, ownership, hierarchies, and relationships, which sets expectations for output. However, it doesn't discuss potential performance implications of requesting deep hierarchies, or whether includeOwners defaulting to true might cause unexpected overhead. It's not misleading but leaves room for more 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 a single sentence that is clear and front-loaded with the main purpose. It efficiently conveys the scope of the data returned. It could arguably be more concise, but it is not verbose and every phrase contributes to the 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?

Given the tool has 6 parameters, 3 required, and no output schema or annotations, the description should be more comprehensive. It covers what information is retrieved, but it doesn't explain how the parameters affect the response (e.g., includeOwners default, hierarchyDepth behavior). Some parameters like session_id are documented in the schema, but the overall orchestration context is missing. It's borderline adequate for a primary getter tool, but a bit more detail on parameter effects would be better.

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 100%, so the baseline is 3. The description does not add much parameter-specific guidance beyond the schema; it doesn't elaborate on what 'full' depth really means or how to use includeHierarchyFields effectively. The session_id parameter is well-explained in the schema, but the tool description does not supplement it. So, it's adequate but doesn't enhance clarity 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 clear verb ('Retrieve comprehensive details') and resource ('specific entity'), and specifies the kinds of information included (metadata, ownership, hierarchies, relationships). It differentiates itself as the 'primary method' for complete entity details, though it doesn't explicitly distinguish from siblings like getDefinition or getEntityDescriptor, but the scope is clear.

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

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

The description implies that this is the go-to tool for complete entity details, but it doesn't explicitly state when to use it versus alternative tools or when not to use it. It mentions it's the 'primary method' but provides no exclusions or alternatives. The agent would need to infer that more specific tools like getTeamDetails or getScorecard exist for narrower use cases.

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

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

With no annotations, the description itself carries the transparency burden. It clearly signals a non-mutating read operation via 'Retrieve' and discloses the categories of information returned. It does not discuss errors or response format, but for a simple read tool this is acceptable.

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

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

Two sentences, front-loaded with the action and resource, no filler or duplication. The second sentence provides practical context without padding.

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 unannotated tool with no output schema, the description should provide enough to call it correctly. It lists returned content but omits the meaning of the required cid and any guidance connecting this tool to listInitiatives, so an agent may fail at the first parameter.

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 required cid parameter has no schema description and the tool description never links it to the initiative identifier, so an agent cannot be certain what to pass. session_id and context are well documented in the schema, but the description adds no meaning for any parameter beyond the already-available schema text.

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 object ('Retrieve detailed information about a specific initiative') and enumerates the data it returns (goals, timeline, affected entities, scorecard targets, current progress). This separates it from siblings like listInitiatives (list vs. get one) and getScorecard.

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

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

It offers contextual guidance ('Essential for understanding initiative scope and tracking achievement of objectives') but never explicitly states when to choose this over listInitiatives or other sibling tools, nor any cases where it should not 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 annotation readOnlyHint=true already covers the safety profile. The description adds the purpose but not additional behavioral traits like return format or side effects. It doesn't contradict annotations, but it doesn't go beyond what the annotation already conveys. A 3 is appropriate given the annotation coverage.

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

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

The description is a single, front-loaded sentence with no filler. It states the action and the condition for use in an efficient manner.

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 main purpose and usage guidance. The parameters are fully documented in the schema, and an output schema exists. The only minor gap is that it doesn't hint at what kind of tools might be returned, but that is likely handled by the output schema. Overall, it's complete for a discovery tool.

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

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

Schema description coverage is 100%, and both 'context' and 'session_id' have detailed descriptions. The tool description adds no extra meaning about the parameters, so the baseline of 3 applies.

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

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

The description clearly states a specific action ('Check for additional tools') and the resource ('additional tools'). It also provides a clear condition for use, which distinguishes it from the many entity-specific get/list tools in the sibling list. No other sibling appears to be a meta-tool for discovery, so it stands 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?

The description explicitly says when to use it: 'whenever your task might benefit from specialized capabilities - even if existing tools could work as a fallback.' This is clear context, though it doesn't mention alternatives or when not to use it. Since no other tool serves this discovery role, the guidance is sufficient.

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

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

With no annotations provided, the description carries the full burden. It discloses the response structure (single array with 'itemType' field), the combination behavior, and gives examples. It also implicitly indicates it's a read operation. However, it does not mention error handling, rate limits, or what happens if a sub-request fails. The example 1 omits required fields (includeArchived, ownershipSource, page, pageSize) for myEntitiesRequest, which could mislead an agent into thinking those are optional, though the schema marks them required. This is a minor transparency gap.

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

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

The description is long but well-structured with headers, bullet lists, and examples. It front-loads the purpose, then explains request/response structures, and ends with examples. Each section earns its place, though it could be tightened. The use of all-caps headers and clear formatting aids readability.

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

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

With no output schema, the description must explain return values, which it does thoroughly (itemType values and meaning). It covers all resource types and gives examples. However, it does not explicitly mention pagination behavior across the combined response or how page/pageSize apply when multiple sub-requests are made. Also, the incomplete examples could lead to failed calls. Overall, it is quite complete for the tool's complexity, but a few gaps remain.

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 100%, so the schema already documents each parameter. The description adds value by explaining how the sub-request objects combine and providing usage examples. However, the examples are incomplete per the schema (e.g., example 1 omits required fields for myEntitiesRequest), which could cause incorrect calls. The description also labels the sub-request objects as 'optional fields' (meaning you can omit a sub-request), which is correct, but the internal required fields are not clarified. This does not fully compensate for the potential confusion.

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 verb ('retrieving') and resource ('current user's owned resources and work items across the Cortex workspace'). It distinguishes itself from sibling tools by aggregating multiple resource types in a single call, which is a unique capability not offered by the per-resource siblings like listAllEntities or getTeamDetails.

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 how to use the tool flexibly: 'Set one or more fields to fetch multiple resource types in a single call.' It provides examples of different combinations and even shows how to fetch all work items. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions (e.g., 'use this instead of getTeamDetails when you need teams plus PRs'). The context is clear enough for an agent to infer, but explicit guidance is missing.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It explains what the tool does but does not mention side effects, permissions, error handling, or the return format beyond the implied OpenAPI document. For a read operation, it lacks detail on what happens if no spec is found or if multiple specs exist (though the name parameter partially covers that).

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

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

Two sentences with zero filler. The core purpose is stated first, and the differentiating sibling is mentioned second. Every sentence earns its place, and the structure is front-loaded and 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?

The description is adequate for a simple retrieval tool, but lacks some contextual details. There is no output schema, so the agent must infer that the result is an OpenAPI document, which is standard but not explicitly stated. The description does not cover edge cases like multiple specs or missing specs, though the name parameter hints at that. Given the simplicity and the clear sibling contrast, it is functional but not rich.

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 100%, so all parameters are well-documented in the schema itself. The tool description adds no additional parameter meaning beyond the schema, meeting the baseline for high coverage. The description does not clarify any parameter behavior beyond what the schema already 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 description clearly states the specific action ('Get the OpenAPI document registered against an entity') and differentiates it from a sibling tool by naming getEntityDescriptor and the distinction between the exposed API and the Cortex descriptor. This is specific and unambiguous.

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

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

The description explicitly contrasts this tool with getEntityDescriptor, providing a clear when-to-use cue. However, it does not explicitly state when not to use this tool or mention any alternative scenarios beyond that single sibling, leaving some room for inference.

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

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

No annotations are provided, so the description bears the full burden of disclosing behavior. It states the tool 'Gets' details, implying a read-only operation, but does not explicitly confirm no side effects, mention error handling (e.g., behavior when the type doesn't exist), or note any permissions or rate limits. It adds little beyond what the name implies, and lacks the transparency expected for a tool without 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 a single, focused sentence that front-loads the purpose and enumerates key output contents. It contains no redundant phrases and is appropriately sized for a getter tool. Every word contributes to understanding the tool's role.

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 lists the core content areas of the response (configuration, rules, filters, inheritance) and provides a rationale for use. While it does not describe the exact return format or error cases, the tool is a simple getter with no output schema, and the description adequately conveys what the agent will learn. It is nearly complete for its simplicity, though it could mention behavior on missing types or prerequisites.

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 67% (context and session_id have detailed descriptions; relationshipTypeTag does not). The tool description mentions 'specific relationship type' but does not elaborate on relationshipTypeTag's format or constraints, nor does it clarify how it interacts with other parameters. Since coverage is not high and the description adds no parameter-specific value beyond the schema, it does not compensate for the undocumented parameter.

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 function: retrieving complete details of a specific relationship type, listing included aspects (configuration, rules, filters, inheritance). It distinguishes from siblings like listRelationshipTypes (which lists all types) and more focused tools like listEntitySourcesForRelationshipType. The verb 'Get' and resource 'relationship type details' are specific and unambiguous.

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

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

The description provides clear context for when to use the tool ('Essential for understanding how entities can be connected'), implying it's for exploring a specific relationship type's full configuration. However, it does not explicitly compare against alternatives like listEntitySourcesForRelationshipType or listEntityDestinationsForRelationshipType, nor state when not to use it. It offers context but no exclusions, so it earns a 4.

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?

There are no annotations provided, so the description carries the burden of behavioral disclosure. It does disclose the main output categories (configuration, rules, levels, weights, exemptions, evaluation criteria), but it does not mention potential side effects, permission requirements, rate limits, or error cases. The verb 'Get' implies a read operation, but the description could provide more 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 only two sentences long, front-loads the core purpose and key output components, and ends with a concise value statement. Every sentence earns its place, and there is no redundant or filler 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 simple get-by-tag tool, the description is largely complete: it lists the major categories of returned data, the schema covers all parameters, and no output schema exists, so the enumerations serve that role. It could be slightly more complete by explicitly distinguishing itself from listScorecards or noting whether the returned configuration is versioned, but 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?

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly, including the tag example, session_id semantics, and context explanation. The description adds no additional parameter-level meaning beyond referring to the scorecard tag as the target of the operation.

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 gets complete details of a scorecard and enumerates the specific components returned: configuration, rules, levels, weights, exemption settings, and evaluation criteria. This makes it distinct from sibling tools like listScorecards or listScorecardScores, which cover listing or scoring rather than full scorecard details.

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 conveys when this tool is appropriate by calling it essential for understanding how services are evaluated and what standards they must meet. However, it does not explicitly mention alternatives or state when not to use this tool, leaving some routing 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It accurately states the tool shows rules and helps prioritize improvements, which is a read-only operation by nature. However, it does not explicitly confirm read-only behavior, mention any prerequisites (e.g., that the entity must have a scorecard), or disclose any side effects. No contradiction with annotations since none exist, but the description could add more context about what the returned next steps look like or any limitations.

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

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

The description is two sentences, front-loaded with the primary purpose and outcome. Every clause adds value: it specifies the action (get next steps), the context (improve scorecard performance), and the output detail (rules to reach next maturity level). No redundancy or filler. It is appropriately sized and structured for quick scanning.

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 4 parameters, no output schema, and no annotations. The description explains the tool's purpose and what it returns conceptually (rules to satisfy), which is sufficient for an agent to understand when to call it. However, it does not explicitly mention that a scorecard tag and entity tag are required (though implied by the schema), nor does it describe the exact structure of the next steps output. Given the tool's moderate complexity, the description is mostly complete but could add a note about prerequisites or return format.

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 100%, meaning all parameters are documented in the schema itself. The description does not add any parameter-level detail beyond what the schema provides. Baseline of 3 applies because the schema does the heavy lifting, and the description does not need to compensate for any undocumented parameters.

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

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

The description clearly states the tool retrieves actionable next steps for an entity to improve scorecard performance, specifically listing which rules must be satisfied to reach the next maturity level. This distinguishes it from siblings like getScorecard (which returns the scorecard itself) and listScorecardScoresForEntity (which lists scores). The verb 'Get' plus the resource 'next steps for an entity' makes the purpose unambiguous.

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

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

The description implies usage when an agent needs to guide improvement toward compliance goals, which is distinct from simply viewing scores or details. It does not explicitly name alternatives or provide when-not-to-use guidance, but the context is clear enough that an agent can infer when to call this tool versus others. Lacks explicit exclusion statements, but the purpose is clear.

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

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

No annotations are provided, so the description carries the behavioral burden. It signals a read-only operation ('Retrieve') and describes expected output content, which is helpful. However, it does not mention error behavior, permission requirements, or any special constraints, so transparency is only moderate.

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 a single, front-loaded sentence with no filler. It conveys the action, target, lookup key, and headline return fields in a compact, readable form.

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

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

For a simple read tool, the description plus the fully documented required parameters are enough for an agent to know when to call it and what to expect back. It lacks an output schema and detailed error semantics, but the high-level return content is explicitly listed, leaving only minor 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 100%, so the structured parameter definitions already explain tagOrId, session_id, and context. The tool description adds little beyond the schema, and its 'ID' wording is slightly looser than the schema's 'CID', but it does not introduce significant ambiguity.

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 ('Retrieve'), a specific resource ('a specific team'), and the lookup mechanism ('by its tag or ID'). It also enumerates key returned content (members, Slack channels, metadata, identity provider group backing), which clearly distinguishes it from generic siblings like getEntityDetails or relationship-focused tools like getTeamHierarchyRelationships.

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 usage context is clear: call this when you need detailed information about one known team. It does not explicitly name alternatives or when-not-to-use conditions, so it falls short of a 5, but the purpose statement is sufficient to guide correct selection.

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

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

No annotations are present, so the description carries the full burden. It discloses that the tool returns parent-child team relationships and that results name teams, but it does not mention pagination, ordering, result shape, or whether all hierarchy levels are included. Adequate for a simple list operation, but not rich.

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

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

Two sentences with no filler. The core purpose is front-loaded, and the second sentence adds a useful cross-reference to getTeamDetails 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?

For a low-complexity tool with fully documented parameters and no output schema, the description states what is returned and how to use the result. It lacks explicit mention of pagination or result limits, but nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, and the session_id parameter is thoroughly documented in the schema. The description adds no parameter-level meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb ('List'), a specific resource ('every parent-child relationship between teams'), and a clear scope ('team hierarchy'). This distinguishes it from sibling tools like getTeamDetails, which reads a single team, and generic relationship listers.

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 only usage guidance is the pointer to getTeamDetails for reading a single team named in the result. It does not explicitly state when to prefer this tool over listEntityRelationships or other relationship-oriented siblings, nor does it mention 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions what the returned workflow includes, but it does not state whether the operation is read-only, how errors or unrecognized IDs are handled, or any authorization/rate-limit implications. The name implies a getter, but the description adds little beyond that.

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

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

The description is two sentences with no filler. The primary behavior and selection info are front-loaded, and the pointer to listWorkflows is a useful, targeted addition that 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?

This is a simple three-parameter getter with fully documented schema parameters, so the description does not need to repeat parameter semantics. It explains how to locate a tag via listWorkflows and what the workflow result contains, which is adequate given the absence of an output schema. It could mention error behavior or uniqueness of tags, but those are relatively minor 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 100%, so the baseline is 3 under the rubric. The tool description does not add meaning beyond the schema: 'by tag or CID' restates tagOrId's schema description, and session_id/context are already fully documented in the schema. No additional parameter nuance is provided.

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 ('Get'), the resource ('one workflow'), and the selection criteria ('by tag or CID'). It also previews what the call returns ('actions it runs and inputs it takes'), and naming listWorkflows helps differentiate it from the sibling list tool.

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

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

The description explicitly directs users to listWorkflows when they need to find the tag, which gives useful routing for when to use the alternative. It does not spell out exclusions or broader when-not-to-use scenarios, but for a straightforward retrieval tool the guidance is sufficient.

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

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

No annotations are provided, so the description carries the full burden: it discloses that the response includes per-action outcomes, and that run context is conditionally omitted unless includeContext=true. It does not cover permissions/auth or rate limits, which leaves a small gap, but the conditional output behavior and polling guidance are meaningful disclosures.

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, front-loaded sentences with zero filler: the core action first, then the id source, then the polling rule, then the conditional output note. 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?

With no output schema, the description usefully characterizes the return ('outcome of each action', conditional context), and adds polling and id-sourcing guidance. It is close to complete for a get tool, though it stops short of describing the status field set or error behavior.

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 100%, so all five parameters are already documented, including includeContext's default behavior and runId's source. The description only reiterates the includeContext condition already in the schema, adding no syntax or format detail beyond it, so baseline 3 applies.

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

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

States a specific verb+resource ('Get one workflow run by its id') and what it returns ('including the outcome of each action in it'), and explicitly names the sibling listWorkflowRuns as the source for the id, so it is distinguishable from listWorkflowRuns 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?

Gives explicit routing ('Use listWorkflowRuns to find the run id') and a concrete polling condition ('Poll while the status is NOT_INITIATED or IN_PROGRESS'), telling the agent both when to call it and how to use the result over time. This is unusually actionable for a get tool.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the output content (replica and pod state) and an important edge behavior ('Returns nothing when the tenant has no Kubernetes integration'). It does not explicitly state read-only semantics or pagination behavior, but 'List' implies a read operation and the schema documents paging parameters. This is solid coverage for a list-style 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?

Two sentences with no redundancy. The main purpose is front-loaded, examples and output details follow, and the empty-result edge case is a separate useful sentence. Every word contributes.

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 absence of an output schema and annotations, the description covers the core what, includes output specifics, and notes the no-integration case. It does not describe pagination behavior or result ordering, but those are already inferable from the schema's page/pageSize defaults. For a straightforward read/list tool, this is sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter-specific meaning beyond the schema: tagOrId, page, pageSize, session_id, and context are all already described in the input schema. The phrase 'mapped to an entity' aligns with tagOrId, but adds no new detail.

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') and resource ('Kubernetes resources mapped to an entity') and provides concrete examples ('deployments, statefulsets, cronjobs and the like') along with the included state ('current replica and pod state'). This clearly distinguishes it from sibling tools like AWSGetAwsResources or getCustomDataForEntity, so an agent can identify what this tool does without opening the schema.

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

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

The description implies a clear use case: when an entity's Kubernetes resources and their replica/pod state are needed. It does not explicitly name alternatives or state when not to use it, but the resource-specific language makes the context obvious enough for an agent to select it over siblings such as AWSGetAwsResources. The absence of exclusions keeps it from a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It conveys a read-only list operation with optional filters, pagination, and historical scope, which is adequate for the basic call, but it does not mention deprecated fields like 'timestamp' or any pagination caveats beyond what the schema already states.

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 and is only two sentences, but it redundantly repeats filtering information: 'filtering by type and time range' is restated as 'filtering by event type, start time, and end time'. This repetition costs conciseness.

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 9 parameters, no output schema, and no annotations, the description gives only basic list-and-filter semantics. It does not describe the return shape, pagination behavior beyond the phrase 'supports pagination', or the deprecated timestamp parameter, leaving several operational gaps for the 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?

Schema description coverage is high (89%), so the schema already documents most parameters. The description adds minor value by clarifying that 'type' means event type and that startTime/endTime form a time range, but it does not compensate for the undocumented 'type' values or describe the deprecated 'timestamp' parameter.

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 ('List') and the resource ('custom events for an entity'), and mentions filtering by type and time range. It is distinct from sibling tools like 'getCustomEventForEntityByUuid' by signaling plural listing rather than single-event retrieval, though it does not explicitly call out that distinction.

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

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

No explicit guidance explains when to use this tool versus related siblings such as 'getCustomEventForEntityByUuid' or 'getCustomDataForEntity'. The phrase 'retrieve historical event data' implies a use case, but there are no alternatives, exclusions, or selection criteria.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose what the operation returns (entity type definitions with their descriptor JSON schemas) and implies a read-only listing. But it does not clarify workspace scoping semantics, pagination behavior, or what happens with the built-in types by default. For a simple list tool this is adequate but not rich, warranting a 3.

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

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

The description is two tight sentences with zero waste. The core purpose is front-loaded in the first sentence, and the usage directive in the second earns its place. No redundancy, no filler, and it is appropriately brief for a simple list tool.

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

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

With no output schema and no annotations, the description compensates reasonably: it states the operation, the return content (types with descriptor JSON schemas), and gives the sequencing guidance to read it before composing custom fields. All parameters are fully documented in the schema. The only gap is not clarifying the relationship to the sibling listing tools, but for a straightforward list operation this is reasonably complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-level detail beyond what the schema already documents; it does not elaborate on any of the five parameters (page, pageSize, includeBuiltIn, session_id, context). Since the schema fully covers the parameters, the description neither helps nor hurts, keeping it at baseline 3.

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

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

The description uses a specific verb ('List') and a clear resource ('entity type definitions in this workspace') and adds what each entry contains ('the JSON schema its descriptor must satisfy'). This is clear and meaningful, and conceptually separates it from listEntityDescriptors (descriptors) and getDefinition (single entity). However, it never names any sibling or explicitly differentiates itself, so it stays at a 4 rather than 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 description gives a genuine usage context: 'Read this before interpreting or composing an entity's custom fields.' This tells the agent when to invoke it but does not mention alternatives, when not to use it, or how it differs from similar tools like listEntityDescriptors or getDefinition. There is context but no exclusions, landing it between a 3 and a 4; the thinness of the single directive pulls it to 3.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses that the tool lists distinct names scoped to the tenant, which is useful, but it does not describe return format, pagination, or any other behavioral traits. It is adequate but minimal.

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

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

The description is two sentences with no filler. The core purpose is front-loaded, and the usage guidance is placed immediately after, making it easy for an agent to parse and act on.

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

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

The tool is simple, has no output schema, and the description clearly states what it returns (deploy environment names) and when to use it. It could mention the exact output type or empty-list behavior, but for this low-complexity tool the description is largely sufficient.

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

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

Schema description coverage is 100%, so both session_id and context are already fully documented in the schema. The description adds no parameter-specific meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states a specific verb ('List') and resource ('all distinct deploy environment names for this tenant'). It also distinguishes itself by explicitly connecting to getDeploysForEntity, making its purpose unambiguous even among many sibling list 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 gives explicit usage context: 'Use before getDeploysForEntity to pass the correct environment values.' This tells the agent when to invoke it, though it does not enumerate exclusions or compare against other list 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?

With no annotations provided, the description carries the full burden. It discloses return format (JSON default, YAML optional), pagination, and filtering/archived behavior. However, it omits details like authentication requirements, error handling, or what happens on empty results, leaving some ambiguity for an agent.

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

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

A single, front-loaded sentence delivers the core purpose ('List many descriptors with pagination') followed by precise details. Every clause earns its place, and there is zero redundancy or 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 list tool with 7 parameters and no output schema, the description covers the essential usage: pagination, filters, formats, and archived entities. The session_id parameter is left to the schema, which is acceptable since it is fully documented there. Overall, an agent can call this tool correctly based on the description and schema together.

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 100%, so all parameters are already documented. The description adds minimal new semantic value—it mentions 'filter with types' and 'includeArchived' but essentially paraphrases the schema. It does not reveal hidden relationships or constraints, so a baseline 3 is appropriate.

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 ('List'), a precise resource ('Cortex descriptors of many entities'), and distinguishes it from the singular getEntityDescriptor sibling. It also mentions pagination, formats, and filters, making the tool's scope 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?

The description gives clear usage context: it lists descriptors in bulk with pagination, filters by types, and can include archived entities. While it does not explicitly name alternatives like getEntityDescriptor, the emphasis on 'many entities' and pagination strongly implies when to use this over a single-entity tool.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'list', implying read-only, but does not state safety, side effects, pagination, or any limitations. The depth behavior is mentioned in the schema, not the description, so the description itself adds minimal 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 two sentences with no fluff, front-loading the core purpose and immediately directing the agent to a prerequisite tool. Every word 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 6 parameters and no output schema, this description is minimal. It does not explain what 'destinations' means in this context, how the depth parameter affects results, or what the output looks like. It points to listRelationshipTypes for the tag but leaves other operational details to the schema. An agent may struggle to use it correctly without additional context.

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 83% (5 of 6 parameters described), which is high. The description adds no parameter-specific details beyond what the schema already provides; it only references relationshipTypeTag indirectly. Per the rubric, baseline 3 is appropriate since the schema covers most 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 clearly states the action ('List all destinations') and the resource ('for a certain relationship type and entity'). It distinguishes itself from siblings like listEntitySourcesForRelationshipType by focusing on 'destinations' rather than 'sources', and from listEntityRelationships by being specific to a relationship type.

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 a key prerequisite by telling the agent to use listRelationshipTypes to find the relationshipTypeTag. However, it does not explicitly state when to use this tool versus alternatives (e.g., when to choose destinations over sources) or when not to use it. The guidance is implied rather than explicit.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It mentions pagination and source-destination pairs, which is useful, but it does not state whether the operation is read-only, whether special permissions are required, how results are ordered, what happens for nonexistent relationship types, or any potential side effects. For a tool with no annotation coverage, this is insufficient 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 a single sentence that is efficient and front-loaded with the core action and scope. There is no filler or redundancy; every word contributes to understanding the tool's 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?

Given the tool has five required parameters, no annotations, and no output schema, the description is sparse. It fails to explain the crucial relationshipTypeTag parameter (left undescribed in the schema), does not mention output format or result structure, and omits operational details like authentication or error handling. A single sentence is not enough to adequately cover the operational context 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?

Schema description coverage is 80% (four of five parameters have descriptions). The description adds minimal semantic value: it mentions 'specific relationship type' which hints at relationshipTypeTag, but does not clarify its meaning or format beyond the schema (which has no description for it). The other parameters (page, pageSize, session_id, context) are already well described in the schema, so the description adds little beyond baseline.

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 ('List'), resource ('entity relationships'), and scope ('across the entire organization' for a 'specific relationship type'). It clearly conveys the action and what it operates on. However, it does not differentiate from sibling tools like listEntitySourcesForRelationshipType or listEntityDestinationsForRelationshipType, which also deal with relationships but from a directional perspective, so it lacks explicit sibling differentiation.

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

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

The description implies usage for understanding the complete relationship graph and finding all connections of a particular type, which gives context. But it does not mention when to avoid this tool or explicitly compare with alternatives (e.g., listEntitySourcesForRelationshipType for one-directional queries, or getRelationshipTypeDetails for metadata). No exclusions or alternative routing are provided.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, yet it reveals nothing beyond what the tool name already implies. It does not mention traversal semantics for depth, what a 'source' consists of, how results are shaped, or any side effects. The prerequisite pointer is operational guidance, not behavioral 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?

Two sentences with the core purpose front-loaded and zero waste. The only minor flaw is the filler qualifier 'certain,' but every sentence earns its place, and the prerequisite guidance is placed exactly where it is needed.

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 schema is rich and covers most parameters, but with no output schema and no annotations, the description leaves important gaps: it never defines what 'sources' are, what the return value looks like, or how this tool differs from the similar listEntityDestinationsForRelationshipType sibling. Adequate for basic invocation, but incomplete for confident selection among closely related tools.

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

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

Schema coverage is 83%, so five of six parameters are already documented and the baseline is 3. The description adds value for the one undocumented parameter, relationshipTypeTag, by directing the agent to listRelationshipTypes to discover valid values — meaningful guidance the schema alone does not provide.

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 ('List') and a specific resource ('sources for a certain relationship type and entity'), making the core function clear. However, it does not explicitly differentiate this from the closely named sibling listEntityDestinationsForRelationshipType, so it stops short of full sibling distinction.

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

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

Provides one concrete usage pointer: use listRelationshipTypes to find the relevant relationshipTypeTag, which is genuinely actionable since that parameter is undocumented in the schema. It does not, however, state when to prefer this over listEntityRelationships or listEntityDestinationsForRelationshipType, or give any exclusion criteria.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It explains the semantics of groups but does not describe return format, pagination behavior beyond the schema-derived page/pageSize hints, or what happens when an entity has no groups or is invalid. The read-only nature is implied but not stated.

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 tight sentences with no filler. The purpose is front-loaded, and the single clarifying detail — what groups are — earns its place by disambiguating the catalog concept. Nothing extraneous is included.

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 list tool with no output schema and no annotations, the description is lean. Pagination is only implied through the parameter descriptions, and return-value structure is left unspecified. It is adequate for a simple read operation but could explain result format and the pagination contract more explicitly.

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 100% — all five parameters are individually described, so the schema carries the heavy lifting. The description adds marginal value by clarifying what counts as an 'entity' (via tagOrId context) and what 'groups' means, but it does not enrich parameter syntax or format beyond the schema.

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

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

The description states a specific verb ('List') and resource ('the groups one entity belongs to'), and clarifies what groups are (free-form x-cortex-groups tags). It reads distinctly from sibling tools, none of which obviously list groups. It lacks an explicit statement of what it is not, but the purpose is unambiguous.

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

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

The description defines groups as x-cortex-groups tags, offering useful context that implies a catalog-organization use case, but it gives no explicit guidance on when to choose this tool over alternatives or any exclusion criteria. Among siblings there is no obvious substitute tool, so the omission is minor but still leaves usage 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?

With no annotations, the description carries the burden and does establish a read-style list operation plus filter behavior. It does not disclose default exclusion of drafts/expired, pagination behavior, or any result-shape caveats, though the schema covers some defaults. This is adequate but not rich.

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 front-loaded sentences with the core listing behavior first and the business purpose second. The phrase 'understand organizational priorities and track progress' adds context but is slightly generic, so not a perfect 5.

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

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

There is no output schema, so the description should compensate by revealing return shape; it only says 'current status' and doesn't mention pagination results or default active-only behavior. The schema covers parameters, but the lack of richer outcome details leaves a gap.

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

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

Schema coverage is 100%, so the parameters are already documented in detail. The description only restates the includeDrafts/includeExpired filter idea and adds no new semantics for page, pageSize, session_id, or 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 clearly states the operation ('List all initiatives') and its scope ('in the organization'), and adds the optional draft/expired filters plus the initiative status/type context. It does not explicitly differentiate from sibling getInitiative, so it stops short of a 5.

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

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

It gives a clear intended use case: viewing active improvement programs and strategic projects to understand priorities and track progress, and it explains optional filters. However, it never mentions when to prefer a sibling such as getInitiative, so it lacks explicit exclusions or 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?

With no annotations, the description must carry the behavioral burden and does substantial work: it warns that lastValidatedAt is a check timestamp, not data freshness, and that message is null unless the caller holds Manage Integrations permission — a real auth-dependent field behavior. It stops short of stating pagination or the full set of status values, and read-only nature is only implied by 'List'.

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 tight sentences, front-loaded with the core action before the usage hint and the two disambiguating caveats. No filler or repetition of the title.

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 listing tool with no output schema, the description supplies the semantics of the key returned fields and a permission caveat, which is most of what an agent needs. Minor gaps remain around result size, pagination, and the complete status vocabulary.

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 100% and both parameters (session_id, context) are fully documented in the schema, so the baseline is 3. The description adds no parameter-level detail beyond what the schema already 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?

States a specific verb and resource — 'List every integration installed in this workspace' — plus the payload it returns (most recent connection check result). No sibling covers integration status, so it is unambiguously distinguishable from the catalog, entity, and workflow 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 names the use case: finding integrations with failing credentials (INVALID) or stale checks (UNKNOWN). That is clear triggering context, though it offers no exclusions or named alternative when a different tool would be better suited.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses performance characteristics (unfiltered full view is very large), caching behavior, and 400/403 error responses. It also explains what metadata full view returns, though it does not explicitly state read-only semantics or auth requirements; 'List' implies read-only.

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 well-structured with clear headings and front-loaded purpose and usage. The filter-operator and ordering sections are dense but relevant to constructing valid point-in-time queries, so they earn their place. There is no filler or tautological 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?

Despite lacking an output schema and annotations, the description provides enough to call the tool correctly: workflow, parameter semantics, caching, error handling, and query metadata. A minor gap is that the exact shape of basic/full response envelopes is not spelled out, but the mention of 'minimal info' and key filtering makes it inferable.

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 descriptions cover only session_id and context, leaving key and view undocumented there. The description fills this gap by defining allowed view values, explaining that key supports multiple values and comma-separated lists, and describing the query metadata returned in full view. It does not restate context/session_id, but those are already well documented 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?

Description opens with 'List all available engineering metric definitions,' a specific verb and resource. It also frames the tool as the prerequisite step before queryPointInTimeMetrics, distinguishing it from generic listing siblings like listDefinitions.

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?

Includes an explicit USAGE section: call before querying metrics, once with view='basic' to discover metrics, then with view='full' and a key before querying. It also gives a clear anti-pattern: do not call view='full' without a key filter, plus caching 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It correctly implies a read-only listing operation and discloses pagination behavior, but it does not explicitly state that no entities are modified, nor describe result size limits, ordering, or what a returned configuration contains beyond a general 'understand what kinds...' hint. Adequate but thin for a tool with zero annotation coverage.

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

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

Two sentences with the core action front-loaded. The first sentence is maximally direct; the second adds value by clarifying the purpose of viewing these configurations. No filler or redundancy, though the second sentence does restate the 'relationship type' concept once more—minor overlap, not noise.

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 paginated list tool with no output schema and no annotations, the description conveys the essential scope, the return domain (relationship-type configurations), and pagination. It does not spell out the exact result shape, but the absence of an output schema is partially mitigated by the domain clarification. The four required params are handled by the schema's thorough 100% documentation.

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 100%, so baseline is 3. The description adds no parameter-level meaning beyond the schema: pagination is already fully documented in page and pageSize, and session_id/context are thoroughly covered in the schema. The description's 'with pagination' phrase merely echoes the schema rather than adding new semantic value.

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

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

States a specific verb and resource: 'List all available relationship types with pagination.' The scope ('all available') is explicit, and the second sentence clarifies the resource domain (relationship configurations between services, resources, domains, teams). This clearly distinguishes it from siblings like listEntityRelationships (relationships for an entity) and getRelationshipTypeDetails (a single type's detail).

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 implied use case: 'View relationship type configurations to understand what kinds of relationships can be created.' However, it does not explicitly route the agent away from alternatives such as getRelationshipTypeDetails or the listEntitySources/DestinationsForRelationshipType siblings, nor state when NOT to use this tool. Usage context is present but no exclusions or explicit comparisons.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: default sort order, the fields returned, and—most valuably—authorization-scoped results (privileged callers see all exemptions, others see only their own requests). It omits pagination/response-shape behavior, but the schema covers page/pageSize.

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 tight clauses: what it lists, how to filter it, and who sees what. The core purpose is front-loaded with no filler, though the middle filter-enumeration clause is a dense run-on.

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 11-parameter read-only listing tool with no output schema or annotations, the description covers output ordering, fields, filtering, the parameter dependency, and access scoping. It leaves pagination semantics to the schema but is otherwise sufficient to call 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 coverage is 100%, so each parameter is already documented in the schema; the description largely paraphrases those filters. It does reinforce the ruleIdentifier→scorecardTag coupling, but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("List Scorecard rule exemptions") and immediately adds the ordering ("newest first") and the returned fields (status, requester, approver, expiry). No sibling tool lists exemptions, so the resource is unambiguous among the provided 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 enumerates the filter axes (Scorecard tag, entity tag, rule identifier, status, requester/approver email, active-only) and states the dependency "a rule identifier needs a Scorecard tag", which is actionable usage context. It stops short of any explicit when-not or alternative-tool 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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It mentions optional filtering and lists filter dimensions (groups, entities, teams), and states the tool returns 'scorecard configurations.' However, it does not mention pagination behavior, that results are paginated via page/pageSize, or how showDrafts affects results. For a list operation without annotations, this is a moderate disclosure but leaves gaps.

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

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

The description is three sentences and front-loads the core purpose ('List all scorecards in the organization'). It is efficient, though the second sentence about 'viewing configurations' is slightly redundant with the purpose but adds context on why it might be used. No filler or repetition of the tool name.

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

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

With 8 parameters and no output schema or annotations, the description covers the main functionality (listing and filtering) but omits details like pagination, session_id handling (though the schema covers it), and the effect of showDrafts. The tool is moderately complex, and while the schema fills in most gaps, the description does not fully explain the complete behavior expected when calling the tool.

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

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

Schema description coverage is 88%, so the input schema already documents most parameters. The description mentions filtering by groups, entities, and teams, which aligns with the schema but adds little beyond it. It does not explain page/pageSize, session_id, context, or showDrafts beyond what the schema already states. Baseline of 3 is appropriate given the high schema 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 clearly states the tool lists all scorecards in the organization, with optional filtering. It names the resource ('scorecards') and the verb ('list'), and distinguishes itself from siblings like getScorecard (which retrieves a single scorecard) and listScorecardScores (which lists scores). The mention of 'view scorecard configurations' reinforces the specific use case.

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 usage by saying 'List all scorecards in the organization' and mentions filtering, but does not explicitly state when to use this tool versus alternatives like listScorecardScores or getScorecard. It lacks explicit 'when not to use' guidance or comparisons to sibling tools. The purpose is implied, but no exclusions are provided.

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

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

With no annotations, the description carries the behavioral disclosure and does so meaningfully: it states pagination, page-by-page scanning, cost on large scorecards, and the contents of the result (individual rule scores and overall scores). It does not explicitly state read-only status, auth, or rate limits, but 'Retrieve' plus the absence of side-effect language makes the operation's nature clear.

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 compact sentences front-load the primary purpose and result, then add a targeted usage caveat. No redundant filler; the performance warning is the only extra detail and it 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 read-only listing tool with no output schema and no annotations, the description covers the essential contract: scope, result content, pagination, and cost. It falls short of fully disambiguating the optional entityTag filter and the related listScorecardScoresForEntity sibling, but overall an agent can 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?

Schema description coverage is 100%, so the schema already documents tag, page, pageSize, entityTag, session_id, and context. The description adds general behavior (paginated results, all entities) but no parameter-specific semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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 specific verb ('Retrieve'), a clear resource ('scores for all entities evaluated by a specific scorecard'), and the result contents. It contrasts naturally with the sibling listScorecardScoresForEntity by emphasizing 'all entities' and explicitly references searchScorecardScores as the filtered alternative.

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 routing: prefer searchScorecardScores for filter-based questions, and warns that this tool scans page-by-page and is expensive on large scorecards. However, the named alternative searchScorecardScores does not appear in the provided sibling-tools list, and the closely related sibling listScorecardScoresForEntity is not mentioned, leaving some routing 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?

No annotations are provided, so the description must carry behavioral disclosure. It states the output (score and rule outcomes) but does not mention whether the operation is read-only (implied by 'List'), any pagination, rate limits, or performance characteristics. For a list operation this is acceptable but not comprehensive; the description adds only surface-level behavior.

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

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

Two concise sentences with no waste. The core purpose is front-loaded, and the alternative tool is mentioned in the second sentence without over-explaining.

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 sufficient for a simple list operation. It clearly states what is returned (score and rule outcomes) and distinguishes from the sibling. Given the rich schema descriptions for all parameters and the absence of an output schema, the description covers the essential context. A slight gap is the lack of mention of any result size or pagination, but it's not critical.

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 100%, so the parameters are fully documented in the schema. The tool description adds no extra meaning about tagOrId, session_id, or context beyond what the schema already provides. Baseline 3 is appropriate.

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 ('List'), a clear resource ('every scorecard that evaluates one entity'), and the included data ('score and rule outcomes'). It explicitly contrasts with the sibling tool listScorecardScores, making the purpose unambiguous.

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

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

It directly names the alternative tool (listScorecardScores) and the condition for using it ('to read one scorecard across many entities'), giving the agent a clear decision rule. The 'per-entity view' framing reinforces when this tool is appropriate.

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