Cortex

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

With no annotations provided, the description carries the burden of disclosing behavior. It indicates a read-only operation ('Retrieve') and provides useful context by stating 'in real-time' and specifying the output contents (primary/secondary on-call, contact info, rotation schedules). This goes beyond a minimal label but could further mention caching or absence handling.

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, well-structured sentence that front-loads the primary action and then adds concise clarifying details. Every phrase contributes to understanding the tool's function without redundancy.

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

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

The description is sufficient for a simple read-only tool with fully documented parameters. It covers the key output areas (personnel, contact info, rotation) and the real-time nature. The lack of an output schema is compensated by the description's detail, but it could mention error cases or prerequisites for completeness.

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?

Both parameters are fully described in the schema (100% coverage), including the dual meaning of 'tagOrId' and the purpose of 'context'. The tool description adds no extra parameter semantics, so the baseline of 3 applies since the schema does the heavy lifting.

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 ('Retrieve') and resource ('current on-call personnel for an entity'), and it distinguishes itself from sibling tools by exclusively addressing on-call personnel. The additional detail about primary/secondary and contact information reinforces the specific purpose.

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

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

The description implies when to use the tool (when real-time on-call status is needed) and clarifies it returns active responsibility for incident response. However, it does not explicitly mention alternatives or state when not to use it, leaving the guidance implicit 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?

No annotations are provided, so the description carries the full burden. It clearly signals a read operation via 'List' and 'Retrieve' and discloses pagination support. However, it does not mention authentication requirements, error behavior, or result format, leaving only partial transparency.

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

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

The description is three sentences: the first states the core action, the second adds example content types, and the third notes pagination. Each sentence contributes useful context with no wasted words, though it could be slightly tighter.

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

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

With no output schema and no annotations, the description could do more to explain the return structure or error/success outcomes. It covers the core operation and pagination hint, but it lacks explicit usage distinction from the key-specific sibling and does not explain what happens when no data exists or the entity is not found.

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's phrase 'Supports pagination' reiterates the page/pageSize parameters already documented in the schema, and it adds no additional parameter-level meaning 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 opens with 'List all custom data key-value pairs associated with an entity,' using a specific verb and resource. It clarifies entity types ('services, resources, or domains') and 'all' implicitly distinguishes from sibling getCustomDataForEntityByKey. However, it does not explicitly name the alternative tool, so it misses the top tier.

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 all custom data for an entity) and mentions pagination for large datasets, but it never explicitly contrasts with getCustomDataForEntityByKey or other sibling tools. No when-not-to-use guidance or alternative tool names 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 burden. It communicates read-only intent ('Retrieve') and adds performance/scope context ('efficiently', 'without fetching all custom data'), which is useful. It does not address error conditions or return format, but for a simple read operation 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?

The description is a single, front-loaded sentence with no filler. Every word earns its place by conveying the action, scoping, and efficiency benefit.

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?

Adequate for a simple read tool: it explains the core function and performance tradeoff. However, there is no output schema and no explicit mention of return format or error behavior, and it does not directly compare with getCustomDataForEntity, leaving some 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 covers 2 of 3 parameters; 'key' lacks a description. The tool description clarifies that 'key' refers to a custom data attribute key, but adds little beyond what the schema already provides for tagOrId and context. With 67% coverage, the description only partially compensates.

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 ('Retrieve a specific custom data value by key for an entity') and differentiates from siblings by emphasizing 'without fetching all custom data'. This makes the tool's purpose unambiguous and distinct from getCustomDataForEntity.

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

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

The description implies the appropriate use case (single attribute lookup) and contrasts with bulk retrieval via 'without fetching all custom data'. However, it does not explicitly name the sibling tool or state when not to use it, so it stops short of a 5.

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

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

No annotations are present, so the description carries the burden. It discloses that the tool returns event details including title, description, timestamp, type, and custom data, which is useful behavioral context. However, it does not explicitly state that the operation is read-only, nor does it mention error behavior, permissions, or any side effects, which would enhance transparency.

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

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

The description is two sentences long, front-loaded with the primary action, and contains no filler. Every word contributes meaning, making it highly concise and well-structured.

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

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

This is a simple retrieval tool with no output schema. The description lists the return fields, which suffices to convey the output. The schema documents the context parameter with a detailed explanation. However, it lacks mention of edge cases (e.g., not found) or how this relates to listing events, so it's not fully complete but is adequate for a simple getter.

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% (tagOrId and context have descriptions; uuid only has format). The description adds the fact that the tool returns 'custom data associated with the event' but does not elaborate on parameter semantics beyond what the schema already states. 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 states 'Retrieve a specific custom event by its UUID' which clearly identifies the action (retrieve) and resource (custom event by UUID). This distinguishes it from siblings like listCustomEventsForEntity, which lists events, and getCustomDataForEntity, which retrieves custom data rather than events.

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 such as listCustomEventsForEntity or getCustomDataForEntityByKey. The description does not mention any exclusions, prerequisites, or relative advantages, leaving the agent to infer usage context from the tool name alone.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose that the operation returns paginated data and supports date-range filtering, which are useful behavioral traits, but it does not mention any constraints, error cases, or permission requirements. Since this is a read operation, the absence of mutation side effects is less critical, but more detail would be needed for full transparency.

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

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

