Cortex

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 mentions 'real-time' retrieval and the types of information included (primary/secondary on-call, contact info, rotation schedules), but doesn't cover critical aspects like authentication requirements, rate limits, error conditions, or whether this is a read-only operation. The description adds some context but leaves significant behavioral gaps.

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

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

The description is appropriately concise with two sentences that efficiently convey the tool's purpose and scope. The first sentence states the core function, and the second elaborates on what information is included. No wasted words, though it could be slightly more 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 tool with 2 parameters, 100% schema coverage, and no output schema, the description provides adequate context about what the tool returns (on-call personnel details). However, without annotations and with no output schema, it should ideally mention more about the return format or behavior to be fully complete for an agent.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions 'entity' which aligns with 'tagOrId' but provides no additional syntax, format, or usage guidance for parameters.

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

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

The description clearly states the tool's purpose: 'Retrieve the current on-call personnel for an entity in real-time.' It specifies the verb ('retrieve'), resource ('on-call personnel'), and scope ('for an entity'), but doesn't explicitly differentiate from sibling tools like 'getEntityDetails' or 'getTeamDetails' that might also provide personnel information.

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 through 'real-time' and 'actively responsible for incident response,' suggesting this tool is for current operational needs. However, it doesn't explicitly state when to use this versus alternatives like 'getTeamDetails' for general team information or 'getEntityDetails' for broader entity data.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool 'Supports pagination,' which is a key behavioral trait not evident from the input schema alone. However, it doesn't mention other important aspects like whether this is a read-only operation, potential rate limits, authentication requirements, error conditions, or the format of returned data. For a tool with no annotations, this leaves significant gaps in understanding its 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 appropriately sized with three sentences that are front-loaded: the first states the core purpose, the second elaborates on what's retrieved, and the third adds a key behavioral note (pagination). There's minimal redundancy, and each sentence adds value. It could be slightly more structured by explicitly separating purpose from context, but it's efficient overall.

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 complexity (a list operation with pagination), no annotations, and no output schema, the description is moderately complete. It covers the basic purpose and pagination behavior but lacks details on output format, error handling, or permissions. For a tool with 4 required parameters and many siblings, more context on differentiation and usage would improve completeness, but it meets the minimum viable threshold.

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 thoroughly. The description adds no specific meaning beyond what the schema provides—it doesn't explain what 'entity' refers to in context, clarify 'tagOrId' usage, or provide examples. With high schema coverage, the baseline is 3, and the description doesn't compensate with additional insights, but it doesn't detract either.

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

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

The description clearly states the tool's purpose: 'List all custom data key-value pairs associated with an entity' and specifies what it retrieves ('metadata, configuration settings, and custom attributes'). It distinguishes from some siblings like 'getCustomDataForEntityByKey' by indicating it returns 'all' data rather than filtering by key. However, it doesn't explicitly differentiate from other list-style tools like 'listCustomEventsForEntity' or 'listMetricDefinitions' beyond the 'custom data' focus.

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 no explicit guidance on when to use this tool versus alternatives. It mentions 'Supports pagination for entities with large amounts of custom data,' which implies a usage condition but doesn't name specific sibling tools as alternatives or clarify exclusions. For example, it doesn't contrast with 'getCustomDataForEntityByKey' (which filters by key) or 'getEntityDetails' (which might include some custom data). Without such comparisons, the agent lacks clear 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 of behavioral disclosure. It mentions efficiency and scope ('without fetching all custom data'), which adds some context. However, it lacks critical details such as authentication requirements, rate limits, error handling, or whether the operation is read-only (implied by 'retrieve' but not explicit). For a tool with no annotations, this leaves significant gaps in understanding its 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 and front-loaded, with the first sentence stating the core purpose and the second adding efficiency context. Both sentences earn their place by providing value without redundancy. However, it could be slightly more structured by explicitly separating purpose from usage guidelines.

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 (3 required parameters, no annotations, no output schema), the description is moderately complete. It covers the purpose and efficiency aspect but lacks details on behavioral traits, parameter specifics, and return values. Without annotations or an output schema, the description should do more to compensate, but it provides a basic foundation that is adequate yet insufficient for full 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?

Schema description coverage is 67%, with two parameters ('key' and 'tagOrId') having minimal or no descriptions in the schema. The tool description adds some meaning by explaining that 'key' refers to 'metadata attributes, configuration values, or custom properties' and 'entity' is involved, but it doesn't detail parameter formats or constraints. It partially compensates for the schema gaps but doesn't fully clarify all three parameters, aligning with the baseline for moderate coverage.

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

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

The description clearly states the tool's purpose: 'Retrieve a specific custom data value by key for an entity.' It specifies the verb ('retrieve'), resource ('custom data value'), and scope ('by key for an entity'), distinguishing it from siblings like 'getCustomDataForEntity' (which likely fetches all data). However, it doesn't explicitly contrast with all relevant siblings, such as 'getCustomEventForEntityByUuid' or 'getCustomMetricData', which slightly limits differentiation.

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

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

The description implies usage guidelines by stating 'Efficiently access individual metadata attributes... without fetching all custom data,' suggesting this tool is preferred when only a specific key is needed. However, it doesn't explicitly state when to use alternatives (e.g., 'getCustomDataForEntity' for all data) or provide exclusions (e.g., when multiple keys are required). The guidance is helpful but not comprehensive.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states this is a retrieval operation, implying it's read-only and non-destructive, but doesn't confirm this explicitly. It lacks details on error handling (e.g., what happens if the UUID is invalid), authentication needs, rate limits, or response format beyond listed fields. For a tool with no annotations, this leaves significant gaps in understanding its 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 a single, well-structured sentence that front-loads the core purpose and lists returned details efficiently. It avoids redundancy and wastes no words, though it could be slightly more concise by omitting 'associated with the event' as implied. Overall, it's appropriately sized for the tool's complexity.

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

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

