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

The description discloses return content and token size (~800 tokens). No annotations provided, but as a read-only metadata tool, the description covers key behavioral aspects. No harmful side effects implied.

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?

Concise: three sentences, front-loaded with purpose, usage, and preference. Every sentence adds useful information without redundancy.

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

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

No output schema, but the description enumerates return components (metadata, provenance, etc.) and mentions token count. Sufficient for a no-parameter info 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?

No parameters exist, so baseline is 4. The description adds value by specifying what the result contains, which compensates for the lack of param details.

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

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

The description clearly states the tool returns structured JSON with specific metadata components (provenance, fingerprint, freshness, security posture). It distinguishes from sibling 'version_info' by noting preference when machine-readable metadata is needed.

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 states when to use: 'verify data currency and coverage before relying on results.' Also provides alternative: 'Prefer this over version_info when you need machine-readable metadata.'

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

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

No annotations are provided, so the description carries full burden. It mentions the premium feature and portal requirement, but lacks details on safety (read-only), error handling, rate limits, or side effects. The description does not contradict any annotations.

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

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

The description is extremely concise with two sentences, no redundant information, and front-loaded purpose. Every sentence provides value.

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

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

No output schema exists, so description should explain return values. It mentions 'change summary and affected framework mappings' but lacks detail on format, pagination, or example. For a tool with 3 params and moderate complexity, it is adequate but not comprehensive.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add meaningful parameter semantics beyond what the schema already provides (control_id pattern, version examples). The premium note is unrelated to parameters.

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

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

The description clearly states the tool shows changes in an SCF control between two releases, with specific output of a change summary and affected framework mappings. It distinguishes itself from siblings like get_control or get_control_history by focusing on diffing specific 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 description implies usage for comparing two SCF releases but does not provide explicit when-to-use or when-not-to-use guidance relative to sibling tools like get_control_history or get_framework_changes. No alternatives are mentioned.

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?

Discloses different content sources (curated summary vs. user copy), attribution/license notice, and error behavior. No annotations exist, so description carries full burden and does well.

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

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

Three sentences, front-loaded with core purpose, each sentence adds unique value. No fluff.

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

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

Given no output schema or annotations, description explains behavior for both source types, error handling, and usage hints. Slightly lacking return format details but acceptable.

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 parameters are well-documented. Description adds context about source types but not deeper semantics. 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?

Clearly states the tool gets a specific clause or section from public or purchased standards, differentiating from siblings like get_control or get_provision.

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 advises using query_standard to discover clause IDs first, and mentions error handling. Does not explicitly state when not to use, but context is clear.

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

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

No annotations are provided, so the description fully covers behavioral traits: it discloses the return values (domain, description, etc.), warns about token sizes (~1000-3000 vs ~200 tokens), and explicitly states that invalid IDs return 'not found'. This is comprehensive transparency for a read-only retrieval tool.

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

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

The description is well-structured with the main purpose first, followed by usage guidance, behavior notes, and parameter details. All sentences add value, though there is slight redundancy in mentioning token sizes twice. It is front-loaded and concise enough, but could be trimmed slightly.

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

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

Given the absence of an output schema, the description adequately explains what the tool returns (domain, description, weight, etc.), covers error behavior ('not found'), and provides token size estimates. Combined with the schema's parameter descriptions, it gives a complete picture for an agent to use the tool effectively.

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

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

While the input schema already provides descriptions for both parameters (control_id with pattern and include_mappings with default/description), the description adds significant meaning: it provides concrete ID examples, explains the token size implications of include_mappings, and reinforces the relationship with search_controls for discovering valid IDs.

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

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

The description clearly states 'Retrieve a specific SCF control by its exact ID' and lists the returned fields (domain, description, weight, PPTDF classification, etc.), with explicit examples of control IDs. It distinguishes itself from sibling tool search_controls by specifying the precondition of knowing the ID.

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

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