The description is two sentences, front-loaded with the primary action and resource, and every clause adds relevant information. It is appropriately sized without unnecessary 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?

Given the tool has 7 parameters, 5 required, no output schema, and no annotations, the description should provide a clear picture of the returned data. It mentions paginated time-series data and filtering but does not describe the structure of the data points or any default behaviors beyond what the schema states for parameters. The description is adequate for a straightforward read tool but leaves gaps about response 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?

The input schema has 100% description coverage for all 7 parameters, so the baseline is 3. The description adds context about pagination and date-range filtering, which align with page/pageSize and startDate/endDate, but it does not add new meaning beyond the schema descriptions.

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

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

The description clearly states the tool retrieves custom metric data points for an entity, specifies it returns paginated time-series data for a specific custom metric, and mentions optional date-range filtering. However, it does not explicitly differentiate from sibling tools like getCustomDataForEntity or queryPointInTimeMetrics, so it stops short of perfect clarity.

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

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

The description implies usage for analyzing trends and patterns with optional date-range filtering, which gives some context. However, it does not provide explicit when-to-use guidance, exclusions, or alternatives among the many sibling tools, so the agent must infer the appropriate 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?

With no annotations, the description carries the full burden for behavioral disclosure. It only says what the tool retrieves, but does not mention whether this is a read-only operation, how errors are handled, whether authentication is needed, or any other side effects or constraints. The tool name and description imply a read operation, but this is not explicitly 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?

The description is concise (one sentence plus a usage clause), front-loads the core action, and avoids unnecessary wording. It could be slightly more structured to include parameter details, but the length is appropriate.

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

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

Given that there are 5 parameters, no output schema, and no annotations, the description is incomplete. It does not explain what each parameter means, what the return value looks like, or how this tool differs from other dependency-related tools. A single sentence cannot adequately guide an agent in invoking this tool correctly.

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

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

Schema description coverage is only 20% (only the context parameter has a description). The descriptive text mentions 'between two entities' hinting at callerTag and calleeTag, but it does not explain the role of the path, method, or context parameters. The description fails to compensate for the lack of schema documentation.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource ('specific dependency details between two entities') and the content (method, path, metadata). This distinguishes it from sibling tools like listDependenciesForEntity, which list all dependencies rather than a single detailed relationship.

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

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

The description states it is 'useful for understanding the nature of the relationship, API contracts, and communication patterns between services', which implies when to use it. However, it does not explicitly contrast with alternative tools, mention prerequisites like having caller and callee tags, or provide any when-not-to-use guidance.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It clearly indicates a read/list operation, specifies the output fields (timestamps, environments, SHAs, deployment types), and mentions paginated format. It does not disclose potential limitations like ordering or access requirements, but these are not critical for a straightforward read tool.

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

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

The description is two concise sentences, front-loaded with the action and resource. No redundant or filler content; each sentence adds value.

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

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

The tool is a simple read operation with fully described parameters. Although there is no output schema, the description covers the key return fields and pagination format, making it sufficiently complete for an agent to invoke correctly.

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

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

The input schema already provides 100% descriptive coverage for all four parameters. The description adds no additional parameter-level semantics beyond the schema; it only loosely references entity and pagination.

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 deployments for a specific catalog entity, with a specific verb and resource. It distinguishes itself from sibling get* tools by focusing on deployment history rather than entity details or custom data.

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

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

The description implies the use case (when you need deployment history for an entity) but does not explicitly state when to use it versus alternatives, nor any exclusions. The pagination parameters suggest intended usage, but no direct comparison to sibling tools 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 must disclose behavioral traits. It does not mention that this is a read operation, any side effects, permissions, or response behavior. The phrase 'Access and manage' even misleadingly implies a broader scope than a getter.

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 generic sentence that provides no specific information. It is under-specified rather than appropriately concise, as no part of the text earns its place by helping the agent select or invoke the 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, the description must compensate by explaining purpose and behavior. Instead it gives a broad catalog API overview, omitting what a descriptor is, what the return value contains, and any usage context. This is completely inadequate for a tool with three parameters.

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

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

The input schema already describes all parameters (100% schema coverage), including tagOrId and yaml. The description adds no additional parameter context, so it meets the baseline for schema-covered parameters but does not enhance semantics.

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 is a generic umbrella statement ('Cortex Catalog API - Access and manage your service catalog, teams, domains, and resources') and does not mention 'entity descriptor' or a retrieval action. It fails to state what this specific tool does, making it vague and indistinguishable from a broad platform description.

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

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

There is no guidance on when to use this tool versus its siblings like getEntityDetails or listEntityDescriptors. No context or alternative mention is provided, leaving the agent without decision 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 for behavioral disclosure. It only states the tool 'retrieves' details, which implies a read operation, but it does not mention permissions, error handling (e.g., invalid ID), return format, or any side effects. For a tool with no structured safety hints, this is a significant gap.

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

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

