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

Annotations already declare readOnlyHint, idempotentHint, and closed-world behavior, so the safety profile is covered. The description adds useful content semantics ('evidence to look for when maturing') but says nothing about ordering, empty-range handling, or size of the returned text; with annotations carrying the safety burden, this is adequate but not rich.

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

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

Two sentences, zero waste, with the primary behavior front-loaded and the sibling disambiguation placed second. Nothing redundant with the name or title.

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

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

An output schema exists, so return values need not be explained; params are fully documented at 100% coverage; annotations cover the read-only/idempotent profile. Combined with the explicit sibling routing, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% and both level parameters are enums with inclusive/exclusive semantics already documented in the schema. The description reinforces the range concept ('between current and target') but adds no format or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource: returns the official maturity assessment text at each level between a current and target level, for one capability. It also explicitly distinguishes itself from the sibling get_maturity_assessment, so an agent can route correctly without opening any schema.

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

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

Names the alternative (get_maturity_assessment) and the exact conditions that select it — one level alone, or all three at once — making this tool's niche (a contiguous range/gap) unambiguous.

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

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

Annotations only declare it is a safe, idempotent read; the description goes well beyond that by disclosing default output size (~1-2k tokens), per-section token costs, the ~7k cost of requesting everything, and the cheaper resource alternative. This is exactly the cost/limit context annotations cannot carry.

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?

Dense but front-loaded, leading with what is returned and the default before the cost breakdown. Every clause about token cost or the resource alternative earns its place, though the single packed paragraph is heavier than strictly necessary.

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

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

An output schema exists, so return values need not be described; the description covers defaults, cost tradeoffs, filtering, and an alternative access path. For a 3-parameter read tool this leaves no meaningful gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it quantifies each `include` section's token cost and explains that `persona` only applies when `activities` is included. That materially helps an agent choose values rather than just knowing the types.

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

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

States a specific verb+resource: fetches one capability's content, and makes the section-selectable behavior explicit. An agent can immediately tell this is a targeted single-capability retrieval rather than a list or search.

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

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

Gives explicit when-to-use guidance (default sections, per-section cost) and an explicit when-not/alternative: prefer the capability resource for the full document. The `persona` filter condition is also stated. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-open-world), but the description adds real behavioral context: the crawler caps the log at 20 refreshes, so the tool covers the full retained history rather than a truncated slice. That retention/cap behavior is exactly the kind of trait annotations cannot express, though it says nothing about ordering or response shape.

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

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

Two front-loaded sentences that lead with the core purpose before qualifying scope and the mirroring resource URI. The long parenthetical is information-dense rather than wasteful, though it slightly buries the retention fact.

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

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

With an output schema present, return-value explanation is unnecessary, and the description covers purpose, retention window, scope caveat, and alternate access path. The one gap is that the only input parameter is undocumented in both the schema and the description.

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 single `limit` parameter has 0% schema description coverage and is never named in the description, so its role (number of entries returned) and default of 5 are left implicit. The description does partially compensate by explaining the 20-entry cap, which gives the schema's maximum=20 meaning, but it never connects that to the `limit` argument itself.

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

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

States a specific verb+resource: what changed between data versions of the server's crawled artifact, scoped to crawl-to-crawl differences in finops.org content. It explicitly disambiguates from a Foundation-published changelog, so the agent knows exactly what this returns and that no sibling tool covers this ground.

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

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

Gives clear context for when this applies (checking crawl-to-crawl diffs in the retained history) and rules out a common misreading ('not a Foundation-published changelog'), plus points to the equivalent resource at finops://framework/meta/changelog. It stops short of an explicit when-to-use/when-not rule against sibling tools, but no sibling offers changelog 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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds useful behavior beyond that: collections are returned whole because they are small, and persona additionally requires a slug. It doesn't discuss pagination or failure modes, but with annotations plus an output schema those are lower priority.

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

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

Three tightly packed sentences that front-load the return type before stating requirements and alternatives. Slightly dense, but every clause carries information; no filler and no repetition.

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

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

With an output schema present, the return format need not be described, and the description covers everything else an agent needs: what is returned, the valid entity types, the required parameter, the persona special case, and the sibling routing. Nothing essential is missing for a two-parameter read 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 only 50% — the enum values carry no per-value documentation there — so the description earns its keep by listing all six valid entity_type values and specifying the conditional requirement of slug for 'persona'. That conditional logic is not present in the schema and materially affects a correct call.

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 exactly what is returned (full rendered markdown) and scopes it to entity types that have no dedicated tool, enumerating them explicitly. It explicitly distinguishes itself from sibling tools by naming get_capability, get_kpis, and get_maturity_model as the correct routes for other entity 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?