Given no annotations, no output schema, and 3 required parameters with partial schema coverage, the description is minimally adequate. It covers the basic purpose and return fields but lacks behavioral context, usage guidance, and parameter details. For a retrieval tool, this might suffice for simple use, but gaps in transparency and guidelines reduce completeness for more complex scenarios.

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% (2 of 3 parameters have descriptions). The description adds no parameter-specific information beyond what the schema provides—it doesn't explain 'tagOrId', 'uuid', or 'context' further. With moderate schema coverage, the baseline is 3, as the description doesn't compensate for the 33% gap (e.g., clarifying 'tagOrId' usage) but doesn't detract either.

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') and resource ('specific custom event by its UUID'), and specifies the returned details (title, description, timestamp, type, custom data). It distinguishes from siblings like 'listCustomEventsForEntity' by focusing on a single event via UUID rather than listing multiple events. However, it doesn't explicitly contrast with 'getCustomDataForEntity' or 'getCustomDataForEntityByKey', which might retrieve different data types.

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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing the UUID), exclusions, or compare it to siblings like 'listCustomEventsForEntity' for bulk retrieval or 'getCustomDataForEntity' for non-event data. The agent must infer usage from the tool name and parameters 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 mentions pagination and optional date filtering, which is helpful, but doesn't cover critical aspects like rate limits, authentication requirements, error handling, or whether this is a read-only operation (implied by 'retrieve' but not explicit). For a data retrieval tool with 7 parameters, this leaves significant gaps.

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

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

The description is a single, well-structured sentence that efficiently conveys the core functionality, resource, and key features (paginated time-series data, optional date filtering, analysis purpose). It's front-loaded with the main action and avoids unnecessary fluff.

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

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

Given the tool's complexity (7 parameters, no annotations, no output schema), the description is adequate but incomplete. It covers the basic purpose and some behavioral traits (pagination, filtering), but lacks details on output format, error cases, or performance characteristics, which are important for a data retrieval tool with multiple 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 schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds marginal value by implying that 'customMetricKey' and 'tagOrId' identify the metric and entity, and that date filtering is for trend analysis, but doesn't provide additional syntax or format details beyond what the schema specifies.

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

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

The description clearly states the tool's purpose: retrieving custom metric data points for an entity with paginated time-series data. It specifies the resource (custom metric data) and action (retrieve), but doesn't explicitly differentiate it from sibling tools like 'getCustomDataForEntity' or 'listMetricDefinitions', which might have overlapping functionality.

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 by mentioning 'analyze trends and patterns' and optional date filtering, suggesting it's for historical data analysis. However, it doesn't explicitly state when to use this tool versus alternatives like 'getCustomDataForEntity' or 'queryPointInTimeMetrics', nor does it mention prerequisites or 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?

No annotations are provided, so the description carries full burden for behavioral disclosure. It describes what information is retrieved (method, path, metadata) but doesn't cover critical aspects like whether this is a read-only operation, potential rate limits, authentication requirements, error conditions, or what format the output takes. For a tool with 5 parameters and no output schema, this leaves significant behavioral gaps.

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

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

The description is appropriately concise with two sentences. The first sentence states the core functionality, and the second provides usage context. Both sentences earn their place by adding value. It's front-loaded with the primary purpose stated immediately.

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 (5 parameters, no annotations, no output schema, low schema coverage), the description is insufficiently complete. It doesn't explain the return format, error handling, or the relationship between parameters like how callerTag/calleeTag interact with method/path. For a tool that appears to retrieve detailed dependency information, more context about what constitutes a 'dependency' and how results are structured would be needed.

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 tool description mentions 'two entities' which maps to callerTag and calleeTag, and 'method, path' which correspond to parameters, but doesn't explain what these parameters mean, their expected formats, or how they interact. With 5 parameters and low schema coverage, the description adds minimal semantic value beyond what's implied by parameter names.

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

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

The description clearly states the tool's purpose: 'Get specific dependency details between two entities including method, path, and metadata.' It specifies the verb ('Get'), resource ('dependency details'), and key attributes (method, path, metadata). However, it doesn't explicitly differentiate from sibling tools like 'listDependenciesForEntity' or 'listEntityRelationships', which appear to be related but broader operations.

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 implied usage guidance: 'Useful for understanding the nature of the relationship, API contracts, and communication patterns between services.' This suggests when to use it (for detailed dependency analysis) but doesn't explicitly state when not to use it or name alternatives among the many sibling tools. The context parameter description hints at broader planning but isn't part of the tool description itself.

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 burden of behavioral disclosure. It mentions that returns are 'paginated format' and includes details like timestamps and environments, which adds context beyond basic listing. However, it lacks information on permissions, rate limits, or error conditions, which are important for a tool with required parameters.

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, efficient sentence that front-loads the purpose and key details like pagination and return fields. It avoids redundancy, though it could be slightly more structured by separating usage notes from behavioral traits.

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

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

Given no annotations and no output schema, the description provides basic completeness by stating the purpose and return format. However, for a tool with 4 required parameters and no safety annotations, it should ideally include more about authentication, error handling, or output structure to fully guide the agent.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds no additional meaning beyond what's in the schema, such as explaining the 'tagOrId' format or 'context' usage. Baseline 3 is appropriate 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 the verb ('List') and resource ('deployments for a specific catalog entity'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'listAllEntities' or 'listEntityDescriptors' that might also involve listing operations, though the focus on deployments is specific enough for general 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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing an entity identifier, or compare it to other tools for deployment-related queries, leaving the agent to infer usage from the name and parameters alone.

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

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

No annotations are provided, so the description carries full burden for behavioral disclosure. The description mentions 'access and manage' but doesn't clarify whether this is a read-only operation (likely given the 'get' prefix) or has side effects. It provides no information about authentication requirements, rate limits, error conditions, or what format the descriptor returns (though the yaml parameter suggests both YAML and non-YAML formats are possible).

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

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