The description is concise at two sentences. The first sentence is packed with useful scope information, and the second adds the 'primary method' context. Every word earns its place, though the second sentence is slightly redundant with the first.

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 should clarify what the tool returns, but it only says 'comprehensive details.' For a tool with 5 parameters and many sibling tools offering specific facets, the description gives a good overview but does not explain the response structure or how this tool differs in output from others. It is adequate but leaves 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?

The input schema has 100% coverage, so every parameter is already described (e.g., includeOwners, hierarchyDepth). The description adds a high-level context by mentioning 'ownership, hierarchies, and relationships,' which maps to the parameters, but it does not provide additional guidance on how to use the parameters or what valid values like 'full' mean beyond the schema. 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 clearly states the tool retrieves comprehensive details about a specific entity, listing metadata, ownership, hierarchies, and relationships. It uses a specific verb ('retrieve') and resource ('entity details'), and distinguishes it as the 'primary method' for complete information, though it does not explicitly contrast with siblings like getEntityDescriptor 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 provides clear context by calling this the 'primary method' for getting complete information, implying it is the go-to tool for full entity details. However, it does not explicitly state when not to use it or mention any alternative tools, so it falls short of the full 5.

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

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

The description implies a read-only action via 'Retrieve' and lists the information categories returned, which is useful. But with no annotations, it does not disclose access prerequisites, error behavior, or how missing/invalid initiative IDs are handled, leaving notable gaps.

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

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

Two sentences with no filler. The description is front-loaded with the action and resource, and every phrase adds value—no repetition of schema or annotations.

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

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

The description lists several output facets, which helps in the absence of an output schema. However, it omits any guidance on how to specify the initiative (cid) or what to put in 'context,' making the tool less complete for an agent encountering it for the first time.

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 50%, with the 'cid' parameter completely undescribed. The description does not compensate by explaining that cid is the initiative identifier or clarifying the purpose of the 'context' parameter. This leaves parameter meaning ambiguous.

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

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

The description clearly states the action ('Retrieve'), the resource ('detailed information about a specific initiative'), and lists the content areas (goals, timeline, affected entities, scorecard targets, current progress). This distinguishes it from sibling tools like listInitiatives, which enumerate initiatives rather than detail one.

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

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

It provides clear context for when to use the tool, calling it 'essential for understanding initiative scope and tracking achievement of objectives.' However, it does not explicitly mention alternatives or exclusions, such as using listInitiatives to discover initiative IDs before calling this 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 disclosing behavior. It only says 'check for additional tools' but omits what happens upon invocation: return format, whether it is read-only, side effects, limitations, or rate limits. This is a significant transparency gap for a meta-tool.

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

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

The description is a single, front-loaded sentence that immediately states the tool's purpose and primary usage condition. Every phrase earns its place, and there is no redundant or vague 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?

Since an output schema exists, the description does not need to explain return values. It clearly covers what the tool does and when to use it, making it minimally viable. However, it lacks behavioral details (e.g., side effects, read-only nature) and does not describe what 'additional tools' means in practice, leaving some ambiguity for an agent.

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

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

Schema coverage is 100% and the parameter already has a clear description ('A description of your goal and what kind of tool would help accomplish it'). The tool description adds a usage hint ('even if existing tools could work as a fallback') but does not add substantive parameter semantics beyond the schema. 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?

The description states a clear verb and resource: 'Check for additional tools.' It also gives a specific purpose (benefiting from specialized capabilities) which distinguishes it from sibling data-retrieval tools. The tool is positioned as a meta-tool for discovering other tools, so it 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 provides an explicit when-to-use condition: 'whenever your task might benefit from specialized capabilities.' It even clarifies to use it 'even if existing tools could work as a fallback,' which is a strong usage directive. However, it does not mention when not to use or suggest alternatives, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden. It discloses the combined response format, the 'itemType' field, pagination through sub-requests, and placeholder behavior. It does not mention rate limits or authentication, and there is an ownershipSource enum mismatch between schema and description, which slightly detracts from trust. Overall, it is transparent enough for an agent to predict behavior.

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

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

The description is long but well-structured with clear headings (FLEXIBLE REQUEST STRUCTURE, RESPONSE STRUCTURE, EXAMPLES). Most sentences serve a purpose, and the examples make the usage concrete. It is not as brief as it could be, but the structure aids comprehension for a complex multi-resource 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?

Given the tool's complexity (multiple resource types, no output schema), the description is unusually complete. It explains the response array structure, the 'itemType' enum, how to combine requests, and provides four distinct examples covering different use cases. Pagination is documented in schema and reinforced by examples. This is sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples for each request object (e.g., {'myEntitiesRequest': {'entityTypes': ['service']}}) and clarifying that fields can be combined. However, the ownershipSource description contradicts its own enum values ('DIRECT, INHERITED, ALL' vs schema enum 'DIRECT, TEAM_HIERARCHY'), which is a negative signal.

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

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

The description states a clear verb and resource: 'retrieving current user's owned resources and work items across the Cortex workspace.' It then enumerates the resource types and gives examples, which differentiates it from sibling tools that focus on single entity types (e.g., listAllEntities, getEntityDetails). The scope is specific and actionable.

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

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