It gives both the when ('entity types that have no dedicated tool') and the when-not with concrete alternatives ('For capabilities use get_capability; for KPIs get_kpis; for maturity levels get_maturity_model'). The routing decision is fully determined without opening any schema.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety and side-effect profile is fully covered without description help. The description adds the useful scope fact that the response includes data version and license metadata, but says nothing about freshness guarantees or size of the payload beyond what the output schema supplies.

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

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

Three short sentences, front-loaded with the routing instruction 'Start here' before the content list, and zero filler. Every clause carries information the agent needs.

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

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

For a zero-parameter tool with an output schema and full annotation coverage, the description supplies what the schema cannot: its role as the server entry point and the fact that it teaches navigation of the other tools. It omits any mention of sibling relationships or follow-up actions, which would round it out.

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 zero parameters and 100% schema coverage, the baseline is 4. The explicit 'No parameters.' statement confirms the tool is a no-argument call, adding small but real clarity for an agent deciding whether it needs to gather inputs first.

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 the resource (the framework) and enumerates exactly what is returned: entity counts, data version/crawl date/license, and tool navigation guidance. 'Start here' plus the navigation clause distinguishes it from data-retrieval siblings like search_framework and get_entity, though it never names an alternative explicitly.

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?

'Start here' is an explicit when-to-use instruction that positions the tool as the entry point before the other ten siblings. It gives no when-not-to-use or fallback condition, but for an orientation tool the single directive is clear context.

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

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

Annotations already establish read-only, idempotent, closed-world behavior, so the bar is lower. The description adds genuinely useful context beyond them: that formula and data-source fields exist only for the 44 detailed KPIs (partial data, not an error), that the library is 88 entries, and that unfiltered calls paginate through the entire set.

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

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

Very tight — every clause carries information (data availability, lookup mode, filter logic, pagination scope) and the record contents are front-loaded. The heavy backtick-per-parameter style makes it slightly dense to parse, but there is no filler.

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

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

With an output schema present, return values need no explanation, and annotations cover the safety profile. The description covers data completeness caveats, filter combination, and pagination scope, leaving only the mechanics of `limit`/`cursor` continuation slightly implicit. Adequate for a 5-param, no-required-args read 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 60% and the description fills key gaps: it defines slug as exact-match lookup, explains capability as 'featured on or officially related to', and clarifies featured_only's dual meaning with and without capability. It also explains filter interaction (AND) and the resulting empty result set. `limit` and `cursor` remain undocumented in both places, costing a point.

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

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

States a specific verb (look up / filter / page through) and resource (full KPI records), and enumerates exactly what a record contains: description, formula plus candidate data sources, related capabilities, and featured locations. That level of content specification lets an agent distinguish it from sibling list/detail tools like list_capabilities and get_capability without opening the schema.

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

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

It clearly states the two usage modes — single-record lookup via `slug` versus filtered/paged browsing — and explains the AND combination rule plus the zero-record gotcha when a slug conflicts with a capability filter. It does not, however, point to any sibling tool for adjacent needs (e.g., when to use get_capability instead), so it stops short of explicit alternatives.

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

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

Annotations already establish read-only, idempotent, closed-world behavior, so the safety profile is covered. The description adds genuinely useful context about the nature of the payload — verbatim official published text rather than a normalized/parsed representation — which shapes how an agent should present or trust the output.

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, zero filler, with the most decision-relevant information (what it returns, its verbatim character, the level scoping) front-loaded.

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

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

An output schema exists, so return values need no explanation, and annotations cover the behavioral profile. The description is complete enough for a simple two-parameter read; only a direct pointer to the alternative assessment tool would improve it.

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

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

Schema coverage is 100%: the enum values and the 'omit for all three' behavior are already documented in the input schema. The description repeats the level vocabulary but adds no slug syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

Names a specific verb and resource ('get the official FinOps Framework maturity assessment prose for a capability') and pins the scope precisely (one level or all three). The clause 'not a parsed breakdown' separates it from derived-text siblings like get_maturity_model, so an agent can choose without opening schemas.

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

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

The contrast with 'a parsed breakdown' implies when to prefer this tool over an interpretive one, but no sibling is named and there is no explicit when/when-not guidance relative to get_maturity_model or assess_maturity_path. Usage is inferable rather than stated.

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

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

Annotations already declare readOnly, idempotent, and non-open-world, so safety is covered. The description adds useful scope context beyond the annotations: this is the static, capability-agnostic reference model rather than a scoped assessment, and it hints at the content (per-level characteristics, sample KPIs like allocation coverage targets). It stops short of describing depth or shape of the returned data, but the output schema covers that.

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

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

Two sentences, zero waste: the first defines the resource and its content, the second routes to the sibling. Front-loaded and appropriately sized for a zero-parameter reference lookup.

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

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