The description explicitly tells when to use this tool ('when you already know the control ID') and when not to ('If you don't know the ID, use search_controls first'). It also provides guidance on the include_mappings parameter, advising to set it to false to reduce token usage when only the control description is needed.

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

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

No annotations provided, so description carries full burden. Discloses it returns timeline (read-only) and premium requirement. Does not mention potential data volume, pagination, or any other behavioral traits beyond basic functionality.

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 succinct sentences covering purpose and prerequisite. No wasted words, front-loaded with key action.

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 1-parameter query tool without output schema, description adequately explains what it does and a key prerequisite. Minor gap: lacks mention of return format, but acceptable given simplicity.

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

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

Schema coverage is 100%, with control_id well-described via pattern and description. Description adds minimal extra meaning beyond the schema (e.g., 'SCF control ID' already in 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?

Description clearly states it returns the full version timeline for a specific SCF control, with specific actions (added, modified, removed) across releases. This differentiates it from siblings like get_control or diff_control.

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?

Implied usage for retrieving version history, and mentions premium feature requirement. However, no explicit guidance on when to use this vs alternatives like get_framework_changes or diff_control.

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

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

With no annotations, the description carries full burden. It adds the premium feature access requirement ('requires Ansvar Intelligence Portal'), but does not disclose other behaviors like pagination, sorting, or typical response format.

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

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

Two concise sentences that front-load the purpose and usage, 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?

Given three well-documented parameters and no output schema, the description adequately covers purpose, usage, and access constraints. Could be slightly improved by noting return format or limits beyond the schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no additional meaning beyond what the schema already provides for the three parameters.

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

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

The description clearly states the tool lists 'SCF control changes that affected a specific framework's mappings', providing a specific verb and resource scope that distinguishes it from sibling tools like get_framework_controls and get_control_history.

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

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

The description explicitly says 'Useful for monitoring how framework coverage evolves across releases', giving a clear use case. However, it does not provide when-not-to-use or alternative tools, though the sibling list offers context.

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

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

With no annotations, the description fully discloses behavior: grouping, default parameter values, token impact, cap of 10 per domain with overflow indication, and error response format. No contradictions with annotations (none exist).

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

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

The description is concise yet thorough: a single opening sentence for purpose, then a clear warning, parameter advice, and fallback behavior. Every sentence adds necessary information; no redundancy or fluff.

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

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

Given the complexity (large frameworks, grouping, cap, error handling, token usage) and absence of output schema, the description covers all critical aspects: response structure, edge cases, and performance considerations. It is fully self-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?

While schema coverage is 100%, the description adds significant value: explains the trade-off of include_descriptions (2.5x token increase), states default false, and clarifies that framework key must be valid via list_frameworks. This goes well beyond the schema alone.

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

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

The description clearly states the verb ('Get') and resource ('all SCF controls'), specifies grouping ('grouped by domain'), and implicitly distinguishes from siblings like get_control (single) or search_controls (search). The resource and scope are unambiguous.

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

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

Provides explicit guidance on when to use (for specific framework keys), warns about large frameworks and token usage, advises setting include_descriptions=false by default, and directs to list_frameworks for key discovery. Also describes fallback behavior on invalid framework. The guidelines are comprehensive and actionable.

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

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

With no annotations, the description fully carries the burden. It discloses that results are limited to 10 controls, body text is only the SCF catalog (CC license), and returns a JSON envelope with _citation metadata. No side effects are expected.

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 moderately long but every sentence adds value. It is front-loaded with the main purpose and examples, though could be slightly trimmed without losing clarity.

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

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

Given no output schema, the description explains the return format and limitations. It covers all key behavioral aspects for a lookup tool with 3 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 baseline is 3. The description adds value by providing framework key examples, explaining bare parent ref matching, and clarifying that jurisdiction is ignored.

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

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

The description clearly states it looks up SCF controls by framework provision reference or direct SCF control ID. It provides concrete examples and explains bare parent ref matching. This distinguishes it from sibling tools like get_control or search_controls.

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 examples for various framework keys and explains the jurisdiction parameter is ignored. It doesn't explicitly state when not to use this tool versus alternatives, but the examples make usage clear.

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

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

No annotations provided, but the description discloses return token range (~200-800) and differentiates standard content types. It does not mention side effects or auth needs, but for a read-only list this is sufficient transparency.

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

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

Three sentences, front-loaded with the primary action, no wasted words. Every sentence adds meaningful detail about standard types and token size.

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

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

For a zero-parameter list tool with no output schema, the description fully covers purpose, content types, and expected output size. No gaps for the agent to infer.

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

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

No parameters exist, so baseline is 4. The description adds value by explaining what each listed standard provides beyond what the schema (empty) conveys.

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 explicitly states the tool lists all available standards (SCF, bundled public profiles, purchased standards) and distinguishes the content of each type, providing specific verb and resource scope.

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

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

The description implies the tool is for listing standards and gives context on standard types, but does not explicitly state when to use over alternatives like search_controls or get_clause. However, the simplicity and zero-parameter design make usage clear.

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

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

No annotations provided, so the description carries the full burden. It discloses behavior: returns grouped/list, error on invalid category, and token estimates. It implies read-only, which is appropriate.

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

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

Four sentences with no redundancy. Key information is front-loaded: 'List all 249 supported security frameworks'. Every sentence serves a purpose.

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

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

Despite having no output schema, the description adequately explains what is returned (grouped by category, filtered list, or error with valid categories). No missing details for this low-complexity 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% with a clear description for the parameter. The description adds token size context and error behavior, providing extra value beyond the schema.

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

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

The description clearly states the tool lists security frameworks with optional category filtering. It distinguishes from sibling tools by specifying its role in discovering valid framework keys for get_framework_controls and map_frameworks.

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

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

Provides explicit guidance on when to use with/without category based on token size, and that it's for discovering framework keys. Could explicitly state when not to use it, but the context is clear.

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

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

No annotations provided, but description discloses key behaviors: result cap of 20, filter option for detailed mapping, error response on invalid keys, and typical response token size. Adequate for a read-only mapping 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?

Concise 4-sentence description: first sentence states purpose, second explains output, third gives use case and limitation, fourth provides error and size info. No redundant sentences.

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?

Description explains what the tool returns (satisfied requirements, gaps, 'not found'), typical response size, and error handling. Lacks output schema but enough for an agent to understand the mapping output.

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

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

Schema covers 100% of parameters with descriptions. Description adds value by explaining the relationship between source_control and the result cap, providing usage context beyond schema definitions.

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?

Clearly states the tool maps controls between two frameworks using SCF, specifying it shows satisfied requirements and gaps. Distinguishes from siblings like get_framework_controls that list controls without cross-mapping.

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?

Describes use case (gap analysis, compliance mapping) and provides specific guidance: results capped at 20, use source_control for detailed mapping, and error behavior for invalid keys. Lacks explicit comparison with sibling tools.

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

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

With no annotations, the description carries full burden. It discloses that it returns matching clauses with text snippets, token range (~500-2000), and behavior when standard is not found (returns available IDs). It distinguishes behavior between public profiles and purchased standards, though does not explicitly state it is read-only or mention auth/rate limits.

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

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

The description is four sentences, each adding value. Front-loaded with purpose, then explains distinctions, return behavior, and prerequisite. No redundant or irrelevant content.

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 search tool with 3 params and no output schema, the description covers purpose, parameter context, return format, token size, and error handling. Minor gap: pagination or how limit parameter affects results not explicitly described, but adequate overall.

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% (baseline 3). The description adds meaningful context beyond schema: it explains the two types of standards for the 'standard' parameter, describes the return structure for 'query', and mentions the token range for output, enhancing parameter understanding.

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

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

The description clearly states the tool searches within bundled public framework profiles or purchased standards by keyword, distinguishing between two content types. It specifies it returns matching clauses with text snippets and describes fallback behavior, differentiating from sibling tools like search_controls or get_clause.

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

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

The description explicitly advises using list_available_standards before calling, providing a clear prerequisite. It implies usage context by explaining what it searches (public vs purchased) and what it returns, but does not explicitly exclude cases or mention alternatives.

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

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

No annotations provided, so description carries burden. Discloses return format (text snippets, top framework mappings), token size per result, default limit and total tokens, and 'No controls found' response. Informs token economy. Doesn't discuss rate limits or authentication, but acceptable for a search 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?

Four well-structured sentences, front-loaded with core functionality. Information dense without unnecessary words. Every sentence serves a purpose: action, return, use case, token estimate.

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?

Tool is simple search with one required param. Description covers search scope, return content, filtering, error case, and token budget. Missing details on pagination or query syntax (exact phrase, case sensitivity), but adequate for typical agent use.

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

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

Schema coverage is 100%. Adds value with examples for query, explanation of frameworks parameter referencing list_frameworks, and clarification of limit's token-saving purpose. Goes beyond schema by providing usage hints.

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

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

The description clearly states the tool performs full-text search across all SCF controls by keyword, returning matching controls with snippets and framework mappings. It distinguishes from sibling tools like get_control (single control retrieval) and get_framework_controls (list by framework).

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

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

Provides explicit use case: 'discover controls by topic' with examples. Mentions optional filtering to specific frameworks and suggests using list_frameworks for valid keys. Lacks explicit 'when not to use' or direct comparison to alternatives, but context is clear.

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

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

No annotations provided, so description carries full burden. It mentions the return size (~500 tokens) and that it's a quick overview. Could add error conditions or auth requirements, but for a simple read-only tool this is sufficient.

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

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

Extremely concise with two sentences that front-load the purpose, usage recommendation, and return size. Every sentence adds value.

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

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

With zero parameters and no output schema, the description fully covers what the tool does, what it returns, and how it relates to a sibling tool. No gaps.

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

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

No parameters exist, so baseline is 4. The description adds value by specifying the type of data returned, which is beyond the empty schema.

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

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

The description clearly states the tool retrieves server version, control/framework counts, and top 10 frameworks by coverage. It distinguishes itself from the sibling 'about' tool by specifying it provides a quick overview.

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 advises to use this tool for a quick overview of available data, and recommends the 'about' tool for structured provenance metadata, providing clear when-to-use guidance.

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