The description clearly conveys when to use the tool via the 'FLEXIBLE REQUEST STRUCTURE' section and examples, explaining how to fetch multiple resource types in one call and when to set specific fields. However, it does not explicitly mention alternatives or when not to use this tool, so there is room for more explicit exclusion guidance.

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

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

With no annotations, the description must carry behavioral info. It explains what data is returned (configuration, rules, filters, inheritance), which is helpful, but it does not mention permissions, possible errors, or explicitly state that it is a read-only operation (though 'Get' implies it). This is acceptable 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, front-loaded with the action and content. The second sentence adds context without being redundant. Every word earns its place, making it appropriately concise and well-structured.

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

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

For a simple read tool with 2 parameters, no output schema, and no annotations, the description adequately covers the purpose and expected contents of the response. It lacks details on error handling or specific prerequisites, but the overall information is sufficient for an agent to invoke the tool correctly in most situations.

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 50%, but the only described parameter (context) has a generic prompt not specific to this tool. The key parameter relationshipTypeTag is undocumented in both schema and description. The description says 'specific relationship type' but fails to mention how to identify it via the tag, so it does not compensate for the schema gap.

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

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

The description clearly states 'Get complete details of a specific relationship type' with a specific verb and resource. It further lists the included aspects (configuration, rules, source/destination filters, inheritance settings), which distinguishes it from sibling tools like listRelationshipTypes or listEntitySourcesForRelationshipType that focus on listing or specific sub-aspects.

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 use case ('Essential for understanding how entities can be connected and what validation rules apply') but does not explicitly compare with alternatives or state when not to use it. Sibling tools like listRelationshipTypes could be competing choices, but no exclusions or direct comparisons 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?

No annotations are provided, so the description carries the full burden. While 'Get' implies a read-only operation, the description does not disclose potential side effects, required permissions, error behavior, or rate limits. It only lists content categories and gives a use case, offering limited transparency about the tool's actual execution behavior.

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

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

The description is concise, consisting of just two sentences. The first sentence front-loads the purpose and lists specific content areas, while the second adds a clear use case. Every word earns its place, with no 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?

Given the absence of an output schema, the description provides a useful overview of the returned content (configuration, rules, levels, weights, exemption settings, evaluation criteria). It does not describe the exact structure or error handling, but for a getter tool with a straightforward purpose, it offers enough context to set expectations. The usage context further aids completeness.

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 has 100% coverage for both parameters (tag and context) with clear descriptions. The tool description does not add any additional meaning about parameters, so it aligns with the baseline score of 3. It neither reinforces nor contradicts the schema.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource ('scorecard') and the scope of details returned (configuration, rules, levels, weights, exemption settings, evaluation criteria). This distinguishes it from sibling tools like listScorecards and listScorecardScores, which focus on listing rather than complete detail retrieval.

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 this tool ('understanding how services are evaluated and what standards they must meet'), implying it is the right choice when a comprehensive view of a scorecard is needed. It does not explicitly mention alternatives or exclusions, but the resource-specific wording helps differentiate it from sibling tools.

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

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

With no annotations, the description carries the burden of conveying behavior. It transparently states that the tool 'Shows which rules need to be satisfied to reach the next maturity level,' making it clear this is a read-only informational query. It does not detail output format or edge cases, but the behavioral intent is unmistakable.

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, front-loaded with the core action and easily scannable. Every word contributes to explaining either the tool's function or its value, with no 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 tool with 3 parameters, no output schema, and no annotations, the description adequately conveys what the tool returns (actionable next steps/rules) and its purpose. It could be slightly more explicit about the output structure or potential failure modes, but the current description is sufficient for an agent to know what to expect.

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 additional parameter-level meaning beyond what the schema already provides, but it does reinforce the purpose of the entity and scorecard parameters by tying them to maturity-level progress.

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 ('Get') and identifies the resource ('actionable next steps for an entity to improve its scorecard performance'). It clearly distinguishes this tool from siblings like getScorecard or listScorecardScores by focusing on improvement guidance rather than raw scores or definitions.

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

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

The description gives clear context for when to use the tool: when teams need to prioritize improvements and track compliance goals. It does not explicitly name alternative tools or exclusions, but the purpose is specific enough for an agent to decide 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.

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