With no parameters, an output schema present, and annotations covering the safety profile, the description only needed to establish what the model is and how it differs from the assessment sibling — both done. Nothing an agent needs before calling is missing.

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

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

The tool takes no parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly signals a no-argument lookup rather than implying hidden filters.

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?

Names a specific resource (the official FinOps maturity model) and its structure (Crawl/Walk/Run levels with characteristics and sample goals/KPIs). It also explicitly distinguishes itself from the sibling get_maturity_assessment by declaring itself capability-agnostic.

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

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

Gives an explicit routing rule: use this for the overall model, use get_maturity_assessment for a single capability's per-level assessment. The when-not condition and the alternative tool are both named, leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower. The description still adds real context: the default limit returns the entire list in one call, and the absence of a phase filter is explained as intentional rather than an oversight.

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

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

Three sentences, front-loaded with the resource and its fields, then filters, then the intentional-omission note. The phase sentence earns its place by preventing a false expectation of a phase parameter, though the block is slightly dense.

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

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

An output schema exists, so return values need not be explained, yet the description still names the fields returned. Combined with the filter semantics and the full-list default, an agent has nearly everything needed to call this correctly; only cursor pagination behavior is left implicit.

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 only 50% — limit and cursor have no descriptions — but the description partially compensates by clarifying that the default limit returns the full list, implying pagination is usually unnecessary. The domain and persona examples largely duplicate schema descriptions, so overall value above the schema is moderate.

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

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

States a specific verb (list) and resource (capabilities), gives the exact count (22), and enumerates the returned fields (slug, title, domain, summary). It is clearly distinguishable from the singular sibling get_capability.

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?

Explains that domain and persona filters are optional, gives concrete slug examples, and preempts an obvious wrong assumption by stating there is deliberately no phase filter. It lacks explicit routing to siblings such as search_framework or get_capability, but the usage context is clear.

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

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

Annotations already declare readOnly, idempotent and closed-world, so the safety profile is covered. The description adds behavior beyond them: mutual exclusivity is an error, and allied personas are mapped at group level by the framework with responses stating that explicitly — a real output nuance. It does not cover limits, pagination, or behavior on an unknown slug, which keeps it from a 5.

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

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

Front-loaded by mode (persona, capability, neither), with the error rule stated before the edge-case note about allied personas. Dense with parentheticals but each sentence carries distinct information; no filler.

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

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

With an output schema present, return-shape details are not required, and the description still flags the group-level allied-persona caveat. Both parameters, the mutually exclusive case, and the discovery path are all covered. Only minor gaps remain, such as behavior on an unrecognized slug.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema cannot: each parameter selects a direction of the mapping and changes what is returned (inline activity bullets vs. persona list), and the two are mutually exclusive. That is genuine semantic value on top of the slug 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 names a specific verb+resource and defines exactly what each mode returns: 'every capability that persona works in, WITH that persona's activity bullets inline' versus 'every persona active in it, with activities'. It also covers the zero-argument case ('the full persona index'), so all three behaviors are distinguishable. It stops short of naming sibling tools, so an agent must infer the boundary against get_capability/list_capabilities on its own.

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?

Explicit routing for every mode: persona for 'what does X do across the framework', capability for the reverse direction, neither 'to discover persona slugs'. It also states the negative constraint outright — 'Passing both is an error — pick one direction per call' — which no schema or annotation conveys.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description still adds real context beyond that: results are ranked, each hit returns slug + uri, and those slugs are the keys expected by get_kpis, get_capability, get_maturity_assessment and map_personas. It does not mention pagination/cursor behavior, which the schema handles.

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

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

Front-loaded with the core purpose and the 'don't know a slug' trigger, then a dense but useful routing block. The long parenthetical enumeration of entity types and the multi-tool routing sentence are justified by the breadth of the tool, though they make it run long.

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

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

An output schema exists, yet the description still supplies the highest-value return fact (slug + uri) and how to use it. Combined with the routing guidance, an agent has enough to call the tool and act on results; only pagination semantics are left to the 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 75%, so query, cursor and entity_types are already documented in the schema. The description enumerates the entity types in prose but adds no syntax, format, or default details for limit/cursor/entity_types. Baseline 3 is appropriate when the schema does most of the work.

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

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

States a specific verb+resource ('Ranked keyword search over every entity') and enumerates exactly which entity types are covered, so an agent knows the search spans the whole framework rather than one collection. It is clearly distinguishable from siblings like list_capabilities or get_entity, which return single collections/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?

Explicitly says when to use it ('whenever you don't already know a slug') and names the alternative routes for the other entity types ('read via get_entity(entity_type: …) or the hit's finops:// resource uri'). It then spells out the concrete downstream calls each slug feeds, which is the exact routing decision an agent faces here.

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