api-evangelist

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description goes beyond them by disclosing the shape of the analysis — section-level coverage, per-rule reach, and unmatched rules — which tells the agent what kind of answer to expect. It stops short of stating cost, limits, or whether it runs against a stored estate or the passed document.

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

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

Two sentences, front-loaded with the core verb and resource, no filler. The trailing analogy is compact and clarifying rather than redundant, though it costs a little precision compared to simply naming the input domain.

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

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

For a read-only analytic tool with no output schema, fully documented parameters, and clear annotations, the description supplies enough: what is measured and at what granularity. What an agent might still want — the exact report structure or whether it requires a previously stored estate — is not addressed.

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

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

Schema description coverage is 100%, and both parameters (document, context) are fully documented in the schema, so the baseline is 3. The description adds no format or constraint detail about the document parameter beyond what the schema states.

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

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

The description states a specific verb and resource: 'Measure how much of an API description your governance actually inspects', with three concrete output facets (coverage by section, each rule's reach, rules matching nothing). It is clearly distinguishable from data-retrieval siblings, but it never names or contrasts with the closest analytic siblings like api_scorecard, audit_pipeline, or governance_report, leaving the boundary slightly implicit.

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 'Like test coverage, one altitude up' analogy hints at the mental model but gives no explicit when-to-use condition, no prerequisites, and no guidance on choosing this over api_scorecard or governance_report. An agent must infer applicability from the purpose statement 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the scoring dimensions and the ruleset caveat, but says nothing about the report structure, pass/fail thresholds, or what happens when a document is unscoreable — gaps that matter for a diagnostic tool with no output schema.

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

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

Two tight sentences that front-load the core action and output before the ruleset advice. The second sentence is slightly rhetorical ('a score against rules you never adopted means little') but it carries real guidance, so little is wasted.

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

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

For a read-only scoring tool with annotations carrying the safety profile and no output schema, the description covers the dimensions and the customization path adequately. It leaves the response format and edge-case behavior unstated, which is a minor gap rather than a blocking one.

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 `document` and `context` are already fully documented, which sets the baseline at 3. The description introduces a `ruleset` argument that does not appear anywhere in the input schema, which adds a little semantic color but also creates ambiguity about how it is supplied.

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 (score) and resource (API maturity) plus the exact output shape: a 0-100 number with a letter grade. It also enumerates the scored dimensions (design, governance, documentation, discoverability, agent-readiness, operations), so an agent knows the breadth of the operation without opening the schema. This is well differentiated from narrower siblings like api_coverage or governance_report.

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

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

The description gives one usage cue — supply your own `ruleset` so the score reflects adopted rules — which is a prerequisite-style hint rather than a when-to-use statement. It never says when to pick this over api_coverage, governance_report, or score_reusability, so the selection guidance is only implied.

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=true and openWorldHint=false, so the safety profile is covered. The description adds that the tool reports per-action match results rather than silently transforming, which is useful, but it doesn't describe failure modes, partial matches, or the report shape. Adequate against annotation coverage, 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 action front-loaded and the use case following. Nothing redundant with the title or annotations.

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

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

For a read-only analysis tool with full schema coverage and no output schema, the description covers purpose, outcome, and usage context. It could go further on what the match report contains, but an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so all three parameters (including the unusual 'context' intent field) are already documented in the schema. The description adds no syntax or format detail about document/overlay beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource: applying an OpenAPI Overlay to a document, plus the outcome ('report what each action matched'). No sibling tool overlaps with overlay application, so differentiation is implicit rather than stated. Clear and specific, but it doesn't explicitly route away from related tools like diff_api_versions.

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

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

The second sentence gives a concrete use context ('deprecation and migration choreography without forking the contract'), which tells the agent when this is the right pick. It offers no explicit when-not conditions or named alternatives, keeping it below 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context (an 8-point maturity rubric, prioritized punch-list output), but it does not disclose auth needs, rate limits, or how the rubric is applied, so it goes only modestly beyond the 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?

Two tightly written sentences with no filler; the core purpose is front-loaded and the invocation hint follows. Every clause carries information.

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

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

With no output schema, the description usefully characterizes the return value as a prioritized punch-list, and annotations carry the safety profile. However, it omits when to choose it over sibling scoring/governance tools and leaves the mismatch between its named inputs (`repo`, `files`) and the formal schema unresolved.

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% for the single documented `context` parameter, so the baseline is 3. The description names `repo` and `files` as inputs, which is useful added semantics not present in the schema, but it never explains the schema's actual `context` parameter and leaves the relationship between these undocumented inputs and the formal schema unclear.

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

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

The description states a specific verb and resource ('Score a repository's Spectral CI setup against an 8-point maturity rubric') and names the concrete output ('prioritized punch-list'), which an agent can act on. It does not, however, distinguish itself from closely related siblings like governance_report, govern_estate, or score_reusability, leaving overlap ambiguous.

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

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

The only usage guidance is 'Pass a public `repo` ("owner/name") or `files`', which is invocation syntax rather than when-to-use guidance. There is no statement of prerequisites, when to prefer this over the sibling governance/score tools, or when it should not be used.

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

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

The annotations already establish read-only and closed-world behavior. The description adds useful behavioral context — baseline comparison, fixed counts, warning budget, and burndown — but it never explains the baseline lifecycle or where the baseline is passed in.

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?

It is a single front-loaded sentence focused on the baseline workflow, with little wasted text. The 'PRO —' prefix and dense parenthetical feature list add some marketing noise but do not obscure the main idea.

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

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

With no output schema, the description should explain what is returned and how the baseline is reused. Instead it leaves the call/return lifecycle ambiguous and references a baseline handoff that the input schema does not support.

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 document and context are self-documenting. However, the description implies a 'baseline' value must be passed back even though no baseline parameter exists in the schema, creating a misleading parameter expectation.

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?

It states a specific outcome — snapshot existing violations as a baseline and fail only on new ones — so it is more than a restatement of the name. However, it describes two phases ('snapshot' then 'pass baseline back') without clarifying which phase this call performs, and it does not differentiate itself by naming a sibling tool.

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

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

It gives a clear usage scenario: adopting a ruleset on a legacy API with existing violations, to avoid a wall of red and fail only on new violations. It does not explain when to use validate_api, validate_ruleset, or other validation siblings instead.

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=true and openWorldHint=false, so the safety profile is covered externally. The description adds real behavioral context beyond that: the certificate is tamper-evident, carries a SHA-256 fingerprint, and is re-verifiable by a third party. It still omits whether the certificate is persisted, whether issuance is idempotent, and what happens on failed attestation.

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

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

Two tight sentences with zero filler. The core action and artifact come first, and the re-verification property is placed as supporting detail rather than preamble.

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

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

With no output schema, the description should say more about what the agent receives back (fingerprint field, certificate body) and where the ruleset/profile threshold come from, since they are not parameters. It is adequate for a two-parameter tool but leaves the agent guessing at the return shape and the source of the attestation criteria.

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

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

Schema coverage is 100% and the 'context' parameter is unusually well documented in the schema itself, so the description adds nothing for the two declared parameters. It is also mildly misleading: 'named ruleset' and 'profile threshold' read as inputs, but neither exists in the schema, leaving the agent unsure how those are supplied.

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 (issue/certify), the artifact produced (a tamper-evident governance certificate), and the condition it attests (an API passed a named ruleset at a profile threshold). It is clearly distinguishable from list/search siblings, though it never explicitly names its closest counterpart, verify_certificate, which only appears indirectly via 'anyone re-verify it'.

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

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

Usage is only implied: certifying makes sense once an API has passed a ruleset at a profile threshold, but the description never states that prerequisite, never names verify_certificate or governance_report as the natural next/alternative step, and gives no when-not condition. An agent can infer context but gets no routing 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description confirms the inspection spans both parameters and request/response schemas, but adds nothing on permissions, rate limits, or what perspective (static scan vs runtime) is used.

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, and the resource/scope statement is front-loaded ahead of the usage cue. Nothing is redundant with the title.

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

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

For a read-only classification tool with full annotation coverage and rich parameter docs, the description is nearly sufficient. With no output schema, it only lightly implies the shape of the result (an inventory of labeled fields) rather than describing 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 description coverage is 100%, and the schema itself explains both the document formats accepted and the optional context field in detail. The description adds no parameter-level meaning beyond restating the purpose, 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 ("Inventory") and a precise resource (PII, secret, and sensitive fields), with the scope narrowed to parameters and request/response schemas. It is clearly distinguishable from siblings like validate_api or api_scorecard, though it never names an alternative to contrast against.

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?

"Run this before exposing an API to agents" gives a concrete triggering condition and timing, so an agent knows this is a pre-exposure gating step. It stops short of naming alternatives or stating when NOT to run it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful output context ('runnable', path params filled in, realistic body) but says nothing about snippet count, ordering, or how bodies are derived, so it only modestly exceeds the 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?

One sentence, front-loaded with the verb and output artifacts, and every clause ('runnable', 'path params filled in', 'realistic body') adds information rather than restating the name.

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

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

For a two-parameter read-only generation tool with a fully documented schema and no output schema, the description covers what is produced and in what languages. It stops short of describing the returned structure (e.g., one snippet per operation, grouped by language), which is the only notable gap.

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

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

Schema description coverage is 100% for both parameters (document and context are both fully documented in the schema), so the baseline of 3 applies. The description adds no format or syntax detail for the document parameter beyond what the schema already states.

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 (generate) and a concrete resource (curl, JavaScript, and Python samples) with a scope modifier ('for every operation'), so an agent immediately knows what comes out. It does not, however, name or differentiate itself from plausible siblings like mock_payloads or forge_mcp_tools.

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

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

There is no when-to-use guidance, no statement of when this is preferable to mock_payloads or the other generation tools, and no prerequisites mentioned. Usage must be inferred purely from the fact that it emits code samples.

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=true and openWorldHint=false, so the safety profile is covered. The description adds real semantic context about how to interpret the output (index where 1.0 is exactly typical, values read against a cohort), but says nothing about permissions, data freshness, or pagination. Adequate value over annotations but not rich.

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

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

Two sentences, front-loaded with the core deliverable and followed by a justification of why the dimension view matters. The unexplained 'PRO' prefix is mild noise, but overall the text is efficient and well-ordered.

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

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

With no output schema, the description takes on the burden of describing returns and does so well, enumerating the cohort statistics and the 1.0-typical index. It still omits the set of available dimensions and any relationship to sibling insight tools, which an agent would need for confident selection.

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

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

Schema coverage is 100%, with slug and context both fully documented in the schema, so the baseline is 3. The description adds no syntax or usage detail for either parameter, leaving the schema to carry the full load.

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 concrete resource (a company's investment dimensions) and precisely the derived columns returned (cohort median, mean, max, rank, percentile, index). It is clear what the tool surfaces, but it never distinguishes itself from closely related siblings like insights_dimensions, get_company_insight, or company_peers, so an agent cannot route between them from this text alone.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named despite several dimension/insight siblings existing. The only implicit cue is that a raw score is 'unreadable on its own,' which hints at complementary use but stops short of routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a small note about the nature of the returned content ('weakest dimensions'), but says nothing about auth/tier requirements ('Pro'), rate limits, or the shape of results.

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 short and front-loaded, with no wasted sentences. The unexplained 'Pro' suffix is the only element that costs clarity rather than earning its place.

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

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

No output schema exists, so the description should carry more of the return-value burden for a read tool. It gestures at the return ('weakest investment dimensions') but never defines what a 'dimension' is or how gaps are framed, leaving a gap for an agent acting without a structured output definition.

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

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

Schema description coverage is 100% and the slug parameter is well documented (including the find_company_insights cross-reference), so the schema does the heavy lifting. The description adds no parameter meaning beyond that. Baseline 3.

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

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

Names a specific resource (a company's weakest investment dimensions) and qualifies it with 'where it is thin', so the agent knows it surfaces weaknesses rather than a full profile. It does not, however, distinguish itself from close siblings like company_dimensions, company_whitespace, or company_signals.

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

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

There is no when-to-use guidance, no preconditions, and no named alternative. The trailing 'Pro' hints at some tier gating but is never explained, so the agent gets no routing help against the many company_* siblings.

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=true and openWorldHint=false, so safety is covered; the description adds genuinely new behavior — the fallback basis logic and the fact that the response reports which basis was used, plus what fields come back. It stops short of noting pagination/ordering or how many peers exist by default.

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, no filler, and the comparability rule is front-loaded ahead of the payload description. Every clause carries information an 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?

With no output schema, the description does the work of describing the return shape (signal totals, top dimensions, stated basis), which is the key thing an agent needs. Minor gaps remain around default limit behavior and result ordering, but nothing critical is missing for a read-only lookup.

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

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

Schema description coverage is 100%, so slug, limit, and context are already fully documented in the schema, including the notable detail that context is never used for ranking. The description adds no parameter-level meaning beyond that, which is the baseline 3 case.

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 resource (companies comparable to a given company) plus its selection rule (same sub-sector when data supports it, same industry otherwise) and the payload contents (signal totals, top dimensions). An agent can tell it apart from the other company_* tools by the 'peers' framing, though it never names a sibling to contrast against.

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

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

Usage is implied by the name and the selection rule — you call it when you want comparable companies for a slug — but there is no explicit when-to-use/when-not guidance and no named alternative (e.g. find_related, company_dimensions, find_company_insights) to route between.

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=true and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds useful substance by disclosing the shape of what comes back (per-entity adoption counts plus radar ring). It does not say what 'PRO' access requires, whether results are cohort-scoped or limited in size.

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

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

A single compact sentence that front-loads the identifier and the payload: entity-by-entity adoption plus cohort count and radar ring. Nothing is padded. Minor deduction because terms like 'radar ring' and 'cohort' go undefined and 'PRO' is unexplained.

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

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

With no output schema, the description must carry the return-value burden, and it does sketch the per-entity fields. However it leaves key domain terms ('radar ring', 'cohort', what 'PRO' gates) undefined and says nothing about result size or ordering. Adequate for a read-only per-company lookup, but not fully 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?

Schema description coverage is 100%, so both slug and context are fully documented in the schema, including the slug format and the unusual read-only semantics of context. The description adds nothing about either parameter, so this is the baseline 3 for a schema that 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 names the resource precisely — the company's adopted stack, broken out entity by entity across services, tools and standards, with cohort-adoption counts and a radar ring. An agent can tell it is a per-company adoption-signal read. It does not distinguish itself from close siblings like company_dimensions, company_gaps or find_company_insights, so the sibling-routing credit is missing.

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

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

There is no when-to-use guidance, no condition, and no named alternative. With ~60 siblings, including several company_* tools, the agent gets no signal on why it would pick company_signals over company_dimensions or company_whitespace. The 'PRO' tag hints at premium access but is not an invocation guideline.

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=true and openWorldHint=false, so the safety profile is covered. The description adds two useful facts beyond annotations: results are ranked by peer prevalence and the tool is a 'PRO' (tier-gated) feature. It says nothing about pagination, row shape, or cost, which matters since no output schema exists.

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

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

Two tight sentences, front-loaded with the 'PRO' tier flag and the core definition before the audience note. Nothing is wasted, though the extreme terseness leaves several dimensions thin rather than being genuinely economical.

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

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

With no output schema, the description carries more burden: it never describes what a whitespace row contains or how results are ordered beyond 'ranked by peers'. For a read-only PRO tool with fully documented params this is adequate but not complete.

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

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

Schema description coverage is 100%, so slug, limit, and context are fully documented in the schema itself. The description adds no syntax or format detail beyond it (e.g. it never connects 'ranked by peer count' to the limit parameter), 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?

The description names the specific resource (a 'whitespace' list of what peers run that the company doesn't) and its ranking basis (how many peers carry it), so the agent can tell what it returns. It does not, however, differentiate from near-siblings like company_gaps or company_peers, which an agent could easily confuse with this tool.

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

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

'The opening list for a vendor selling into the account' implies a use context but states no explicit when-to-use, when-not, or named alternative. The agent must infer that this is the entry-point tool rather than, say, company_gaps.

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=true and openWorldHint=false, so the safety profile is covered. The description adds only the shape of what is inspected (deprecated operations plus sunset announcement status), and says nothing about determinism, how 'going quiet' is detected, or behavior on malformed input. Adequate but thin against an already-informative annotation 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?

Two short sentences, front-loaded with the action and scope. The closing line is persuasive framing rather than operational content, but it is brief and does not bury anything important.

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

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

For a read-only analysis tool with no output schema, the description conveys the subject of the report (deprecated operations and their sunset signaling) clearly enough to set expectations. It omits output format and any notion of sorting or grouping, which is a minor gap given the annotation coverage.

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

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

Schema description coverage is 100% and both parameters are documented in the schema itself, including a detailed note that 'context' is never returned or used for ranking. The description adds no parameter meaning beyond that, 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?

The description states a specific verb ('Report') and a tightly scoped resource ('every deprecated operation and whether it actually announces a sunset'), which is narrow enough that an agent can separate it from broad audit siblings like api_coverage or governance_report. It never names or contrasts a sibling explicitly, so it stops short of a 5.

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

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

There is no when-to-use instruction, no prerequisites, and no named alternative among the many governance/audit siblings (api_scorecard, governance_report, diff_api_versions). The second sentence ('The ones that go quiet are the ones that break consumers') is motivation for caring about deprecations, not guidance on when to invoke this tool versus another.

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=true and openWorldHint=false, so safety is covered; the description still adds real behavior beyond that — the exact payload components, the existence of a remediation prompt explaining "what to change when it fires," and the fuzzy-match fallback on unknown ids. It does not describe output format or failure modes beyond the near-miss suggestion.

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

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

Two tight clauses, front-loaded with the verb and resource, then the return contents, then the edge-case behavior. Every phrase earns its place and nothing repeats 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 read-only single-entity lookup with no output schema, the description covers what is returned (naming the sections) and the unknown-id path, which is enough to call it correctly. The remaining gap is sibling disambiguation against the several other rule-related tools.

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

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

Schema coverage is 100% and the `context` parameter carries an unusually thorough description (why you are asking, never used to rank). The description only reinforces "by id" and implies the `rule` value is a rule identifier; it adds no syntax or format detail beyond the schema. Baseline 3 applies when the schema does 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?

Specific verb ("look up") plus resource ("one rule by id") and an enumeration of what comes back: description, severity, given/then, reference, plus a remediation prompt. It is unambiguous what the tool returns, though it never distinguishes itself from neighbors like explain_rule_result or document_ruleset, which plausibly also surface rule 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?

The one usage signal is implicit: use it when you have a rule id, and it will "suggest close matches for an unknown id" — an unstated fallback for lookup by fuzzy name. There is no explicit when-to-use versus explain_rule_result (rule result interpretation) or document_ruleset, so the agent must infer the routing.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description's job is to add context — and it does, disclosing that the result includes catalog rule counts and named profile applicability, which is otherwise unknowable. It stops short of saying how ambiguity (e.g. Swagger 2.0 vs 3.x near-miss) or unrecognized input is reported.

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

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

A single front-loaded sentence with no filler; every clause carries content. The em-dash tail introducing rule counts and profiles is slightly buried but still earns its place.

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

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

With no output schema, the description must carry the return contract, and it only gestures at it (format, rule count, profiles) without shape or failure semantics. For a low-risk read-only detection tool this is close to sufficient, but an agent cannot predict the response structure or what happens on an ambiguous/unknown document.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, so the baseline of 3 applies. The description's format list roughly mirrors what `document` may contain (YAML/JSON string or parsed object) but adds no new syntax, sizing or validation detail beyond the schema.

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

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

Specific verb ("Identify") plus resource ("a document") with a fully enumerated taxonomy of possible outcomes (OpenAPI/Swagger 2.0 vs 3.x, AsyncAPI, Arazzo, JSON Schema, APIs.json, MCP, SKILL.md, Overlay, ruleset). It also states what comes back (catalog rule count, applicable named profiles), which distinguishes it from siblings like validate_api, api_scorecard and api_coverage that act on an already-identified document.

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

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

Usage is only implied: laying out the full format taxonomy signals "call this when the format is unknown", and the `context` parameter's schema text reinforces that it is a diagnostic/intent-capture step. But the description never states when to prefer this over validate_api or api_coverage, nor what to do on an unrecognized document.

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=true and openWorldHint=false, so safety is covered. The description adds genuine behavioral value by disclosing the result taxonomy and the five granularity levels at which changes are classified, which is important given there is no output schema. It stops short of describing edge cases (unresolvable refs, ambiguous version inputs).

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

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

A single dense sentence with the action front-loaded and the scope qualifier trailing. Every clause earns its place; nothing is repeated from the title or annotations.

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

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

For a three-parameter, fully documented, read-only tool with no output schema, the description covers what the tool returns (change classification at multiple granularities). It does not mention input format flexibility (string path/URL vs. object) or result size/ordering, leaving a small gap.

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

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

Schema description coverage is 100%, including the baseline/candidate semantics and aliases, so the schema carries the parameter burden. The description adds no parameter-level detail (e.g., accepted string forms vs. inline objects) beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb (compare/diff) and resource (two OpenAPI versions) plus the exact output taxonomy (breaking, non-breaking, addition) and the granularity levels (path, operation, parameter, request-body, response). No sibling in the list (api_scorecard, validate_api, api_coverage) performs a version diff, so the tool is clearly distinguishable.

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

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

Usage is implied by the name and description — you call it when you have a baseline and a candidate spec to compare — but the description never states prerequisites, when to prefer it over validate_api/api_scorecard, or any exclusions. Minimum viable routing 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral information by spelling out the shape of the returned Markdown (per-rule severity, check, message, remediation), which matters because there is no output schema. It stops short of mentioning failure modes or cost.

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

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

Two tight sentences: the capability and its output come first, the input selection follows. There is no filler or restatement of the title.

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

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

The output is well described, which offsets the missing output schema. But the description's implied `ruleset`/`profile` arguments are absent from the declared schema and `context` is never mentioned in the description, so an agent still has to guess the exact invocation shape for a zero-required-parameter 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 100%, so baseline is 3. The description does add useful semantics by naming the curated `profile` values (owasp, problem-details, fhir, api-authorization), but it also references `ruleset` and `profile` as if they were declared parameters when the schema only formally defines `context`, leaving an agent to infer how those are passed via additionalProperties.

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

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

States a specific verb and resource ("Generate human-readable Markdown documentation for a ruleset") and enumerates the output contents (severity, what it checks, message, fix). This clearly separates it from validate_ruleset, test_ruleset, and describe_rule, which operate on rules rather than producing rendered docs.

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

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

The second sentence tells the agent how to select input ("Pass `ruleset`, or `profile` for a curated one"), which implies the two ways to invoke it. However, it never states when this tool should be preferred over siblings like describe_rule or explain_rule_result, and gives no 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?

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine behavioral value beyond that: it discloses that the return carries two distinct numbers (authoritative count vs. named companies) and that the 'basis difference' is explained, which is the kind of output quirk an agent needs and no schema provides.

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 inversion idea and information-dense. The all-caps 'PRO — THE INVERSION' and the promotional 'exists in no report, bundle or page' are marketing filler, but most sentences earn their place.

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

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

For a read-only query with no output schema, the description covers purpose, the direction of the query, and the two-count return shape, which is most of what an agent needs. It stops short of describing result format or what 'basis difference' means concretely.

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 kind, slug, limit, context and industry. The description adds only the 'broken down by industry' framing that maps to the industry param, and nothing about slug resolution or limit semantics beyond the schema. Baseline 3 is correct.

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 (which companies show demand for a given service, tool or standard) and explicitly frames the direction of the query as the inversion of the other insights tools. An agent can tell it apart from insights_adoption or company_dimensions from the description alone.

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 to reach for it ('the prospecting query — who should I be selling this to') and contrasts it with 'every other insights tool'. It never names a specific sibling to prefer or an exclusion, so routing is inferred rather than explicit.

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

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

Annotations only declare readOnlyHint and openWorldHint=false; the description adds that the explanation includes concrete internals (format matching, `given` matching, `then` checks, verdict) and that it works across owned, catalog, and built-in rules, which tells the agent there is no ownership prerequisite. No mention of limits or failure modes, but with no output schema this enumeration carries real weight.

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: the purpose and payload are front-loaded, and the scope sentence follows. Every clause (formats, given, then, verdict, rule sources) conveys distinct information.

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

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

With no output schema, the description usefully enumerates the report's contents and the rule sources it handles, which is what an agent needs to decide to call it. Minor gaps remain—e.g., what happens if the rule id is unknown or the document fails to parse—but the core calling information is present.

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 all three parameters—including the optional `context` field—are documented in the schema itself. The description adds only that the operation targets a document and a rule, restating what the schema already says; baseline 3 applies.

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

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

States a specific verb (Explain) and precise resource (why a rule did or did not fire on a document), then enumerates exactly what the explanation covers: formats matched, what `given` matched, what `then` checked, and the verdict. The scope sentence (own rules, catalog, built-ins) further separates it from describe_rule and test_ruleset.

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

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

Usage context is implied by the diagnostic framing—an agent will infer it is for debugging an unexpected pass/fail—but there is no explicit when-to-use/when-not guidance and no named alternatives such as describe_rule or test_ruleset. The scope sentence ('Works for your own rules, the catalog, and the built-ins') widens applicability but does not route the agent.

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=true, openWorldHint=false), so the description only needs to add operation detail — and it does, by naming the four output artifacts an agent will get back. It does not describe format or size of those artifacts, but the artifact inventory is meaningful added context beyond the 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?

A single front-loaded sentence with the verb first and the artifact list in the middle; no filler. Slightly dense with the em-dash clause, but every clause carries information an agent can act on.

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

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

No output schema exists, so the description's artifact enumeration is doing real work, and the schema is fully self-documented for both parameters. Nothing required to invoke it correctly is missing, though return shape/size details are left unspecified.

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

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

Schema description coverage is 100% and the schema descriptions are unusually rich (ruleset explains the catalog-default override; context explains its passive, non-ranking role). The description adds nothing about either parameter, so the baseline 3 is correct when the schema carries the full load.

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?

Specific verb (turn/export) and resource (a governance ruleset) with an explicit enumeration of the artifacts produced — AGENTS.md block, system-prompt set, remediation pack, digest. That output list differentiates it from governance_report or generate_agent_descriptor without needing the schema, though no sibling is named directly.

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

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

"so agents follow the rules while authoring, not after linting" gives a clear when-to-use context and implicitly marks the when-not case (post-lint reporting, which other tools like audit_pipeline cover). No explicit alternative tool is named, 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioural content by naming what gets computed (divergence, drift, promotion candidates), but says nothing about how adoption states are resolved, what happens with conflicting severities, or whether 'PRO' implies an entitlement failure mode.

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

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

A single dense sentence, front-loaded with the tier marker and the core verb+resource, followed by the computed outputs. Every clause carries information, though the 'PRO —' prefix competes with the purpose for first position.

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

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

For a read-only analysis tool with no output schema, the description does the necessary work by enumerating the three result categories an agent should expect. Adequate overall; the remaining gap is the absence of any note on input validation or failure behaviour for malformed federation objects.

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 baseline is 3, but the description adds semantics the schema lacks: it enumerates the adoption states (inherit / override / waive / defer / local) that the free-form 'state' field accepts, which is real meaning beyond the schema text. The optional 'context' parameter is not mentioned, keeping it below a 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 gives a specific verb ('model') and resource ('a central baseline ruleset and the domains that adopt it') and enumerates the computed outputs (divergence per rule, drift per domain, promotion candidates). It does not name a sibling, so the agent must infer the boundary against get_org_ruleset, governance_report, or reconcile_waivers from context alone.

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

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

Usage is only implied: the input shape (central + domains with adoptions) signals this is the tool for multi-domain federation modelling, and 'PRO —' flags a tier gate. There is no explicit when-to-use/when-not statement and no pointer to alternatives such as reconcile_waivers for waiver handling or governance_report for reporting.

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=true and openWorldHint=false, so the safety profile is covered. The description usefully discloses the fixed size of the result set (77) and that each area is a subsite with its own catalog, but says nothing about pagination behavior, default result shape, or cost of a call. Modest added value over the 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?

One compact sentence with the resource and its scope front-loaded and no filler. It earns its brevity, though it spends the whole sentence on what the entity is rather than what the call does.

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

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

For a read-only, no-required-param listing tool with fully documented parameters and no output schema, the gaps are minor: the description does not sketch the fields a record returns (slug, title, url) even though the schema exposes a `fields` projection. An agent can still call it correctly.

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

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

Schema description coverage is 100% across all 8 parameters (including enum values for sort and match and per-parameter defaults), so the schema carries the full semantic load. The description adds no parameter information, which is the expected baseline when the schema is this complete.

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 the resource precisely and quantitatively ('The 77 focused topic areas of the network ... each a subsite with its own catalog'), so an agent knows what corpus is being enumerated. It supplies no verb of its own, however, and never contrasts itself with the sibling get_area (single-area retrieval), so the list-vs-fetch distinction is left to the tool name.

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

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

There is no when-to-use guidance, no prerequisite, and no mention of an alternative. Nothing tells the agent to reach for find_areas when it wants to browse or discover areas, versus get_area when it already has a slug.

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=true and openWorldHint=false, so safety is covered. The description adds the per-type corpus distribution and implies a paginated list, but says nothing about result shape, maximum result counts, or ordering behavior beyond what the schema carries.

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

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

A single front-loaded sentence that names the purpose first and then the type facet. The parenthetical counts are dense but informative rather than filler; slightly bulky but nothing is wasted.

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

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

For a read-only search tool with 9 fully documented parameters and a default limit of 25, the description is adequate but thin: it never mentions pagination, result ordering, or what a returned building block contains, and no output schema exists to fill that gap. Enough to call it, not enough to fully predict behavior.

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

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

Schema coverage is 100%, so the schema already documents all nine parameters in detail. The description only reinforces the `type` enum with counts, adding marginal value (knowing which types are large) but no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb (search) and resource (governance building blocks) and enumerates the type facet with result counts, which scopes the tool clearly. It does not explicitly distinguish itself from the singular sibling get_building_block or the other find_* tools, so it falls short of a 5.

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

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

Usage is implied by 'search ... by type', and the type list tells the agent what dimension to filter on, but there is no explicit when-to-use, when-not-to-use, or alternative routing (e.g. versus get_building_block for a known slug). The agent must infer the search-vs-fetch boundary.

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?

Beyond the 'readOnlyHint' annotation, the description adds valuable behavioral context: the tool operates on a specific, curated subset of data (Fortune 1000 + API providers) and includes the ranking criteria ('ranked by technology-readiness signal').

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 highly concise, fitting all necessary information (action, resource, scope, ranking, cost) into a single, efficient sentence without 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?

The description clearly establishes the identity of the profiled companies and the mechanism by which they are presented (ranking/browsing). Given that the schema handles pagination and the annotations handle safety, the description is complete enough for the agent to confidently 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?

Since the schema description coverage is 100%, the schema already provides detailed definitions for all parameters, including `q`. The description does not add unique semantic meaning beyond what the structured schema provides, making baseline 3 appropriate.

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

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

The description uses the specific verb 'Browse' and defines the resource scope clearly ('profiled companies (Fortune 1000 + API providers)'). It also specifies the key sorting mechanism ('ranked by technology-readiness signal').

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

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

The description defines the specific population being browsed (Fortune 1000 + API providers), giving a clear boundary for usage. While it doesn't explicitly name the alternative tool, the use of 'Browse' implies a list/search operation distinct from a single 'Get' operation.

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=true and openWorldHint=false, so safety is covered; the description adds no behavioral context beyond that. It says nothing about pagination behavior, result limits, or what the record shape looks like, which matters for an 8-parameter list tool.

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

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

A single compact sentence with no waste and the entity definition front-loaded. It is efficient, though it spends its one sentence on a definition rather than on the actionable information an 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 an 8-parameter, zero-required, open-ended retrieval tool with no output schema, the description should at minimum say what the tool returns and when to reach for it. It supplies only an entity gloss, leaving routing and return expectations unaddressed.

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 q, page, sort, tags, match, limit, fields, and context in detail. The description contributes no parameter meaning at all, which is the expected baseline-3 outcome 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 defines the resource ('recorded discussions with API practitioners') rather than stating the action the tool performs — there is no verb like find/search/filter, so the agent must infer the operation from the name. It does add useful domain grounding (guest, company, YouTube/SoundCloud links) that helps distinguish conversations from posts, videos, or papers. Overall the purpose is implied rather than stated.

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

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

There is no guidance on when to use this tool versus siblings such as get_conversation (single record) or find_videos/find_posts (adjacent media types). No prerequisites, no exclusions, no query-vs-browse routing. The agent is left to guess the retrieval context entirely.

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=true and openWorldHint=false, so safety is covered. The description adds that results are ranked by company coverage and that access is free, but says nothing about result volume, pagination behavior or what a page of entities looks like beyond the schema's page/limit fields.

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?

It is short and front-loads the resource and ranking rule. The 'left-hand side of the inversion' phrasing is insider jargon that costs a sentence of clarity without much payoff, keeping it from a 5.

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

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

For a read-only browse tool with no output schema and fully documented parameters, the description covers purpose, ordering and the natural follow-up call. It is slightly thin on what the response contains, but annotations carry the safety profile and the schema carries the 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?

Schema description coverage is 100%, so all six parameters (q, kind, page, limit, context, min_companies) are already documented in the schema. The description adds no syntax or filtering nuance beyond that, 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 (browse) and resource (demand-side entity catalog) covering services, tools and standards, plus the ordering rule (ranked by company count). It does not fully separate itself from near-name siblings like find_services, find_tools and find_measured_standards, which an agent might reasonably confuse with this combined catalog.

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 sketches a workflow ('pick an entity here, then call entity_demand to see WHO') and notes the tool is free, which implies when to reach for it. But it never states when NOT to use it, nor how it relates to the many find_* siblings that appear to cover overlapping territory.

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=true and openWorldHint=false, so safety is covered. The description adds useful non-structured context: what the tool actually returns (measured repositories, maturity, governance, coalition) and that it is 'Free' – a pricing/cost signal an agent cannot get from the 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?

Two compact sentences, front-loaded with the resource and its distinguishing trait, followed by the sibling contrast. No filler; the capitalization of MEASURED does useful disambiguating work.

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

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

For a read-only, paginated, no-required-param list tool with a fully documented schema and no output schema, the description is nearly sufficient – it names the data dimensions it returns and its cost profile. Only minor gaps (explicit return shape/pagination guidance) remain, which the schema largely covers.

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 page, limit, and context are fully documented in the schema itself. The description adds no parameter-level detail beyond that, making the baseline 3 correct.

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

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

States a specific verb and resource ('standards bodies API Evangelist has actually MEASURED') plus the concrete dimensions returned (repositories, maturity, governance, coalition). It explicitly distinguishes itself from find_standards, so an agent can route without opening a 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?

Explicitly contrasts with find_standards ('613 catalog entries describing what a standard IS'), giving clear context for when measured data is the right choice over catalog metadata. It stops short of stating hard exclusions or prerequisites, but the when-to-use signal is strong.

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=true and openWorldHint=false, so safety is covered, but the description adds nothing behavioral on top: no note on pagination semantics beyond what the schema says, no statement that results are limited to API Evangelist papers, no mention of how relevance ordering behaves when `q` is supplied.

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

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

A single front-loaded sentence with no wasted words. It is arguably too terse for an eight-parameter tool, but as written every phrase earns its place.

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

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

For an eight-parameter search tool with no output schema, the description does not describe the shape of a returned record (slug/title/url keys are only hinted at inside the `fields` param) or how results are ordered by default. The schema covers inputs well, but an agent gets no picture of the response or the pagination workflow.

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

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

Schema description coverage is 100%, so the baseline is 3. The description contributes no parameter guidance at all, and its own content ('papers ... with outlines') does not map to any of the eight params, so it neither adds nor detracts.

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 the resource concretely and characterizes it ('single-PDF deep dives on one practice or topic, with outlines'), which distinguishes it from find_posts, find_videos and find_tools. It lacks an explicit verb, but 'find_papers' plus the content characterization leaves no ambiguity about what is returned.

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

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

No when-to-use guidance is given: nothing says when to prefer this over find_posts/find_videos, or that get_paper is the follow-up for full content once a slug is found. The agent must infer usage entirely from the name and sibling list.

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=true and openWorldHint=false, so the safety profile is covered. The description usefully adds corpus size and date range, but says nothing about result shape, pagination behavior, or rate limits beyond what the schema's page/limit params imply.

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

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

A single front-loaded sentence with no filler — scope and capabilities come first. It is perhaps too terse for a nine-parameter tool, but nothing is wasted.

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 nine-param search tool with no output schema, the description is minimal: it never indicates what a returned record looks like or how pagination results behave, though the schema covers paging inputs. The main omission is distinguishing this corpus from sibling search tools.

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

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

Schema description coverage is 100%, so all nine parameters are already documented in detail (including enums and defaults). The description's "filter by year or tags" merely echoes two of those parameters and adds no syntax or semantics beyond the schema.

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

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

The description gives a specific verb (search/browse) and resource (API Evangelist stories) with scope (5,100+ stories, 2010–present) and supported filters. It does not, however, distinguish this from near-siblings like search_api_evangelist or find_papers, so an agent must infer which corpus each covers.

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?

"Search or browse ... filter by year or tags" implies the use case but gives no explicit when-to-use versus alternatives, no exclusions, and no routing to siblings such as search_api_evangelist or get_post. Usage is implied 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavior beyond that: results are ranked by shared-tag relevance with rare, specific tags weighted most, and the candidate pool is the whole network rather than a single type — useful for interpreting and trusting the ordering. It omits pagination/return-shape behavior, keeping it off 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?

Two sentences, front-loaded with the trigger and the result, with the ranking mechanism trailing. The quoted 'More like this,' flourish and the open-ended 'and more' add slight slack but cost little.

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?

Read-only tool with no output schema, but the description conveys what comes back (related content across types) and how it is ordered. Combined with the 100%-documented schema and annotations covering the safety profile, an agent has enough to call it correctly; only pagination/return-shape detail is unaddressed.

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%, including a substantive explanation of the context parameter's non-ranking role, so the schema carries the parameter burden. The description restates the type + slug pairing and gestures at the breadth of acceptable types but adds no syntax or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific function (return the most related content for a given type + slug) plus the scope that separates it from the per-type find_* siblings: 'across the whole network' spanning stories, areas, guidance, papers and conversations. An agent can tell it is a cross-type recommendation tool rather than another type-specific lister without opening the schema.

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

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

The trigger condition is clear — 'Given any doc (type + slug)' — and the 'More like this' framing makes the intended use obvious. It does not, however, name an alternative (e.g. find_posts for plain listing) or state when not to use it, so it stops short of full when/when-not 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds content-scope context (what kinds of engagements exist) but says nothing about result volume, pagination, or how a 'service' record differs from a paper/post record — useful behavioral detail it could have carried.

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?

It leads with the content scope, which is good front-loading, and the sibling routing note is valuable. But 'The front door to working with API Evangelist' is pure marketing filler that consumes space without helping an agent decide or invoke.

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

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

For an 8-parameter, no-required-args search tool with 100% schema coverage and no output schema, the description is adequate but thin: it never describes what a returned record contains or how paging/sorting interact at a practical level. The safety profile is left entirely to annotations.

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%, including detailed notes on q, sort, match, and context, so the schema does the heavy lifting. The description adds no syntax or semantics beyond the schema, which is the correct baseline of 3 when coverage is this 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?

It names the resource (services API Evangelist offers) and enumerates the engagement types — API strategy, governance, discovery, evangelism — so an agent knows what records this covers. It also explicitly contrasts with find_solutions for the third-party vendor registry. However, it frames itself as 'the front door to working with API Evangelist,' which is promotional rather than stating the operation (search/listing over service records).

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 parenthetical gives one explicit routing rule: use find_solutions for the third-party vendor registry. That excludes the most confusable sibling. Beyond that single case it offers no guidance on when to prefer this over find_posts, find_tools, or find_conversations, so it stops short of full when/when-not coverage.

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=true and openWorldHint=false, so the safety profile is covered. The description adds useful context — corpus size (740+) and the adoption-based ranking across tracked companies — but says nothing about how ranking behaves when q is empty, result limits, or scope of coverage. 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?

A single front-loaded sentence that wastes no words. It is efficient, though the ellipsis-truncated enumeration ('gateways, portals, testing, monitoring, …') adds little and the sentence reads as a catalog label rather than an actionable tool statement.

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 absent and eight parameters (all documented), the description is functionally sufficient to attempt a call. However, for a search tool that coexists with several similarly named find_* siblings, the lack of routing guidance leaves a real gap for correct tool selection.

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

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

Schema description coverage is 100%, so all eight parameters (q, page, sort, tags, limit, match, fields, context) are already documented in the schema itself. The description adds no parameter-level meaning, 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?

The description clearly identifies the resource pool: a registry of 740+ third-party API services and tools ranked by adoption. It conveys what an agent will find, but never states the operative verb (search/list/filter) nor distinguishes this registry from the sibling find_services and find_tools registries.

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 on when to use find_solutions versus find_services, find_tools, or find_related — all of which could plausibly be chosen for the same discovery intent. There are no exclusions, prerequisites, or selection criteria offered.

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=true and openWorldHint=false, so the safety profile is covered. The description adds scope ('16k+ docs') and restates the count-vs-breadth ranking, but the latter duplicates what the `sort` schema entry already says, and nothing is said about pagination behavior or result 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?

Three short sentences, front-loaded with what the tool returns before the search hint. The closing tagline ('The map of what API Evangelist covers') is positioning rather than instruction, a minor cost but not bloating.

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

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

For a read-only, zero-required-param browse tool with full schema coverage and no output schema, the description covers purpose, scope and filtering adequately. Only the return shape and paging expectations are 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 100% and every parameter, including the unusual `context` field, is documented in-schema. The description only echoes 'Search with q' and the breadth definition, adding no syntax or format detail beyond the schema; baseline 3 applies.

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

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

States a specific verb pair (browse and rank) plus the resource (network tag taxonomy) and quantifies scope ('every subject tag across 16k+ docs'). It reads as distinct from the singular get_tag, though it never names that sibling 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?

'Search with q' implies the filter path, and the sort modes hint at two browsing intents, but there is no stated when-not condition and no routing to get_tag for detail on a specific tag. Usage is inferable rather than spelled out.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful context about the dataset (400+ tools, adoption counts, technology-radar placement), which helps the agent anticipate results, but says nothing about pagination behavior 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?

A single, front-loaded sentence with no filler. It is efficient, though it spends its one sentence characterizing the dataset rather than the operation, so it is well-sized but slightly misdirected.

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

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

For an 8-parameter, no-output-schema tool, the description is thin: it gestures at return content (adoption counts, radar placement) but omits the operation itself, usage context, and anything about result shape. The schema carries the parameter burden, but the description does not fully complete the picture.

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% — all 8 parameters are richly documented in the schema itself (sort semantics, tag matching, pagination, the unusual 'context' param). The description adds no parameter meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description identifies the resource ('the open-source tooling registry — 400+ tools') and hints at return content, but never states the operation (search/list/find). It is a noun phrase describing a dataset rather than a specific verb+resource, leaving the agent to infer from the name that it searches tools. It does not explicitly distinguish itself from siblings like get_tool.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternative. The description never tells the agent when to call find_tools versus get_tool or the other find_* siblings.

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=true and openWorldHint=false, covering the safety profile. The description usefully adds that the corpus is a bounded local library (openWorld=false consistency) searchable over transcripts, but says nothing about pagination, result shape, or ranking behavior beyond the schema's sort notes.

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

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

A single front-loaded sentence with no filler instructions. The clause 'interviews and discussions from across the API space' is mild editorializing, but it does convey content type, so the sentence is 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?

For an all-optional 8-parameter search tool with full schema coverage and no output schema, the description covers the resource adequately. However, given the dense find_* sibling cluster, it omits the when-to-use context that would make selection unambiguous.

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 8 parameters, which sets the baseline at 3. The phrase 'searchable by transcript' loosely signals the free-text scope of q, but the schema's own wording ('title, summary, tags, and body') carries the detail, so the description adds little param-level meaning.

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?

Identifies a specific resource (the API Evangelist video library) and its scope (interviews and discussions from across the API space), with an implied search verb via 'searchable by transcript'. It does not explicitly distinguish itself from sibling find_papers/find_posts/find_conversations, so an agent must infer the difference from the noun alone.

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

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

No when-to-use guidance and no named alternatives. It never tells the agent when to prefer find_videos over find_papers, find_posts, or the broader search_api_evangelist, leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and closed-corpus behavior are covered structurally. The description adds useful framing that the vocabulary is extracted from the API landscape and is large ('thousands'), but says nothing about result shape, pagination limits beyond the schema, or the unusual side-channel role of the `context` parameter.

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 short sentences, front-loaded with the resource definition and closed with the operative filter hint. No filler or redundancy; every clause carries information.

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

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

With nine optional parameters, 100% schema coverage and no output schema, the structured fields do most of the work, so the terse prose is defensible. However, for a tool whose results are records drawn from a large taxonomy, the description never clarifies what a returned record contains or how this aggregate relates to the narrower find_* siblings, leaving a completeness gap.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents all nine parameters thoroughly (sort semantics, tag matching, pagination). The description's only parameter contribution is the category filter, which merely restates an enum already in the schema.

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

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

The description names the resource clearly (an API vocabulary of resources, actions, personas, domains, schemas, tags) and states it is filterable by category, so the agent knows exactly what corpus is behind `find_vocabulary`. It does not distinguish itself from siblings like `find_tags` or `find_entities`, which overlap with the 'tags' and other categories it mentions, leaving some ambiguity about when this aggregate tool wins.

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 closing phrase 'Filter by category' implies the primary retrieval pattern, but there is no explicit when-to-use or when-not-to-use guidance, nor any mention of the sibling find_* tools that cover narrower slices. Usage is inferable but not spelled out.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower, and the description still adds genuine value by disclosing the shape of the result: findings bucketed into code-fixable vs. spec-authoring, with per-generator remediation. What it omits is behavior on ambiguity — whether it reports a confidence, or what happens when no generator fingerprint is recognized.

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

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

A single dense sentence that front-loads the operation and then the diagnostic output. Every clause earns its place except the 'PRO —' marketing prefix, which conveys no actionable information to an agent and slightly delays the verb.

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

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

With no output schema, the description must convey the return shape, and it does: generator identification plus two categorized finding buckets plus per-generator remediation. Combined with complete parameter documentation and read-only annotations, this is nearly sufficient; the only gap is edge-case behavior when a fingerprint cannot be determined.

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

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

Schema description coverage is 100%, so both `document` (accepted formats, string or object) and even the unusual `context` parameter are fully documented in the schema. The description adds nothing about either parameter, so the baseline 3 applies — the schema carries this dimension entirely.

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 — 'identify which OpenAPI generator produced the spec' — and adds the output shape (findings split between code-annotation fixes and spec-authoring fixes). That is far more specific than the name alone and clearly distinct from generic validators or linters in the sibling list. It does not explicitly name the adjacent sibling (detect_format for spec-type detection), keeping it just short of a 5.

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

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

'For a code-first API' is a real qualifying condition that tells the agent when this applies, which is more than nothing. But there is no when-not guidance (e.g., design-first specs), no named alternative, and no statement of prerequisites such as needing the source spec rather than a hosted URL. Usage is only implied.

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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is already given, and the description credits the report contents (resolved, newly fires, breaking changes), which is real added value. However, 'apply it' reads like a mutation and is in tension with readOnlyHint=true — an agent cannot tell whether the overlay is applied to the passed-in document only or persisted. That ambiguity is exactly what a description should resolve when annotations say 'no 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?

Two tightly packed sentences with the outcome front-loaded and no filler. The 'PRO —' prefix is low-cost framing, though the trailing 'Review the overlay before applying it' introduces a workflow step the schema cannot satisfy.

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

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

With no output schema, the description is what tells the agent what comes back, and it does so specifically: what was resolved, what newly fires, and any breaking change. The gaps are the undocumented `rules` selector and the absence of any way to actually preview the overlay before it is applied.

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 both parameters are fully documented in the schema, and the baseline of 3 applies. The description does not add meaning to `document` or `context`, and it references a `rules` input that does not appear in the schema at all, which is mildly confusing rather than helpful.

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 concrete verb chain and resource: propose an OpenAPI Overlay that fixes lint errors, apply it, re-lint, and report. An agent immediately knows this is a generate-and-verify remediation tool. It does not, however, distinguish itself from the sibling apply_overlay or test_ruleset, so the boundary only becomes clear from 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?

Usage is implied rather than stated: you come here when lint errors need fixing, and the phrase 'or the `rules` you name' hints at a targeted variant. There is no explicit when-to-use versus apply_overlay (which takes a pre-built overlay) and no when-not guidance. 'Review the overlay before applying it' is a workflow hint, but there is no dry-run parameter to support it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered by structured data. The description adds the artifact inventory (what gets produced), which is genuinely useful behavioral context, but says nothing about determinism, whether outputs are returned inline or persisted, or size limits on the input document.

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

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

A single front-loaded sentence with the verb and source first, then the outputs. The six-item artifact list is dense but each item earns its place by telling the agent what the call yields; no filler or restatement of the name.

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

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

For a generation tool with no output schema, the description lists the produced artifacts but never explains the return shape (single bundled payload vs. separate files), whether the result is written somewhere, or any constraints on document size. The annotations carry the safety profile, so the gap is moderate rather than severe.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, including the accepted formats (OpenAPI/AsyncAPI/Arazzo/JSON Schema, string or parsed object). The description's phrase 'From an OpenAPI' only partially matches the actual accepted document types, adding no semantics beyond the schema — 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?

The description gives a specific verb ('forge') plus an enumerated set of concrete artifacts (MCP server design, per-operation tools, Agent Skills, enriched OpenAPI, server.json, apis.json properties), so an agent knows exactly what this produces. It does not, however, distinguish itself from near-neighbors like generate_agent_descriptor or export_agent_rules, which also emit agent-facing artifacts.

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

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

There is no guidance on when to invoke this versus the sibling generators (generate_agent_descriptor, export_agent_rules, map_api_experience), nor any prerequisite such as a valid OpenAPI version or required upstream validation. The agent is left to infer usage from the artifact list 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully adds that output includes PII and secret checks via Spectral, but it does not explain how the target API is supplied or whether the emitted artifacts are persisted, which matters given the 'emit' wording against a read-only hint.

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

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

A single front-loaded sentence naming the action and all three emitted artifacts, with no filler. It is efficient, though it spends its words on outputs rather than the input the caller must provide.

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

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

No output schema exists, and the description explicitly enumerates the three artifact types returned plus the PII/secret validation applied, which is exactly the return-value detail the agent otherwise lacks. Given the modest parameter surface and the readOnly annotation, that is sufficient.

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

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

Schema description coverage is 100% and the single 'context' parameter is already thoroughly documented in the schema, so the baseline is 3. The description adds nothing about parameters, and notably never explains where the API spec being gated comes from (additionalProperties: true).

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 gives a specific verb+resource: selecting which operations/fields an API exposes to agents, plus the concrete outputs (Tyk OpenAPI, MCP tool manifest, Spectral ruleset). It is clear what the tool produces, but it does nothing to distinguish itself from overlapping siblings such as forge_mcp_tools, generate_agent_descriptor, or export_agent_rules.

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

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

There is no statement of when to use this tool versus the many adjacent governance/generation siblings, no prerequisites, and no exclusions. The agent must infer the trigger condition from the name alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered structurally. The description usefully discloses the artifact's composition, but is silent on a genuinely important behavior: which API the descriptor is generated for, since the only parameter is an optional, non-ranking context string.

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

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

A single dense sentence with the deliverable front-loaded, followed by the enumerated contents after an em-dash. Every clause carries information; nothing is padded.

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

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

No output schema exists, so the description reasonably carries the burden of describing the artifact, which it does. However, for a generation tool with no required parameters it never explains the scope — which API, from what context — leaving a real gap for correct invocation.

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

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

Schema description coverage is 100% and the context parameter is documented in unusually rich detail in the schema itself, so the baseline is 3. The description adds no additional semantics about the parameter or about how the target API is selected.

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 ("Generate") and concrete artifacts (llms.txt, AGENTS.md), then enumerates the contract's contents (base URL, auth, operation table, deprecated operations, usage rules). An agent can picture the deliverable precisely, though it does not differentiate itself from the similarly-scoped sibling export_agent_rules.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternative. The sibling list contains export_agent_rules and gate_agent_context, which an agent could easily confuse with this tool, and nothing here resolves that choice.

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=true and openWorldHint=false, so the safety profile is covered. The description adds one real behavioral fact — that the related-area graph is resolved for you rather than returned as raw edges — but says nothing about graph depth, expansion limits, or response shape for a tool with no output schema.

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

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

A single compact sentence with no filler, and the core scope (one area, graph resolved) is front-loaded before the usage hint. The trailing "walk the network from here" is mildly informal but still informative.

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 two-parameter read-only getter, the description conveys the essential return shape (area + related-area graph) despite there being no output schema. Missing details like graph depth or pagination are minor at this complexity level.

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

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

Schema coverage is 100% and both parameters are well documented in the schema, including the cross-reference to find_areas for slug format. The description adds nothing about slug or the optional context parameter, so baseline 3 applies.

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

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

"One topic area with its related-area graph resolved" names a specific resource and states the retrieval scope (area plus its related-area graph), which reads clearly against the list-oriented find_areas sibling. However, it never explicitly names find_areas or another sibling, so the differentiation is inferred from the verb rather than stated.

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?

"Walk the network from here" implies the tool is for graph exploration, but there is no explicit when-to-use/when-not guidance or named alternative (e.g. find_related, find_areas). The agent must infer that it fetches one area and its neighbors rather than, say, a filtered list.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the default-vs-inline behavior (summary unless include=["content"]) and hints at a Pro gate, but says nothing about lookup failures or what the summary contains.

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

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

A single sentence with the primary behavior front-loaded and no filler. Every clause carries information.

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

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

For a simple read-only lookup with a fully documented schema and no output schema, the description covers the essential retrieval semantics. The only real gap is error behavior when the slug does not exist.

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

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

Schema description coverage is 100%, so all four parameters — including the unusual 'context' parameter and the include enum — are already documented in the schema. The description only restates the include behavior, adding no new semantics, which lands on the baseline.

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

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

Names a specific verb (get) and resource (building block) plus the identity key (type + slug), which is enough to distinguish it from the plural finder sibling. It stops short of explicitly contrasting itself with find_building_blocks, so it falls just short of a 5.

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

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

Usage is implied by the required type+slug key — you call this when you already know the exact block. There is no explicit statement of when not to use it or a pointer to find_building_blocks for discovery, which is the obvious alternative.

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=true and openWorldHint=false, so safety is covered. The description adds two useful signals beyond that: the payload scope (readiness + stack + history) and the 'Pro' tag, which implies a paid/tier-gated capability worth knowing before calling. It does not cover any error/empty-result 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?

A single front-loaded sentence naming the resource first, then its contents. The trailing 'Pro.' is efficient but cryptic without further context, which keeps it from a perfect score.

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

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

There is no output schema, so the description carries the return-value burden. It lists the three major content blocks, which is the minimum an agent needs, but says nothing about response shape, size, or whether the profile can be partially empty for a given company.

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

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

Schema description coverage is 100%, so both parameters (slug, context) are fully documented in the schema itself, including the provenance of the slug. The description adds no parameter-level detail beyond that, which is the correct baseline 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?

States a specific resource (one company) and enumerates the payload contents: 40-dimension readiness, adopted stack, per-quarter history. The word 'Full' implicitly contrasts with the narrower company_dimensions/company_gaps/company_signals siblings, but no sibling is named outright, so it stops short of a 5.

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

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

No explicit when-to-use, when-not, or alternative is given. The slug parameter's schema notes it comes from find_company_insights, which hints at a two-step find-then-get flow, but that routing lives in the schema, not the description, and no condition distinguishes this from the dimension-specific siblings.

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=true and openWorldHint=false, so the safety profile is covered. The description adds the set of contact channels returned, which is modest extra value, but says nothing about how results are shaped or any constraints. A 3 is appropriate with annotations carrying the load.

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

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

A single front-loaded sentence with no wasted words. It is a fragment rather than a full statement of purpose, which slightly limits clarity, but it is efficiently sized.

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

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

There is no output schema, so the description's enumeration of the returned channels usefully compensates by telling the agent what to expect back. For a simple read-only contact lookup this is essentially complete, though it omits any return-format or freshness detail.

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

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

Schema description coverage is 100% and the single 'context' parameter is documented in detail in the schema. The description adds nothing about how to use the parameter, so baseline 3 applies.

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

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

The description makes clear this returns every channel for reaching API Evangelist, and it enumerates those channels (email, contact form, newsletter, GitHub, social, postal mail). It is written as a noun phrase describing the return content rather than stating an explicit verb, but combined with the name get_contact an agent can tell what it does. It does not distinguish itself against any sibling.

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

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

There is no when-to-use guidance, no conditions, and no pointer to alternatives. Related siblings such as submit_api_evangelist_feedback or search_api_evangelist are not mentioned, so the agent must infer that this is the contact-info lookup.

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?

readOnlyHint=true and openWorldHint=false already tell the agent this is a safe, closed read, so the description is not carrying the safety burden. What it adds — that the default response is a summary and include=["content"] inlines the full writeup — is real behavioral information, but it duplicates schema content rather than extending it.

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

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

A single semicolon-joined sentence with zero filler, and the return-shape clause is front-loaded before the option flag. It is efficient, though the terseness trades away guidance the agent would need.

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

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

With no output schema and full schema coverage on three simple parameters, the description covers what an agent needs: the resource, the default versus expanded response, and the presence of guest/media subfields. Missing sibling routing is a usage-guidelines concern rather than a completeness gap for a single-record lookup.

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

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

Schema description coverage is 100%, so all three parameters (slug, context, include) are already documented in the schema, including the enum and the Pro-gated content mode. The description restates the include behavior rather than adding syntax or edge-case detail, which is the expected baseline 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 names the resource precisely and states what the payload contains — one conversation plus guest detail and media links, with an optional full-body mode. It omits an explicit verb and never names find_conversations as the collection-level sibling, so it stops short of full sibling differentiation.

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

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

There is no when-to-use guidance, no stated precondition, and no routing to an alternative. The only hint of context is indirect: the slug schema description points at find_conversations, which the description itself never leverages.

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=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: 'zero-auth' tells the agent no credentials are needed, and 'static' signals the content is not dynamically generated — useful details not present in structured fields.

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

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

A single compact sentence with no filler, and the distinguishing trait (no-key alternative) lands at the end where it can route the agent. It is efficient, though a leading verb would make it more immediately parseable.

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, no-output-schema tool, the description covers roughly enough: it names the content formats and the auth posture. It still doesn't say what a caller receives structurally (list of feed URLs? feed bodies?) or what 'network site' scopes, leaving a modest gap for an agent deciding to call 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?

There is one optional parameter with 100% schema description coverage, so the schema fully documents 'context'. The description adds no parameter-level meaning beyond what the schema already provides, making the baseline 3 correct.

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 identifies the resource (static machine-readable feeds: JSON, APIs.json) and a distinguishing trait (zero-key alternative), but it is written as a noun phrase with no explicit verb, and 'this API' is a self-referential shorthand that doesn't clearly resolve. An agent can guess it retrieves feeds, but the phrasing is indirect.

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 clause 'the no-key alternative to this API' implies a selection condition — use this when you cannot or do not want to authenticate. However, it names no sibling tools and gives no explicit when-not guidance, leaving the agent to infer the routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the conceptual framing of six editorial lenses, but does not disclose behavior such as pagination, response shape details, or anything beyond what the annotations and schema already imply.

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?

It is a single front-loaded sentence that states the resource and its valid sections without wasted words. The section enumeration is compact and immediately useful.

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

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

For a simple read-only lookup with full schema coverage and readOnly/openWorld annotations, the description is largely complete: it identifies the resource and valid sections. It could mention pagination or how to use the context parameter, but the schema already covers those details.

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 four parameters, including the section enum and pagination controls. The description repeats the section list but adds no syntax, format, or usage meaning beyond the schema.

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

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

The description states the specific resource: one editorial guidance section, and enumerates the six valid section names. It clearly tells an agent what will be returned, but it does not differentiate this tool from similarly named guidance-oriented siblings such as guide_topic.

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

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

The description offers no explicit when-to-use guidance, prerequisites, or alternatives. It implies the tool is for retrieving one guidance section, but an agent gets no help deciding between this tool and related siblings.

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=true and openWorldHint=false, so the safety profile needs no restating. The description's added value is the defaulting semantic — that this is the ruleset governance calls fall back to — which is genuinely useful, but nothing is said about the returned object or any access/tier constraints beyond the 'PRO' marker.

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

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

A single sentence, front-loaded with the verb and resource, with the qualifying clause placed immediately after. 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?

For a simple read-only getter with annotations covering safety and a fully documented single parameter, the description supplies enough to call it correctly. The shape of the returned ruleset is left unstated (no output schema), which is the only notable 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?

There is one optional `context` parameter with 100% schema description coverage that already explains its purpose and that it is never used to rank or included in the answer. The description adds no parameter meaning beyond that, so the schema-derived 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 and resource ('Read your org default ruleset') and defines what that resource is: the fallback used by governance calls without an explicit `ruleset`. It does not explicitly contrast with the many ruleset siblings (set_org_ruleset, describe_rule, validate_ruleset), so it stops short of the top score.

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 defaulting clause implies when this matters — when a governance call has no `ruleset` of its own — but there is no explicit 'use this instead of X when Y' guidance and no exclusions relative to describe_rule, document_ruleset, or validate_ruleset.

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 the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower; the description adds useful context by disclosing that the response is orienting rather than exhaustive — 'counts, entry points, and how to engage.' It does not describe pagination, size, or auth, but for a small read-only orientation endpoint that omission is minor.

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 imperative 'START HERE' is correctly front-loaded, but the middle is a long marketing-style inventory ('sixteen years of API research as searchable stories, 77 topic areas...') whose individual items carry less weight than their length suggests. It is readable but not tight.

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

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

With no output schema, the description does the work of explaining what comes back (counts, entry points, engagement path) and scopes the tool as the network orientation entry point. Combined with annotations covering read-only and closed-world behavior, an agent has enough to call it correctly; only return-format detail is absent.

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?

There is a single optional parameter with 100% schema description coverage, so the schema already fully explains the 'context' field. The description adds nothing about it. Baseline 3 is appropriate when the schema does all 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?

The description states a specific role for the tool — a network overview — and explicitly enumerates what it covers (topic areas, governance building blocks, papers, conversations, consulting services) and what it returns (counts, entry points, how to engage). This clearly distinguishes it from the many get_*/find_* siblings, which return individual entities. It loses a point because the opening 'What the API Evangelist network offers' is more promotional inventory than a crisp verb+resource statement.

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, front-loaded when-to-use directive that tells the agent to call this before exploring the sibling tools. However, it names no alternative (e.g., search_api_evangelist for targeted lookup) and states no when-not condition, so the routing guidance stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds useful context by disclosing that the response includes the full outline and purchase/landing URL, which is meaningful with no output schema present. It stops short of describing error behavior or response structure, so it is not 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?

The description is a single short sentence with no wasted words and front-loads the resource and its returned content. Every part of the sentence earns its place.

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

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

For a simple read-only lookup tool with full input schema coverage and annotations, the description gives enough to understand the call and its general return content. It could be slightly more complete about what 'full outline' means or error behavior for an invalid slug, but the gap is minor.

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

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

Schema description coverage is 100%, and the schema already documents both the required slug and optional context parameters in detail. The description adds no parameter-specific information, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the resource (one paper) and its core payload (full outline and purchase/landing URL), so an agent knows what will be returned. It does not explicitly distinguish this from sibling tools like find_papers, which is the only thing keeping it from 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?

No when-to-use guidance is provided in the description. It never says to use this after find_papers, when to choose it over other get_* tools, or what conditions make it appropriate, leaving the agent to infer entirely from the name and 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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The one behavioral fact added — that omitting include yields the summary while ["content"] yields the full markdown body — is largely a restatement of the schema's own wording, so the description adds little new context (no not-found/error behavior, no rate or auth notes).

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

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

A single front-loaded sentence carrying the identifier format and the one behavioral toggle, with no filler. The payload/behavior split is immediately clear.

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 one-parameter read tool with no output schema, the description tells the agent what it will receive (summary vs full markdown body), which is the key decision point. It leaves unstated what happens on an unknown slug, but that is a minor gap for a tool of this simplicity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description echoes the slug format and the include=["content"] behavior, but both are documented in the schema already, so it adds no meaning beyond it.

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

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

States a specific verb+resource (get one story/post) and pins down the identifier format (YYYY-MM-DD-slug), which is enough to tell it apart from the plural find_posts. It stops short of naming the sibling explicitly, so the differentiation is inferable rather than stated.

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 slug-format hint implies 'use this once you already have a slug from find_posts', but the description never states when to choose this over find_posts or search tools, nor any prerequisites. Usage is only implied, not spelled out.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the meaningful behavioral fact that omitting include yields only the summary while ["content"] inlines the full pitch, but that detail is also carried by the schema's include description, so the added value is modest.

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

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

A single front-loaded sentence with no filler, and both clauses carry information (resource+key, then the include behavior). It is efficient, though terse enough that it leaves gaps the schema must absorb.

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

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

For a simple read-only lookup with full schema coverage and annotations carrying the safety profile, the description covers the essentials. With no output schema, a brief note on what 'full detail' returns would have been the only missing piece.

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% — slug format, the context field's purpose, and the include enum are all documented in the schema itself. The description adds essentially no parameter meaning beyond it, so the baseline 3 applies.

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

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

States a specific verb and resource ('Full detail for one service offering') plus the keying parameter ('by slug'), so an agent can distinguish it from the many find_* siblings that list rather than fetch. It never names a sibling explicitly (e.g. find_services as the slug source), so it stops short of full 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?

Usage is only implied: 'by slug' hints that a prior find_services call supplies the identifier, and the include clause implies when to request the full pitch versus the default summary. There is no explicit when-to-use/when-not statement or named alternative.

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=true and openWorldHint=false, so safety and scope are covered structurally. The description contributes the return payload (website, adoption count) but says nothing about error behavior for a missing slug, rate limits, or auth needs; with annotations carrying the safety profile, this is a moderate addition.

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

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

A single front-loaded sentence that names the resource, the key, and the returned fields with no 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 simple read-only lookup with no output schema, the description discloses the two headline return fields and the annotations cover the read-only nature. It could mention what happens when the slug is not found, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 100% — the slug param documents its format and example ("adobe") and the context param is fully explained in the schema. The description only restates the slug lookup, adding no syntax or format 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?

The description states a specific verb (retrieve one solution) and resource (vendor registry entry) plus scope (by slug), and even previews the payload (website, adoption count). By naming find_solutions as the source of the slug, it cleanly separates this singular lookup from the search sibling.

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

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

It establishes the intended workflow — obtain a slug from find_solutions, then fetch that one entry here — which gives the agent a clear context for use. There are no explicit exclusions or when-not guidance (e.g. what to do for an unknown slug), so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully adds scope ("across the network") and the specific aggregate metrics returned, but says nothing about the PRO gating, cost, or freshness of the statistics.

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

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

A single front-loaded sentence listing the metrics with zero filler. Every clause earns its place by naming a distinct output dimension.

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

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

With no output schema, the description must convey what comes back, and it does list the three metric families. For a zero-required-parameter read-only tool this is close to sufficient, missing only granularity/scope qualifiers such as time window or filtering.

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

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

Schema description coverage is 100% and the single 'context' parameter is documented exhaustively in the schema (purpose, non-use for ranking, failure-diagnosis use). The description adds nothing about it, which is acceptable given the schema carries the full burden.

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 the resource (catalog stats) and enumerates the concrete outputs: per-type counts, stories-per-year, and top tags by reach. That lets an agent distinguish it from most siblings, though it never explicitly contrasts with the plausibly overlapping get_overview or get_timeline.

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

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

There is no when-to-use or when-not-to-use guidance and no alternative tool is named. An agent must guess whether catalog-level aggregates belong here or in get_overview.

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=true, openWorldHint=false), so the bar is lower. The description still adds real value by disclosing the shape and breadth of the payload — per-type counts plus all labeled entities network-wide — which is the only place return scope is explained since no output schema exists.

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 resource and its payload in one sentence, followed by a short actionable filter hint. No padding, though the trailing "Filter with types." fragment is too terse to earn full marks.

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

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

With no output schema, the description takes on the burden of describing the return value and does so adequately (counts plus labeled items). Pagination and page/limit semantics are already in the schema, so nothing essential is missing, though item ordering or truncation behavior is left unstated.

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 slug, page, limit, types, and context are all documented in the schema itself. The description only echoes the types filter ("Filter with types") and adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ("One tag") and enumerates what comes back (per-type counts plus every labeled item across the network), which implicitly separates it from the list-oriented find_tags sibling. It stops short of naming find_tags or otherwise explicitly differentiating, so an agent must infer the contrast.

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?

"Filter with types" gives a lightweight usage hint, and the singular "One tag" implies this is the detail lookup after find_tags. No explicit when-to-use/when-not or named alternative is given, so guidance remains implied rather than stated.

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