With no annotations, the description carries the full burden. It proactively discloses what the response includes ('complete team data including members, slack channels, metadata, and whether it's backed by an identity provider group'), which provides meaningful behavioral context beyond 'retrieve'. The word 'Retrieve' implies a read-only operation.

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

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

The description is a single, well-front-loaded sentence. Every clause adds value: what the tool does, how the team is identified, and what data is returned. No redundant or verbose language.

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 (2 params, no output schema), and the description covers the key return contents. The schema covers both parameters, including the unusual 'context' parameter. It is complete enough for straightforward usage, though it could mention that the 'context' field should be used for rationale.

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%—both parameters are described in the schema. The description's phrase 'by its tag or ID' parallels the schema's 'tag or CID' and adds no new semantic information. Therefore a 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?

The description clearly states a specific action ('Retrieve detailed information') and resource ('a specific team'), and enumerates the key data returned (members, slack channels, metadata, IdP group). The focus on 'team' distinguishes it from generic entity tools like getEntityDetails.

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

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

No guidance is given on when to use this tool vs alternatives such as getEntityDetails or other get_* tools. The description implies a general use case but does not provide exclusions, prerequisites, 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?

No annotations are provided, so the description carries the full burden. It discloses pagination and structured filtering but does not describe return format, default filters (e.g., types default), or that it may exclude archived entities unless requested. The mention of 'structured filters' gives some behavioral context, but not rich detail.

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

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

Two sentences, front-loaded with the core action and key differentiator. No filler or redundant repetition of schema info.

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 16 parameters and no output schema, the description does not explain return values, but the schema covers parameter semantics. The description provides enough context for the tool's role in a workflow and its relationship to searchCatalog, but could benefit from mentioning default exclusion of archived entities or default types.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds little beyond naming a subset of filters (groups, types, owners, git repositories) and pagination, but does not provide additional syntax or interaction details 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 uses a specific verb ('List and enumerate') with a clear resource ('catalog entities') and method ('by structured filters'). It explicitly differentiates from sibling tool searchCatalog, which is for name/relevance/team/domain searches.

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 when-not-to-use guidance by naming searchCatalog as the alternative for name-based or relevance-based searches. The description itself implies use for structured filter-based browsing, and the alternative statement clarifies boundaries.

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

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

No annotations are provided, so the description carries the burden. It discloses pagination and filtering behaviors, but does not mention return shape, ordering, or the deprecated 'timestamp' parameter. 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 sentences with a clear purpose, but there is redundancy between 'optional filtering by type and time range' and 'filtering by event type, start time, and end time'. Still appropriately sized.

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

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

The description covers the core behavior (list, filter, paginate) for an 8-parameter tool with no output schema. It omits required identifier/context parameters and the deprecated timestamp, but the schema fills most 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 88%, so the schema already documents most parameters. The description maps filtering to type/startTime/endTime and pagination to page/pageSize, adding minimal meaning beyond the schema.

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

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

The description clearly identifies the tool as listing custom events for an entity, with optional filtering and pagination. It distinguishes from siblings like getCustomEventForEntityByUuid by emphasizing the plural 'events' and historical retrieval.

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 retrieving historical event data with filtering and pagination, but does not explicitly exclude alternatives or state when to prefer this over other event tools. The context is clear, but no alternatives are named.

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 fully disclose behavior, but it only partially does. It mentions both incoming and outgoing dependencies, yet fails to mention that includeIncoming defaults to false, so default behavior returns only outgoing relationships—contradicting the 'including both' phrasing. Pagination behavior, response shape, and read-only nature are also undisclosed. This is a significant transparency gap for a 6-parameter tool.

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

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

The description is two sentences with a strong front-loaded verb-object structure. The second sentence adds practical value by naming use cases. There is no redundant wording, tautology, or filler. It earns a 5 for being efficient and purposeful.

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 6 parameters, no annotations, and no output schema, so the description must carry substantial weight. It does not explain pagination semantics, the meaning of callerTag, the effect of setting both boolean flags to false, or what the returned dependencies look like. The phrase 'List all dependencies' is also incomplete given the default to outgoing-only. This is not enough context for an agent to invoke the tool reliably without additional assumptions.

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 50%, so the description must compensate for callerTag, includeIncoming, and includeOutgoing. It adds conceptual meaning for the boolean flags ('incoming' and 'outgoing') but does not clarify their defaults or how to request both directions. It also omits callerTag entirely and doesn't explain the 'all' claim in light of pagination defaults. The description actually misleads by implying both directions are always included.

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-object pair ('List all dependencies for an entity') and clearly distinguishes incoming vs outgoing relationships. It separates this from sibling tools like getDependency, which implies a single relationship, and provides a clear domain purpose. The use cases ('understanding service interactions, planning changes, and assessing blast radius') reinforce why this tool exists.

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

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

The description gives clear context for when to use the tool: understanding interactions, planning changes, and assessing blast radius. It does not explicitly name alternative tools for other scenarios or state when not to use it, but the use-case framing is specific enough to guide selection among the large sibling list. A 4 is appropriate because exclusions/alternatives aren't stated.

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

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

With no annotations provided, the description must disclose behavior, but it only says 'Access and manage,' implying both read and write capabilities. This is misleading for a list operation and does not mention pagination, filtering, or response format.

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 single sentence is short but under-specified, providing only a vague API-level statement. It is not effective conciseness because it omits the tool's actual purpose and key behaviors.

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 list tool with 5 parameters, no output schema, and no annotations. The description is entirely insufficient to understand what the tool does, when to use it, or what results to expect, making it inadequate 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 coverage is 100% with clear descriptions for each parameter (e.g., page, pageSize, types). The tool description adds no additional parameter meaning, 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 'Access and manage your service catalog, teams, domains, and resources' is a generic API overview, not specific to listing entities. It fails to state the core action (listing entity descriptors) and does not distinguish from sibling tools like listAllEntities or searchCatalog.

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

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

There is no guidance on when to use this tool versus alternatives. The description does not mention listing, pagination, or that it is a read-only catalog query, leaving the agent without context for 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?

With no annotations, the description carries the burden of behavioral disclosure. 'List all destinations' clearly indicates a read-only operation, and the hint about listRelationshipTypes adds useful context. However, it does not define what a destination is, describe the output shape, or mention how archived entities and hierarchy depth are handled beyond the schema.

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

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

The description is two concise sentences with no filler. It front-loads the primary action and follows with a practical prerequisite hint, making it easy to parse quickly.

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 no output schema, so the description should ideally describe what the returned destinations look like, but it does not. It also does not explain how this tool differs from listEntitySourcesForRelationshipType or listEntityRelationships, though the name provides some clues. Overall, it is adequate but leaves meaningful gaps.

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

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

The schema covers most parameters, but relationshipTypeTag has no schema description. The description compensates by explaining that listRelationshipTypes can be used to find the appropriate relationshipTypeTag, and it clarifies that tagOrId refers to the entity. This adds value over the schema alone.

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

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

The description uses a specific verb ('List') and clearly identifies the resource ('destinations for a certain relationship type & entity'). This distinguishes it from sibling tools like listEntitySourcesForRelationshipType and listEntityRelationships.

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

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

It explicitly instructs the user to use listRelationshipTypes to find the relevant relationshipTypeTag, which addresses a key prerequisite. It doesn't spell out exclusions versus other relationship listing tools, but the context is sufficient for basic 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?

Annotations are absent, so the description must carry the full burden. It discloses pagination ('Returns paginated results') and org-wide scope, which are useful behavioral traits. However, it does not mention potential costs, rate limits, or that the result set could be large, and does not explicitly state that it is a read-only operation.

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

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

The description is two sentences, front-loaded with the primary action, and every phrase adds value. It avoids redundancy and fluff, making it highly 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?

For a list tool with no output schema and no annotations, the description covers the key aspects: what it lists, the scope, return type (source-destination pairs), and pagination. It is reasonably complete, but the missing documentation for `relationshipTypeTag` and absence of guidance on where to find valid tags leave a small gap.

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

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

Schema description coverage is 75%, but the key parameter `relationshipTypeTag` has no documentation in either schema or description. The description adds little parameter-specific meaning beyond mentioning pagination, and does not guide the user on how to obtain valid relationship type tags (e.g., via listRelationshipTypes). This is a notable gap.

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

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

The description clearly states the tool lists all entity relationships for a specific type across the organization, using a specific verb ('List') and resource ('entity relationships'). It also implicitly distinguishes from sibling tools by emphasizing 'full graph' and 'all source-destination pairs', which differentiates it from more targeted tools like listEntitySourcesForRelationshipType.

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 ('useful for understanding the complete relationship graph and finding all connections of a particular type'). It does not explicitly exclude alternatives or name when-not-to-use scenarios, but the context is sufficient for an agent to choose this over sibling tools that handle individual sources/destinations.

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 bears full responsibility for behavioral disclosure. The phrase 'List all sources' may be misleading because the schema indicates a default depth of 1 (direct relationships only), and the description does not mention this limitation, pagination, or other behavioral traits.

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

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

The description is concise, consisting of two sentences that front-load the primary purpose and include a helpful pointer to a related tool. There is no unnecessary verbiage.

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

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

Given that there is no output schema and 5 parameters, the description is too brief. It does not explain what 'sources' refers to, what the return shape looks like, or how depth/archival flags affect results, leaving the agent with significant gaps in understanding.

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?

While schema coverage is 80% and already documents most parameters, the description adds value by clarifying that tagOrId is the entity and relationshipTypeTag is the relationship type, and it tells the user how to discover valid relationshipTypeTag values via listRelationshipTypes. This goes 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 clearly states the tool lists sources for a given relationship type and entity, using a specific verb and resource combination. However, it does not explicitly differentiate from the sibling tool listEntityDestinationsForRelationshipType, so it falls short of a 5.

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

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

The description offers a prerequisite hint by pointing to listRelationshipTypes to find relationshipTypeTag, but it does not explicitly state when to use this tool over alternatives or when not to use it. The guidance is useful but only implied rather than fully spelled out.

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

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

No annotations are provided, so the description carries the burden. It discloses that the tool lists all initiatives with optional filters for drafts and expired ones, and indicates return content (status). However, it does not mention pagination behavior or response format, which are left to the schema.

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

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

The description is two sentences: the first states the action and filters, the second explains the purpose and return value. No filler words; it is concise and front-loaded.

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

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

For a straightforward list tool with all parameters documented in the schema, the description covers the essential aspects: what it lists, the filters, and the output content. It does not explicit mention pagination, but that is covered by the schema parameters, making it adequately 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 meaning by clarifying that 'optional filters' map to includeDrafts and includeExpired, and by explaining what the output represents (active programs, status). It does not add extra syntax details 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 uses a specific verb 'List' with a clear resource 'initiatives' and scope 'in the organization'. It distinguishes from sibling tool 'getInitiative' by emphasizing 'all initiatives' and mentioning optional filters.

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

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

The description provides clear usage context: 'View active improvement programs, strategic projects, and their current status to understand organizational priorities and track progress.' It implies when to use the tool but does not explicitly name alternatives or when not to use it.

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

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

No annotations are provided, so the description carries the full burden. It discloses caching expectations ('Cache responses in your context'), error responses (400, 403), and that full view returns sources and query metadata. It does not explicitly state read-only, but 'List' and the usage context make it clear. This level of disclosure is above average.

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 exceptionally well-structured with sections (USAGE, Query parameters, Full view..., Filter operators by type, Error responses). Every section provides distinct, non-redundant information. No fluff.

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

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

No output schema exists, but the description explains what full view returns (supportedAggregations, orderByAttribute, groupByOptions, filterOptions) and how to interpret them. It also covers error codes and prerequisites. For a metadata-listing tool, this is comprehensive.

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 low (only the generic context param is described). The description compensates fully: explains view='basic' vs 'full', key filtering (multiple values, comma-separated), and enumerates the metadata returned for query construction. This gives agents everything they need to set parameters correctly.

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

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

The description opens with 'List all available engineering metric definitions' – a specific verb and resource. It further distinguishes this from querying metrics by explicitly stating to call this 'BEFORE querying metrics (queryPointInTimeMetrics)' and by listing sibling-related metadata. This clearly differentiates it from sibling tools.

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

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

Provides explicit step-by-step usage: '1. Once at start: Call with view='basic'... 2. Once per metric... 3. Use cached metadata...' It also instructs caching behavior and when to refresh. This is strong actionable guidance for when to use vs. the query 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?

With no annotations provided, the description carries the full burden. It discloses pagination behavior and the 'all' scope, and 'List' implies a read operation. However, it does not explicitly say it is read-only, nor does it mention any error conditions, ordering, or rate limits.

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

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

The description consists of two sentences. The first sentence is tightly worded and informative. The second sentence adds contextual purpose with entity examples, which is useful but slightly redundant. Overall, it is concise and easy to scan.

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

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

For a simple listing tool with no output schema, the description is reasonably complete. It explains what is listed (relationship types) and why it's useful (understand possible relationships between entities). It lacks details about return fields or ordering, but that may be acceptable given the tool's simplicity.

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 baseline is 3. The description adds no parameter-specific semantics beyond mentioning pagination, which is already clear from the page/pageSize parameter descriptions. It does not compensate for any gaps since there are none.

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

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

The description clearly states the tool lists all available relationship types with pagination, which is a specific verb+resource combination. It distinguishes from siblings implicitly by saying 'all' vs. getRelationshipTypeDetails for a single type, but does not explicitly name alternatives.

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

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

The second sentence provides an implied use case: to understand what kinds of relationships can be created between entities. However, it does not explicitly state when to use this tool over siblings like getRelationshipTypeDetails or listEntityRelationships, nor does it mention any exclusions.

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 of disclosing behavior. It mentions optional filtering and filter dimensions, but does not reveal potential pagination behavior, whether drafts are included, or what fields the returned scorecards contain. It sufficiently indicates a read-only operation, but lacks deeper behavioral insight.

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, front-loaded with the primary action. Every sentence contributes: the first defines the operation and scope, the second explains the purpose and filter options. There is no fluff 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?

The tool has no output schema, so the description should provide context about return values. It mentions 'scorecard configurations' but does not specify response format, pagination behavior, or how drafts are handled. Combined with the lack of annotations, this leaves gaps for a complete understanding, though the core purpose is clear.

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

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

Schema coverage is high (86%), so the schema already documents most parameteters. The description adds value by naming the filter dimensions (groups, entities, teams), but does not elaborate on nuances like the instruction to use only one identifier type or the meaning of pagination defaults. Thus it neither compensates for gaps nor significantly extends 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 'List all scorecards in the organization with optional filtering,' establishing a clear verb ('list') and resource ('scorecards'). It differentiates from siblings like 'getScorecard' (singular) and 'listScorecardScores' (scores) by focusing on the scorecards themselves.

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: 'to understand quality standards, compliance requirements, and maturity models' and 'to find relevant scorecards.' It does not explicitly name alternatives or exclusions, but the intended use case is evident, especially compared to sibling tools that retrieve specific entities or scores.

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 transparency burden. It discloses pagination and the shape of results (rule scores and overall scores), but omits behavior around optional entityTag filtering, default page sizes, and edge cases like invalid scorecards. This is partial transparency, hence 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?

Two sentences communicate the core purpose and output without redundancy. Every phrase 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 no output schema and no annotations, the description explains what is returned but leaves out important context around entityTag, which shifts the result set from all entities to one. It also doesn't mention how pagination works in edge cases. Thus not fully complete, score 3.

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 reinforces that tag identifies a specific scorecard and results are paginated, aligning with page/pageSize, but does not add new parameter semantics. EntityTag filtering is left entirely to 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 'Retrieve scores for all entities evaluated by a specific scorecard', which combines a clear verb and resource. It further clarifies output scope (paginated per-entity results with rule and overall scores), distinguishing it from sibling tools like getScorecard and getScorecardNextStepsForEntity.

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 context: when you need aggregate scorecard performance across all entities. It does not explicitly call out alternatives or when not to use, but the 'all entities' scope contrasts with entity-specific siblings. Clear context but no exclusions, so 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?

No annotations are provided, so the description carries the transparency burden. It states the tool returns a response with 'answer and metadata', indicating read behavior, but does not explicitly confirm it is read-only, mention auth, rate limits, or limitations. For a query tool this is minimally 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 short and front-loaded with the purpose, followed by Args and Returns. It has no fluff, but it lists only 'query' under Args while 'context' is also required, making the textual summary slightly incomplete.

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 only two parameters and an output schema, the description is mostly sufficient: it identifies the input and output shape. However, it omits the required 'context' parameter in the prose and gives no fallback/error behavior, leaving minor gaps for an agent to infer.

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 50%; the description adds meaning for 'query' ('The question to ask Cortex docs') which the schema omits, while the 'context' parameter is already thoroughly described in the schema. This balances the coverage gap, though the description does not mention the required 'context' parameter in its Args section.

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

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

The description names a specific verb ('Query') and target ('Cortex knowledge base'), and states the outcome ('answers'). It is clear and distinct from sibling tools like 'searchCatalog' by referring specifically to docs/knowledge base, though it does not explicitly contrast with them.

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 this tool is for asking questions about Cortex docs via the query argument, but it does not state when to prefer it over alternatives (e.g., searchCatalog) or provide exclusions. Sibling-tool context is not referenced.

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 discloses the 6-month (180-day) time range limit, response structure (lightweight metadata, row data, no heavy schemas), error codes (400 and 403), and explicit caching instructions ('Do NOT cache point-in-time query results - always execute fresh queries'). It also clarifies that listMetricDefinitions results, not query results, should be cached. This is thorough and goes well beyond the schema.

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

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

The description is longer than typical but is well-organized into sections: a brief overview, PREREQUISITES with numbered workflow, IMPORTANT caching notes, response summary, and error codes. Each section earns its place given the tool's complexity. It is not bloated with repeated schema info, though it could be trimmed slightly without losing value.

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

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

Given the tool's complexity (14 parameters, 8 required, no output schema), the description provides a complete operational picture. It tells the agent exactly how to discover metrics, construct valid queries, handle caching, interpret responses, and anticipate errors. The reference to listMetricDefinitions fills the gap between discovery and execution, making the tool usable 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?

The input schema already covers 93% of parameters with descriptions, so the baseline is 3. The description adds crucial context beyond the schema: it explains that metric names, groupBy keys, filter keys, and orderBy attributes must come from listMetricDefinitions full view responses, and that startTime/endTime cannot span more than 180 days. This guidance directly helps construct valid values for metrics, groupBy, filters, and orderBy, which are otherwise only schematically described.

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: 'Execute point-in-time queries for one or more engineering metrics' and specifies it returns 'current metric values for specified time periods, with support for batch queries and optional period-over-period comparisons.' It also distinguishes itself from sibling tools by referencing listMetricDefinitions as a prerequisite for discovery, making the division of labor explicit.

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

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

The description offers a detailed workflow: call listMetricDefinitions first to discover metrics and cache metadata, then construct queries using exact values from those responses. It explicitly says 'Do NOT guess attribute names' and explains when to refresh cached metadata. However, it does not explicitly name alternative query tools (e.g., getCustomMetricData) or state when not to use this tool versus those alternatives, so it stops short of a 5.

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

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

No annotations are provided, so the description carries full burden. It discloses relevance ranking, supported query operators (AND/OR/NOT), scoping semantics, and the lean result structure. However, it omits behavior around includeArchived (archived excluded by default), and doesn't clarify whether query is optional, so some behavioral details remain implicit.

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

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

Four sentences, all purposeful: states purpose, query syntax, scoping options, and return format with alternative. No fluff, though slightly longer than minimal.

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

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

For a 9-param search tool with no output schema, the description explains the return fields and directs to getEntityDetails for full records, which is complete for a list/search result. It lacks explicit mention of pagination behavior and archived handling, but schema covers page/pageSize defaults. Overall adequate for invoking the tool correctly.

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

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

Schema description coverage is 89%, so baseline is 3. The description repeats schema details for query, types, owners, domains, and catalog without adding new syntax or semantic details beyond the schema. It adds practical context (e.g., 'put search text in query') but doesn't compensate for the undocumented includeArchived param.

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 states 'Search the catalog for entities (services, domains, teams, resources), ranked by relevance.' This is a specific verb+resource+scope, and explicitly distinguishes itself as 'the primary way to find entities,' also pointing to getEntityDetails for full records, differentiating it from sibling list/detail 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?

Description says 'This is the primary way to find entities' and explicitly directs to 'use getEntityDetails for the full record of a single entity.' It also provides alternative scoping methods. This gives clear when/why guidance relative to siblings.

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