Cloud FinOps Skill & MCP

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

With no annotations, the description carries the full burden and does well: it discloses case-insensitive exact matching, AND semantics, the return shape, and the empty-result behavior with hint and valid_values. It omits potential details like pagination or ordering, but the disclosed behavior is meaningful and not just a restatement of the tool's name.

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

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

The description is well-structured: purpose, semantics, examples, args, return contract, and edge-case behavior. Every section earns its place, and code formatting makes it easy to scan.

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

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

For a tool with four optional parameters and no annotations, the description covers filter semantics, parameter values, return shape, and how to distinguish typos from genuine gaps. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 0% and the schema only provides bare nullable string parameters. The description compensates fully by enumerating allowed values for scope, waste_category, and confidence, explaining service exact-match semantics, and clarifying the confidence model with examples.

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

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

The description opens with 'Filter playbooks by their pattern frontmatter,' a specific verb+resource+mechanism statement. This clearly distinguishes find_playbooks from sibling tools like list_playbooks (listing) and get_playbook (single retrieval).

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

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

It states that all filters are optional and combine with AND semantics, and provides concrete examples showing when to use the tool with different filter combinations. It does not explicitly name sibling alternatives or when-not-to-use conditions, so it stops short of a 5.

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

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

The description discloses key behaviors: case-insensitive exact matching, AND semantics, optional filters, and the fact that a no-match response includes hints and valid values. This is thorough given no annotations.

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

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

The description is well-structured: a concise summary, filter semantics, examples, and detailed args. It is verbose but justified given the need to explain multiple optional parameters and behaviors.

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

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

The description covers the return format, filter logic, and edge cases (no matches). It is complete for the tool's complexity and the provided schema, requiring no additional inference.

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

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

The Args section explains each parameter in detail, providing example values and noting they match fcp_ fields. This adds substantial meaning beyond the bare schema, which lacks descriptions or enums.

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: 'Filter references by FinOps Capability/Phase (FCP) frontmatter.' This is specific and distinguishes it from sibling tools like find_playbooks and get_reference.

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 concrete examples of usage and explains that all filters are optional with AND semantics. It does not explicitly contrast with alternatives, but the examples and focus on FCP filtering make the intended use case clear.

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

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

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It reveals the return structure (name/title/content/lines), error behavior (error and suggestions), and optional UI rendering via a resource link. This covers the key behavioral traits beyond a simple read, though it doesn't mention authentication or side effects (which are not expected for a fetch). It is transparent about outcomes and error handling, earning a 4.

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

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

The description is well-structured with a clear main sentence, an Args section, a Returns section, and a note about rendering. It is not overly verbose, but the final note about MCP Apps support is slightly tangential to the core function. Still, every sentence contributes useful context, and the purpose is front-loaded. It is appropriately concise but not perfectly streamlined.

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

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

For a simple get-by-slug tool, the description covers all necessary aspects: the action, parameter source, return structure, error handling, and optional rendering behavior. It accounts for the existence of an output schema (not shown here) by describing the output shape. Given the tool's simplicity and the lack of annotations, this description is complete and self-contained.

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

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

The input schema only defines 'name' as a string with no description (schema coverage 0%). The tool description compensates fully by explaining that 'name' is a playbook slug, giving concrete examples (aws-zombie-nat-gateway, etc.), and directing the caller to list_playbooks for valid slugs. This adds substantial meaning beyond the schema, making the parameter semantics clear and actionable.

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

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

The description clearly states the action: 'Fetch the full markdown content of one playbook by slug.' It specifies the resource (playbook) and the identifier (slug), and distinguishes it from sibling tools like list_playbooks (which lists playbooks) and find_playbooks (which searches). The purpose is unambiguous and specific.

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 saying the slug is 'as returned by list_playbooks', which tells the agent where to obtain the required parameter. It does not explicitly state when not to use this tool or mention alternatives, but the context is clear for a fetch operation. The error-handling suggestions also guide the caller on self-correction, adding some usage guidance.

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

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