The description is a single sentence that's appropriately concise but fails to be front-loaded with the tool's specific purpose. It wastes its limited space on generic API branding rather than tool-specific functionality. While not verbose, it's inefficient in its information delivery.

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 (including a complex 'context' parameter requiring detailed reasoning), no annotations, and no output schema, the description is inadequate. It doesn't explain what an 'entity descriptor' contains, how it differs from entity details, or what format the output takes. The description fails to provide the necessary context for an agent to understand when and how to use this tool effectively.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds no parameter-specific information beyond what's in the schema. The baseline score of 3 reflects adequate coverage through the schema alone, though the description doesn't compensate with any additional parameter context.

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

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

The description 'Cortex Catalog API - Access and manage your service catalog, teams, domains, and resources' is vague and generic. It describes the entire API rather than this specific tool's purpose. While it mentions 'access and manage', it doesn't specify what getEntityDescriptor actually does (retrieve descriptor details for a specific entity). The description fails to distinguish this tool from its many siblings that also access catalog 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?

No guidance is provided about when to use this tool versus alternatives. The description gives no indication of what problem this tool solves or when it's appropriate. With 25+ sibling tools including listEntityDescriptors and getEntityDetails, the lack of differentiation is problematic. The context parameter description provides some meta-guidance about explaining tool usage, but this isn't part of the tool's actual description.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions retrieving 'comprehensive details' but doesn't specify what happens on errors, whether it requires authentication, rate limits, or the format of returned data. For a read operation with no annotation coverage, this leaves significant gaps in understanding how the tool behaves beyond its basic purpose.

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 that efficiently state the tool's purpose and primary use case without unnecessary words. It's front-loaded with the core functionality. However, it could be slightly more structured by explicitly listing key behaviors or constraints.

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 complexity (5 parameters, no output schema, no annotations), the description is minimally adequate. It covers the purpose and scope but lacks details on error handling, data format, or operational constraints. Without an output schema, it should ideally hint at what 'comprehensive details' include, but it doesn't, leaving gaps for an agent to interpret.

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 5 parameters thoroughly. The description adds no specific parameter semantics beyond implying retrieval of 'metadata, ownership, hierarchies, and relationships,' which loosely maps to parameters like 'includeOwners' and 'hierarchyDepth.' This meets the baseline of 3 when schema coverage is high.

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

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

The description clearly states the tool's purpose: 'Retrieve comprehensive details about a specific entity including its metadata, ownership, hierarchies, and relationships.' It specifies the verb ('retrieve') and resource ('entity details') with scope ('comprehensive'). However, it doesn't explicitly differentiate from sibling tools like 'getEntityDescriptor' or 'getTeamDetails' that might retrieve similar information.

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 some usage context by calling this 'the primary method for getting complete information about services, teams, or domains,' which implies it should be used for comprehensive entity details. However, it doesn't explicitly state when to use this versus alternatives like 'listAllEntities' for summaries or 'getEntityDescriptor' for basic info, nor does it mention any prerequisites or 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes the tool as retrieving information, which implies a read-only operation, but does not specify permissions required, rate limits, error conditions, or response format. For a tool with no annotation coverage, this is a significant gap in 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 core purpose and followed by a concise statement of essential use. Every word contributes value without redundancy, making it efficiently structured and easy to parse.

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

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

Given no annotations, no output schema, and incomplete parameter documentation, the description is insufficient. It lacks details on behavioral traits, response format, and full parameter semantics, making it incomplete for a tool that retrieves detailed information with multiple data points.

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%, with the 'context' parameter well-described but 'cid' lacking a description. The tool description does not add meaning beyond the schema, such as explaining what 'cid' represents or providing examples. With partial schema coverage, the description does not compensate for the undocumented parameter, resulting in a baseline score.

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

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

The description clearly states the specific verb ('retrieve') and resource ('detailed information about a specific initiative'), listing key data elements like goals, timeline, affected entities, scorecard targets, and current progress. It distinguishes this tool from sibling tools like 'listInitiatives' by focusing on detailed retrieval of a single initiative rather than listing multiple initiatives.

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

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

The description implies usage for 'understanding initiative scope and tracking achievement of objectives,' which provides some context. However, it does not explicitly state when to use this tool versus alternatives like 'listInitiatives' or 'getScorecard,' nor does it mention prerequisites or exclusions, leaving gaps in 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?

No annotations are provided, so the description carries full burden. It mentions checking for tools but doesn't disclose behavioral traits like what triggers the check, whether it's a read-only operation, what authentication is needed, rate limits, or what 'additional tools' means in practice. The description is too abstract to provide meaningful behavioral context.

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

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

The description is a single sentence that's appropriately concise, but it's not front-loaded with clear purpose. The sentence is somewhat abstract and could be more direct about what the tool does. While efficient, it doesn't maximize clarity in its brevity.

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 abstract purpose, lack of annotations, and presence of an output schema (which isn't described), the description is incomplete. It doesn't explain what 'checking for additional tools' entails, what the output might contain, or how this differs from the many sibling data retrieval tools. The description leaves too much ambiguity for effective use.

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

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

With 0% schema description coverage for the single parameter 'context,' the description doesn't add any parameter-specific information. However, since there's only one optional parameter with a default value, the baseline is 4. The description doesn't compensate for the lack of schema documentation, but the minimal parameter count keeps the score from being lower.

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 vague purpose ('Check for additional tools') without specifying what resource or action is involved. It doesn't distinguish from siblings (which are all data retrieval tools) and reads more like general advice than a tool definition. While it mentions 'specialized capabilities,' it doesn't clarify what this tool actually does operationally.

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 implied usage guidance ('whenever your task might benefit from specialized capabilities') and suggests using it even when existing tools could work as fallbacks. However, it doesn't explicitly state when to use this tool versus the many sibling data retrieval tools, nor does it provide clear exclusions or named alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does an excellent job describing the tool's behavior: it explains the flexible request structure, that multiple resource types can be fetched in one call, that results are combined into a single array with mixed types, and provides detailed response structure. It also includes pagination details and parameter defaults through examples. The only minor gap is it doesn't mention rate limits or authentication requirements.

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

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

The description is well-structured with clear sections (FLEXIBLE REQUEST STRUCTURE, RESPONSE STRUCTURE, EXAMPLES) and uses bullet points effectively. However, it's quite lengthy with detailed examples and could be more concise. Some information (like specific parameter defaults) could potentially be streamlined since they're already in the schema.

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

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

For a complex tool with 7 parameters, nested objects, and no output schema, the description does an excellent job providing context. It explains the request philosophy, response structure, and provides multiple usage examples. The only gap is the lack of output schema, but the description compensates well by detailing the response format. With no annotations, it successfully carries the full explanatory burden.

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 thoroughly. The description adds significant value by explaining the overall request structure philosophy (set one or more fields to fetch multiple resource types), providing concrete examples of how to combine parameters, and clarifying that all results are combined into a single response array. This goes well beyond what the schema provides about individual parameters.

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

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

The description clearly states the tool's purpose: retrieving the current user's owned resources and work items across the Cortex workspace. It specifies the exact resource types (entities, teams, scorecards, PRs, reviews, work items) and distinguishes itself from sibling tools by focusing on user-owned data rather than entity-specific queries like most siblings.

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

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

The description provides clear context for when to use this tool: when you need to fetch user-owned resources of various types. It explains the flexible request structure and gives multiple examples. However, it doesn't explicitly state when NOT to use it or mention specific alternatives among the sibling tools, though the focus on user data implies differentiation.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes what information is returned but does not mention behavioral traits such as whether this is a read-only operation, if it requires authentication, potential rate limits, error conditions, or response format. For a tool with no annotations, this leaves significant gaps in understanding how it behaves.

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 appropriately sized and front-loaded, with two sentences that efficiently convey purpose and usage without unnecessary details. Every sentence adds value, making it concise and well-structured for quick understanding.

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 complexity of retrieving detailed relationship type information, no annotations, no output schema, and moderate schema coverage, the description is incomplete. It covers purpose and usage but lacks details on behavior, parameters, and output, which are essential for effective tool invocation. It meets a minimum viable standard but has clear gaps in providing a full context.

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

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

Schema description coverage is 50%, with one parameter ('context') well-described and the other ('relationshipTypeTag') undocumented. The description does not add meaning beyond the schema; it mentions 'specific relationship type' but does not clarify what 'relationshipTypeTag' is or provide examples. Since schema coverage is moderate, the baseline score of 3 applies, as the description does not compensate for the coverage gap.

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

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

The description clearly states the verb 'Get' and the resource 'complete details of a specific relationship type', specifying what details are included: configuration, rules, source/destination filters, and inheritance settings. It distinguishes from siblings like 'listRelationshipTypes' by focusing on detailed information for a single type rather than listing all types.

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: 'Essential for understanding how entities can be connected and what validation rules apply.' This implies it should be used when detailed relationship type information is needed. However, it does not explicitly state when not to use it or name specific alternatives among siblings, such as 'listRelationshipTypes' for broader overviews.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes what information is retrieved but does not disclose behavioral traits such as whether this is a read-only operation (implied by 'Get'), authentication requirements, rate limits, error conditions, or response format. For a tool with zero annotation coverage, this is a significant gap in 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 appropriately sized and front-loaded, with two concise sentences that directly state the purpose and usage context. Every sentence earns its place by providing essential information without redundancy or unnecessary details.

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

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

Given the complexity (a detailed retrieval tool with 2 parameters) and lack of annotations and output schema, the description is partially complete. It covers the purpose and usage context well, but it does not address behavioral aspects or output details, which are important for an agent to use this tool effectively. A score of 3 reflects adequacy with clear gaps in transparency and output expectations.

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 both parameters ('tag' and 'context') with clear descriptions. The description does not add any meaning beyond what the schema provides, such as explaining the format of 'tag' or how 'context' influences the output. Baseline 3 is appropriate when 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 the specific verb ('Get') and resource ('scorecard'), with detailed scope ('complete details including its configuration, rules, levels, weights, exemption settings, and evaluation criteria'). It distinguishes from sibling tools like 'listScorecards' (which likely lists scorecards) and 'getScorecardNextStepsForEntity' (which focuses on next steps rather than full details).

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

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

The description provides clear context for when to use this tool ('Essential for understanding how services are evaluated and what standards they must meet'), which implies it's for detailed inspection rather than listing or other operations. However, it does not explicitly state when not to use it or name specific alternatives among the 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions the tool 'Shows which rules need to be satisfied' and helps with 'prioritize improvements', it lacks details on permissions required, rate limits, whether it's a read-only operation, or what the output format looks like. For a tool with no annotation coverage, this leaves significant gaps in understanding its 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 appropriately sized and front-loaded, with two concise sentences that directly state the tool's purpose and value. Every sentence earns its place by explaining what the tool does and how it helps users, with zero wasted words 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?

Given no annotations and no output schema, the description provides adequate purpose and usage context but lacks behavioral details (e.g., output format, error handling) and deeper parameter insights. For a tool with 3 parameters and no structured output documentation, it's minimally viable but has clear gaps in 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?

Schema description coverage is 100%, so the schema already documents all three parameters (tag, entityTag, context) with clear descriptions. The description adds no additional parameter semantics beyond what the schema provides, such as explaining how 'tag' relates to 'scorecard' or providing examples. Baseline 3 is appropriate when 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 the tool's purpose with specific verbs ('Get actionable next steps', 'Shows which rules need to be satisfied') and resources ('entity', 'scorecard performance'). It distinguishes from siblings like 'getScorecard' (which likely retrieves scorecard data) and 'listScorecardScores' (which likely lists scores) by focusing on improvement recommendations for a specific entity.

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 ('to improve its scorecard performance', 'prioritize improvements', 'track progress toward compliance goals'). It implies usage when an entity needs guidance on advancing maturity levels. However, it doesn't explicitly state when not to use it or name specific alternatives among siblings, keeping it at a 4.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the output includes 'complete team data' with specific fields, but lacks details on permissions, rate limits, error handling, or whether it's a read-only operation (implied by 'Retrieve' but not explicit). It adds some context on data returned but misses key behavioral traits like auth needs or side effects.

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 efficiently conveys purpose and output scope without redundancy. It's front-loaded with the core action and resource, and every part adds value (e.g., specifying input methods and data inclusions). Minor room for improvement in brevity, but overall concise.

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

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

Given no annotations and no output schema, the description provides basic purpose and output fields, but lacks completeness for a tool with 2 parameters and behavioral unknowns. It covers what the tool does and returns, but doesn't address permissions, errors, or detailed usage context, leaving gaps for an AI 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 100%, so the schema fully documents both parameters ('tagOrId' and 'context'). The description adds no additional parameter semantics beyond what's in the schema (e.g., no extra details on 'tagOrId' formats or 'context' usage). Baseline 3 is appropriate as the schema handles 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 the verb ('Retrieve detailed information') and resource ('about a specific team'), specifying the input method ('by its tag or ID') and output scope ('complete team data including members, slack channels, metadata, and whether it's backed by an identity provider group'). It distinguishes from siblings like 'getEntityDetails' by focusing on teams, but doesn't explicitly contrast with other team-related tools (none listed).

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

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

No explicit guidance on when to use this tool versus alternatives is provided. The description implies usage for retrieving team details, but it doesn't specify prerequisites, exclusions, or compare to siblings like 'getEntityDetails' (which might handle broader entities). The 'context' parameter hints at broader planning but doesn't offer tool-specific usage rules.

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 mentions pagination, search, and filtering capabilities, but lacks details on permissions, rate limits, error handling, or what the response structure looks like. For a tool with 16 parameters and no output schema, this leaves significant behavioral gaps.

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

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

The description is appropriately sized with two sentences that efficiently convey core functionality and a specific usage tip. It's front-loaded with the main purpose and avoids unnecessary repetition, though the second sentence could be more integrated with the first for better flow.

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 (16 parameters, no output schema, no annotations), the description is incomplete. It doesn't explain the return format, pagination behavior beyond mentioning it, or how results are structured. For a list/filter tool with rich filtering options, more context on output and usage constraints is needed.

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 input schema already documents all parameters thoroughly. The description adds marginal value by listing filter types (groups, types, owners, git repositories) and mentioning pagination and search, but doesn't provide additional syntax or format details beyond what the schema specifies. Baseline 3 is appropriate when 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 the tool's purpose: 'List and filter catalog entities' with specific capabilities like pagination, search, and various filters. It distinguishes itself from siblings by mentioning 'teams' as a specific use case, though it doesn't explicitly name alternative tools for different scenarios beyond the team example.

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 some guidance by specifying 'If the client is trying to fetch data for teams, use 'type': 'team' in these APIs,' which implies usage context. However, it doesn't offer explicit when-not-to-use advice or name specific alternatives among the many sibling tools, leaving usage somewhat implied rather than fully articulated.

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 key behavioral traits: pagination support, filtering capabilities (type, start time, end time), and historical data retrieval. However, it doesn't mention rate limits, authentication requirements, error conditions, or what format the returned events will have (especially important since there's no output schema).

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

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

The description is appropriately concise (two sentences) and front-loaded with the core purpose. Every sentence adds value: the first states the main function with key filters, the second adds pagination support and clarifies the historical data use case.

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 complexity (8 parameters, no annotations, no output schema), the description is adequate but has clear gaps. It covers the basic purpose and filtering capabilities but doesn't explain the return format, error handling, or provide complete guidance on when to use versus sibling tools. For a list operation with pagination and filtering, more context would be helpful.

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

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

Schema description coverage is high (88%), so the baseline is 3. The description adds some value by mentioning filtering by 'type and time range' which corresponds to the 'type', 'startTime', and 'endTime' parameters, but doesn't provide additional semantic context beyond what's already in 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's purpose: 'List custom events for an entity' with optional filtering by type and time range. It specifies the resource (custom events) and action (list) but doesn't explicitly distinguish it from similar sibling tools like 'getCustomEventForEntityByUuid' or '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 usage context by mentioning 'retrieve historical event data' and filtering capabilities, but doesn't provide explicit guidance on when to use this tool versus alternatives like 'getCustomEventForEntityByUuid' (which retrieves a single event) or 'getCustomDataForEntity' (which retrieves custom data rather than events).

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the tool lists dependencies and their purposes, but lacks details on permissions required, rate limits, pagination behavior (beyond what the schema implies), error handling, or what the output looks like. For a tool with 6 parameters and no annotations, this leaves significant gaps in understanding how it behaves in practice.

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

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

The description is concise and front-loaded, stating the core purpose in the first sentence and adding context in the second. Both sentences earn their place by clarifying scope and use cases without redundancy. It could be slightly improved by integrating parameter hints more directly, but overall it's efficient 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?

Given the tool's complexity (6 parameters, no annotations, no output schema), the description is incomplete. It doesn't address output format, error conditions, authentication needs, or detailed behavioral traits. While it covers the basic purpose and usage context, it falls short for a tool that likely returns structured dependency data, leaving the agent with insufficient guidance for correct invocation and interpretation.

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%, with parameters like 'callerTag' and 'includeIncoming'/'includeOutgoing' lacking descriptions in the schema. The tool description adds value by clarifying that dependencies include both incoming and outgoing relationships, which relates to 'includeIncoming' and 'includeOutgoing' parameters, but doesn't explain 'callerTag' or other undocumented parameters. It partially compensates for the schema gaps but not fully.

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

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

The description clearly states the tool's purpose: listing all dependencies for an entity, specifying both incoming and outgoing relationships. It distinguishes this from siblings like 'getDependency' (singular) or 'listEntityRelationships' (generic), but doesn't explicitly contrast with 'listEntityDestinationsForRelationshipType' or 'listEntitySourcesForRelationshipType' which might overlap in functionality. The description includes the verb 'list' and resource 'dependencies for an entity' with scope details.

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

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

The description provides implied usage guidelines by stating it's 'essential for understanding service interactions, planning changes, and assessing blast radius,' which suggests contexts like change management or impact analysis. However, it doesn't explicitly state when to use this tool versus alternatives like 'listEntityRelationships' or 'getDependency,' nor does it mention prerequisites or exclusions. The guidance is helpful but not comprehensive.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure but offers none. It doesn't indicate whether this is a read-only operation, whether it requires authentication, what rate limits might apply, what format the output takes, or any pagination behavior beyond what's in the schema. The description is purely generic API marketing language with zero operational 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?

While technically concise (one sentence), the description is under-specified rather than efficiently informative. It wastes its single sentence on generic API branding instead of stating the tool's specific function. The structure fails to front-load useful information, forcing the agent to rely entirely on the tool name for understanding.

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 5 parameters (3 required), no annotations, and no output schema, the description is completely inadequate. It doesn't explain what 'entity descriptors' are, what the tool returns, how results are structured, or when this tool should be preferred over similar listing tools. The agent must guess at the tool's purpose and behavior based solely on the name and parameter schema.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional meaning about parameters beyond what the schema provides. It doesn't explain what 'entity descriptors' are, what the 'types' filter actually filters, or how pagination works in practice. The baseline score of 3 reflects adequate parameter documentation coming entirely from 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 'Cortex Catalog API - Access and manage your service catalog, teams, domains, and resources' is a general API overview that doesn't specify what this particular tool does. It restates the API's broad purpose rather than defining the specific action of 'listEntityDescriptors'. The description fails to distinguish this tool from its many siblings (like listAllEntities, listScorecards, etc.) that also list things.

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 no guidance on when to use this tool versus alternatives. It doesn't mention any specific use cases, prerequisites, or comparisons to sibling tools like listAllEntities or getEntityDescriptor. The agent must infer usage entirely from the tool name and parameters without any contextual help from the description.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic action ('List all destinations') without explaining what 'destinations' means in this context, whether the output is paginated, if there are rate limits, or what permissions are required. For a tool with 5 parameters and no annotations, this leaves significant behavioral gaps.

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

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

The description is extremely concise—two sentences with zero waste. It front-loads the core purpose and follows with a practical usage tip. Every word serves a clear function, 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?

Given the complexity (5 parameters, no annotations, no output schema), the description is incomplete. It doesn't explain what 'destinations' are, how results are structured, or any behavioral traits like error handling. While schema coverage is high, the lack of output schema and annotations means the description should compensate more for context, which it fails to do adequately.

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

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

Schema description coverage is 80%, so the schema already documents most parameters well (e.g., 'depth', 'includeArchived'). The description adds minimal value beyond the schema by implying that 'relationshipTypeTag' is a key input, but it doesn't clarify the semantics of 'tagOrId' or 'context' beyond what's in the schema. Baseline 3 is appropriate given the high schema coverage.

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

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

The description clearly states the tool's purpose: 'List all destinations for a certain relationship type & entity.' It specifies the verb ('List') and resources ('destinations', 'relationship type', 'entity'), making the action clear. However, it doesn't explicitly differentiate from sibling tools like 'listEntitySourcesForRelationshipType' or 'listEntityRelationships', which likely serve related but distinct purposes.

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 explicit guidance on when to use this tool by stating 'Use the listRelationshipTypes tool to find the relevant relationshipTypeTag.' This indicates a prerequisite step, helping the agent understand the workflow. However, it doesn't specify when NOT to use it or mention alternatives like 'listEntitySourcesForRelationshipType' for reverse relationships, leaving some ambiguity.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully states that results are paginated and describes the output format ('all source-destination pairs'), but doesn't mention important behavioral aspects like whether this is a read-only operation, potential rate limits, authentication requirements, or what happens with invalid relationship types. It adds some value but leaves significant gaps.

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

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

The description is efficiently structured in two sentences: the first states the core functionality with key details (scope, pagination, output format), and the second provides usage context. Every element earns its place with no redundant information, making it front-loaded and appropriately sized for the tool's complexity.

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

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

Given the tool's moderate complexity (4 parameters, no output schema, no annotations), the description is adequate but has clear gaps. It covers the core purpose and output format well, but doesn't address behavioral aspects like error conditions, performance characteristics, or how results are ordered. For a tool that queries organizational relationship graphs, more context about limitations or typical use patterns would be helpful.

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

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

The description doesn't explicitly discuss individual parameters, but it provides crucial context that complements the 75% schema coverage. It clarifies that 'relationshipTypeTag' specifies the 'specific relationship type' for filtering, and mentions pagination which aligns with 'pageSize' and 'page' parameters. This adds meaningful semantics beyond the schema's technical descriptions, though it doesn't cover all parameters in detail.

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

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

The description clearly states the verb ('List') and resource ('entity relationships/full graph'), specifies the scope ('for a specific relationship type across the entire organization'), and distinguishes it from siblings by mentioning it returns 'all source-destination pairs' for the complete relationship graph, unlike more specific sibling tools like listEntitySourcesForRelationshipType or listEntityDestinationsForRelationshipType.

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 ('useful for understanding the complete relationship graph and finding all connections of a particular type'), which implicitly suggests using it for broad relationship analysis rather than entity-specific queries. However, it doesn't explicitly state when not to use it or name specific alternatives among the 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 provided, the description carries full burden for behavioral disclosure. While it mentions a prerequisite tool, it doesn't describe what 'sources' means in this context, whether this is a read-only operation, what format the output takes, or any limitations like pagination. The description provides minimal behavioral context beyond the basic 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 extremely concise with just two sentences, both of which earn their place. The first sentence states the core purpose, and the second provides essential prerequisite guidance with zero wasted words.

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 5 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what 'sources' means in this relationship context, what the output format looks like, or how this differs from similar sibling tools. The description leaves too many questions unanswered for proper agent usage.

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

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

Schema description coverage is 80%, so the schema already documents most parameters well. The description adds minimal value beyond the schema - it mentions 'relationshipTypeTag' but doesn't explain what 'sources' means in relation to the parameters. The baseline of 3 is appropriate given the high schema coverage.

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

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

The description clearly states the action ('List all sources') and target ('for a certain relationship type & entity'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from the sibling tool 'listEntityDestinationsForRelationshipType' which appears to be a counterpart for destinations rather than sources.

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 guidance to 'Use the listRelationshipTypes tool to find the relevant relationshipTypeTag,' establishing a prerequisite workflow. It doesn't explicitly state when NOT to use this tool or name alternatives, but the sibling reference provides some contextual awareness.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'optional filters' and viewing purposes, but fails to describe key behaviors: pagination handling (implied by page/pageSize parameters), rate limits, authentication requirements, or what the output format looks like. For a list tool with 5 parameters, this is inadequate.

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 reasonably concise and front-loaded, with the core purpose stated first. However, the second sentence ('View active improvement programs...') could be more tightly integrated or omitted, as it repeats the purpose without adding critical guidance. Overall, it avoids excessive verbosity.

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 lack of annotations and output schema, the description is incomplete. It does not explain the return values, pagination behavior, error conditions, or how the 'context' parameter should be used. For a tool with 5 parameters and no structured output documentation, more contextual information is needed.

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 fully documents all parameters. The description adds minimal value by mentioning 'optional filters for draft and expired initiatives,' which aligns with includeDrafts and includeExpired parameters, but does not provide additional semantics beyond what the schema already states. 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's purpose: 'List all initiatives in the organization with optional filters for draft and expired initiatives.' It specifies the verb ('List'), resource ('initiatives'), and scope ('organization'), but does not explicitly differentiate it from sibling tools like 'listAllEntities' or 'getInitiative'.

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 no guidance on when to use this tool versus alternatives. It mentions 'view active improvement programs, strategic projects, and their current status,' but does not specify prerequisites, compare to siblings, or indicate when not to use it. This leaves the agent without contextual usage direction.

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

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

With no annotations provided, the description carries full burden and delivers comprehensive behavioral information. It details caching requirements, error responses (400, 403), output structure for different views, and query construction metadata. This goes well beyond basic functionality disclosure.

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

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

The description is well-structured with clear sections (USAGE, Query parameters, Full view details, etc.), but contains some redundancy in filter operator listings that could be more concise. Most sentences earn their place by providing essential guidance, though it's slightly verbose in technical details.

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

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

Given the tool's complexity (3 parameters, no annotations, no output schema), the description provides complete context. It explains the tool's purpose, usage workflow, parameter semantics, output structure for different views, error handling, and integration with other tools. No significant gaps remain for agent 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?

With only 33% schema description coverage (only 'context' parameter has description), the description compensates fully by explaining both 'view' and 'key' parameters in detail. It specifies valid values for 'view' ('basic'/'full'), default behavior, and how 'key' supports filtering with multiple values. This adds significant meaning beyond the sparse schema.

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

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

The description clearly states the specific action ('List all available engineering metric definitions') and distinguishes it from sibling tools by explaining its role in a workflow with 'queryPointInTimeMetrics'. It provides a verb+resource+scope that is precise and differentiated.

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

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

The description explicitly states when to use this tool ('BEFORE querying metrics'), provides a step-by-step usage pattern with caching instructions, and names the alternative tool ('queryPointInTimeMetrics'). It gives clear context on when to refresh cached data and distinguishes this from other tools.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions pagination behavior, which is useful, but doesn't describe authentication requirements, rate limits, error conditions, or what the output format looks like. For a read operation tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.

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 reasonably concise with two sentences. The first sentence states the core functionality, and the second provides context about the purpose. There's minimal wasted language, though the second sentence could be more tightly integrated 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?

Given the tool's moderate complexity (list operation with pagination), no annotations, and no output schema, the description is minimally adequate. It covers the basic purpose and mentions pagination, but lacks details about authentication, rate limits, error handling, and output format. For a tool with no structured output documentation, more guidance on what to expect would be helpful.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. The baseline score of 3 reflects adequate coverage through the schema alone, with no additional value from the description.

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

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

The description clearly states the tool's purpose: 'List all available relationship types with pagination' and 'View relationship type configurations to understand what kinds of relationships can be created between entities'. It specifies the verb ('list'), resource ('relationship types'), and scope ('all available'), but doesn't explicitly differentiate from sibling tools like 'getRelationshipTypeDetails' or '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?

The description provides minimal guidance on when to use this tool. It mentions 'to understand what kinds of relationships can be created', which implies usage for discovery or configuration purposes, but offers no explicit when/when-not instructions or alternatives compared to sibling tools. No prerequisites or exclusions are 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'list all scorecards' and filtering, but doesn't describe key behaviors such as pagination (implied by parameters but not stated), rate limits, authentication needs, or what happens with drafts (via the 'showDrafts' parameter). The description adds some context about viewing configurations but lacks operational details.

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 appropriately sized with three sentences that are front-loaded: the first states the core purpose, the second adds context about scorecard configurations, and the third details filtering options. There's minimal waste, though the second sentence could be more directly related to tool usage.

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 complexity (7 parameters, no annotations, no output schema), the description is moderately complete. It covers the purpose and filtering but lacks details on behavioral aspects like pagination, response format, or error handling. Without annotations or output schema, more context on how to interpret results would be beneficial for a higher score.

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

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

Schema description coverage is high at 86%, so the baseline is 3. The description adds value by mentioning filtering by 'groups, entities, and teams,' which aligns with parameters in the schema, but it doesn't provide additional semantics beyond what the schema descriptions already cover (e.g., it doesn't explain the 'context' parameter's purpose or how filtering works in practice).

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

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

The description clearly states the tool's purpose: 'List all scorecards in the organization with optional filtering.' It specifies the resource (scorecards) and action (list), and mentions filtering capabilities. However, it doesn't explicitly differentiate from sibling tools like 'getScorecard' or 'listScorecardScores,' which would be needed for a score of 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 implies usage by mentioning 'optional filtering' and 'supports filtering by groups, entities, and teams to find relevant scorecards,' which suggests when to use this tool for filtered queries. However, it doesn't provide explicit guidance on when to use this tool versus alternatives like 'getScorecard' or 'listScorecardScores,' nor does it mention any exclusions or prerequisites.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions pagination and the type of data returned (rule scores, overall scores), which is helpful. However, it lacks critical details: whether this is a read-only operation, any rate limits, authentication requirements, error conditions, or what happens if the scorecard tag is invalid. For a tool with 5 parameters and no annotations, this leaves significant gaps in understanding its 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 a single, well-structured sentence that efficiently conveys the tool's purpose and output format. It front-loads key information (retrieving scores) and avoids redundancy. However, it could be slightly more concise by integrating usage context, but as-is, it's appropriately sized with zero waste.

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 complexity (5 parameters, no annotations, no output schema), the description is moderately complete. It covers the core purpose and output structure but lacks details on behavioral traits, error handling, and usage guidelines. Without an output schema, it should ideally describe return values more explicitly (e.g., format of scores), but it does mention pagination and score types, which partially compensates.

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 thoroughly. The description adds no additional meaning beyond what the schema provides—it doesn't explain parameter relationships (e.g., how 'tag' identifies the scorecard) or usage nuances. Baseline 3 is appropriate as the schema does the heavy lifting, but the description doesn't compensate with extra insights.

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 scores for entities evaluated by a specific scorecard, specifying it returns paginated results with rule and overall scores. It distinguishes from siblings like 'getScorecard' (which likely returns metadata) and 'listScorecards' (which lists scorecards rather than scores). However, it doesn't explicitly differentiate from 'getScorecardNextStepsForEntity', which might be related but not directly overlapping.

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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a scorecard tag), exclusions, or comparisons to siblings like 'listAllEntities' or 'getScorecardNextStepsForEntity'. The only implied usage is retrieving scorecard scores, but no context for selection among similar 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 carries the full burden of behavioral disclosure. It mentions that the tool returns a 'response from Cortex including answer and metadata,' which gives some insight into output behavior. However, it fails to disclose critical traits like authentication needs, rate limits, error handling, or whether it's read-only or mutative. This leaves significant gaps for an agent to understand how to use it safely and effectively.

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 appropriately sized and front-loaded, starting with the core purpose. The two-sentence structure is efficient, with the second sentence covering returns. However, the inclusion of 'Args:' and 'Returns:' sections adds some redundancy since the input and output schemas already document parameters and returns, slightly reducing conciseness.

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

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

Given that there are no annotations and an output schema exists, the description provides basic context but is incomplete. It covers the purpose and return values (aided by the output schema), but lacks behavioral details, usage guidelines, and full parameter semantics. For a query tool with two parameters and no annotations, this is adequate but leaves clear gaps, making it minimally viable.

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% (only the 'context' parameter has a description). The description adds minimal semantics: it explains that 'query' is 'the question to ask Cortex docs,' which clarifies its purpose beyond the schema's title. However, it doesn't compensate for the lack of schema description for 'query' or provide details on format, constraints, or examples. With partial coverage, the description offers some value but not enough to elevate the score.

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

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

The description clearly states the tool's purpose: 'Query the Cortex knowledge base for answers.' It specifies the verb ('query') and resource ('Cortex knowledge base'), making the action explicit. However, it doesn't differentiate from sibling tools like 'queryPointInTimeMetrics' or other query-related tools, which would require 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 provides no guidance on when to use this tool versus alternatives. It lacks context about prerequisites, exclusions, or comparisons to sibling tools such as 'queryPointInTimeMetrics' or other query functions. The only implied usage is for asking questions to Cortex docs, but no explicit guidelines are 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly describes the tool's behavior: time range limitations (cannot exceed 6 months), caching requirements (cache metadata only, not query results), error responses (400 for validation errors, 403 for feature not enabled), and response structure (lightweight metadata, row data, no heavy schemas). It also warns against guessing attribute names and specifies prerequisites.

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

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

The description is well-structured with clear sections (purpose, prerequisites, important notes, response, errors). While comprehensive, it's appropriately sized for a complex tool with many parameters and no annotations. Every sentence adds value, though it could be slightly more concise in the prerequisites section.

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, no annotations, no output schema), the description provides excellent contextual completeness. It covers purpose, prerequisites, behavioral constraints, error handling, and response format. The detailed workflow guidance compensates for the lack of structured metadata, making it fully usable for an AI agent.

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

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

Schema description coverage is high (93%), so the baseline is 3. The description adds meaningful context beyond the schema: it explains that time range parameters have a 6-month limit, clarifies that metrics require aggregation functions, and implies that filters/groupBy/orderBy should use values from listMetricDefinitions. However, it doesn't detail all 14 parameters individually, keeping it at 4 rather than 5.

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

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

The description clearly states the tool's purpose: 'Execute point-in-time queries for one or more engineering metrics.' It specifies the resource (engineering metrics), verb (execute queries), and scope (point-in-time with batch support and optional comparisons). It distinguishes itself from sibling tools like listMetricDefinitions by focusing on querying actual metric values rather than discovering metadata.

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 explicit, step-by-step prerequisites for using this tool, including when to call listMetricDefinitions (with specific view parameters) and what to cache. It explicitly states when NOT to use it (e.g., 'Do NOT cache point-in-time query results') and provides clear alternatives (use listMetricDefinitions for metadata). The workflow guidance is comprehensive and actionable.

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