With no annotations, the description carries the full burden and does well: it discloses the exact return shape on success and failure, mentions 'full markdown content', and explains that errors include suggestions for self-correction. This goes beyond a simple 'fetch' and gives actionable behavioral detail.

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

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

The description is compact and well-structured, with a one-line summary followed by clear argument and return/error sections. Every sentence provides necessary information without fluff.

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

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

For a single-parameter lookup tool, the description fully covers invocation, expected input, return contract, and error behavior. Even without structured annotations, this is enough for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 0% for the single parameter, but the description fully compensates by defining name as a reference name returned by list_references and providing concrete examples. It adds meaning beyond the bare schema type 'string'.

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 fetches the full markdown content of a single reference by name, using a specific verb ('Fetch') and resource ('reference'). It distinguishes itself from siblings like list_references and find_references by focusing on one named reference's full content.

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

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

It explicitly tells the caller to use names as returned by list_references, providing a clear precondition and context. It does not explicitly enumerate alternatives or when not to use it, but the usage context is clear enough from the description and sibling names.

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 the return format (JSON with 'playbooks' and 'total') and details each entry's fields (name, title, scope, service, waste_category, confidence, lines). It also gives an approximate line count (80-130 lines) for playbooks, adding behavioral context. It does not explicitly state that the operation is read-only or has no side effects, but the verb 'list' implies a safe read operation, and the detailed return structure compensates for the lack of annotations.

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

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

The description is front-loaded with the primary purpose in the first sentence. The second paragraph adds valuable context about what a playbook is (scope, size) and the exact return structure. It uses about 100 words with zero filler, every sentence contributes to understanding the tool's behavior and output. This is a model of 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?

Despite having an output schema (which handles structural details), the description still explains the semantic meaning of the output (field names and their values like confidence levels). It also clarifies the tool's scope ('bundled', 'named-pattern') and provides typical examples. For a simple list tool with no parameters, the description fully covers what an agent needs to know: the purpose, the output shape, and the content context. It is complete.

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

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

The input schema has zero parameters, so there are no parameter semantics to explain. The schema coverage is 100% (empty), and per the rubric, 0 params gives a baseline of 4. The description does not need to add parameter details, and any additional info about query options would be redundant.

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

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

The description opens with 'List every bundled named-pattern playbook,' which is a specific verb (list) + resource (playbooks) with scope ('every bundled'). It further distinguishes from siblings like find_playbooks and get_playbook by explicitly covering all bundled playbooks and providing examples of typical playbook names (e.g., aws-zombie-nat-gateway). This clearly defines the tool's unique purpose.

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

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

'List every bundled' clearly indicates the use case: when you need a complete inventory of all bundled playbooks. The description also implies no filtering or search is involved, differentiating it from find_playbooks which likely searches. It does not explicitly mention when not to use it or alternative scenarios, so it lacks exclusions, but the context is clear enough.

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

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

No annotations are provided, so the description carries the transparency burden. It discloses the return format (a dict with 'references' and 'total') and the fields included in each entry, which goes beyond a bare listing. It does not mention side effects, but for a read-only list operation this is sufficient.

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

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

Two sentences: the first states the purpose and scope, the second details the return structure. No filler, front-loaded, and every sentence adds value.

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

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

For a simple zero-parameter list tool with an output schema, the description covers the essential behavior and return shape. It also clarifies the scope ('every bundled') and metadata included. No obvious gaps for the operation described.

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 tool has zero parameters, so the schema is trivially fully covered. The baseline for 0 parameters is 4; no parameter description is needed or expected.

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

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

Description states 'List every bundled FinOps reference with its FCP metadata', identifying a specific verb (list), resource (references), and scope (every bundled, with FCP metadata). This distinguishes it from siblings like find_references (filtered search) and get_reference (single retrieval).

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

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

The description implies usage when all references are needed, but it does not explicitly mention alternatives or exclusions. It does not warn against using it when a specific reference is needed (e.g., get_reference) or when filtering is required (find_references).

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