infrawise

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

No annotations are provided, so the description carries the full disclosure burden — and it delivers: it documents the matches-per-source-file structure, case-sensitive path-segment matching, and every conditional outcome (ambiguous with accesses withheld, fileMatched: false with availableFiles, triggers absent rather than empty when candidateLambdas exist, unresolvedLambdas with refusal reasons, found: false). It also clarifies that calls read a cached snapshot rather than re-reading AWS, via the maxAgeSeconds schema note.

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

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

The description is front-loaded with purpose and usage before the edge-case documentation, and each conditional behavior clause earns its place given the tool's matching complexity. It is long and partially repeats the file-matching mechanics already present in the schema, but that redundancy is minor against the well-organized, spec-like structure.

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 no annotations, the description must explain both invocation and return semantics, and it does so thoroughly: matches entry shape, ambiguity handling, absent-vs-empty triggers, unresolvedLambdas refusal reasons, availableFiles recovery, and found: false. The one thing left to the schema (maxAgeSeconds freshness semantics) is itself well documented there, so nothing an agent needs to call the tool 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it frames `file` as a way to 'bind the answer to the one file you are editing' and prescribes the retry strategy for ambiguous results, and it attaches found: false semantics to `function`. This actionable interpretation guidance exceeds what the schema's mechanical descriptions provide.

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 ('Analyzes a single named function or Lambda handler') and enumerates the exact analysis dimensions: tables queried, scan vs query, queue publishing, secret access, and trigger event shapes. This clearly distinguishes it from the sibling get_* overview tools, which retrieve resource snapshots rather than function-scoped infrastructure analysis.

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?

'Call this before writing or reviewing a Lambda handler' is an explicit when-to-use with a clear context, and the description scopes the result ('all findings scoped to this function'). However, no alternative tools are named and no when-not-to-use conditions are stated, though the sibling tools are clearly different in purpose.

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

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

The description clearly indicates this is a read operation by saying 'Returns', but it does not disclose the cached snapshot behavior or the dataHealth mechanism. Those details exist in the parameter description but not in the tool description itself. With no annotations, the description carries the burden, and it could be more transparent about data freshness and that AWS is not re-read.

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

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

The description is two sentences that front-load the exact return content and then provide a clear use case. Every word earns its place, with no redundancy or filler.

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

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

With no output schema, the description appropriately lists the return values (APIs, routes, methods, paths, Lambda functions). It also covers when to use the tool and the freshness parameter, making it sufficiently complete for a listing tool of moderate complexity.

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

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

The tool description does not discuss the maxAgeSeconds parameter, but the input schema fully explains it (100% coverage), including its advisory nature and the dataHealth field. Since the schema covers all parameters, the description adds no additional parameter semantics beyond the schema, matching the baseline for high schema coverage.

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

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

The description clearly states the tool returns all API Gateway APIs (REST, HTTP, WebSocket) with detailed route information and Lambda mappings. It uses a specific verb 'Returns' and a well-defined resource, effectively distinguishing it from sibling tools that focus on other AWS services.

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

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

The description provides explicit usage context: call before writing an API handler or when reviewing API surface area and Lambda integration coverage. It does not explicitly mention when not to use or name alternatives, but the guidance is sufficiently clear 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 discloses important behavior: the tool never reads cached data, TLS is required when transit encryption is on (rediss://), and a costSignal note appears for clusters with over 3 nodes. These details go beyond the basic return type and help the agent understand side effects and security implications.

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 focused sentences: return contents, usage timing/security note, data exclusion, and cost note. Every sentence adds distinct value, with essential info front-loaded.

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

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

For a single-parameter read-only overview tool with no output schema, the description provides ample context: what is returned, when to use it, what it excludes, and a behavioral quirk (costSignal). Combined with the schema's maxAgeSeconds explanation, there are no significant 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?

Schema coverage is 100% with a rich description for maxAgeSeconds (advisory behavior, dataHealth, infrawise analyze refresh). The tool description adds no parameter-specific details, but the baseline of 3 applies because the schema handles the parameter semantics effectively.

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 'Returns' with the resource 'all ElastiCache clusters' and enumerates the fields (engine, version, node type, etc.), distinguishing it from sibling get_* overview tools. It clearly identifies the tool's scope and function.

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 explicit use cases ('Call this before writing cache client code... or when reviewing cache availability and security posture') and an exclusion ('Cached data is never read or included'), but does not name alternative sibling tools. This provides strong context without explicit alternatives.

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

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

The description discloses important behavioral traits beyond annotations: the data is a snapshot that is not re-read from AWS on each call, and behaviors are returned in CloudFront match order. It also directs the agent to `infrawise analyze` to refresh data, which is valuable operational context.

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

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

The description is dense and front-loaded, with the main purpose first and usage guidance following. Though the first sentence is long, it packs necessary detail without fluff, earning a 4.

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 thoroughly explains what each distribution's data includes, including origins and cache behaviors with ordering. The freshness semantics are covered by the parameter schema, and usage guidance is present, making this complete for a read-only overview 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?

The tool description does not discuss the sole parameter, maxAgeSeconds, but the schema description covers it 100%, explaining the advisory nature and the dataHealth field. Per the rubric, baseline 3 is appropriate when schema coverage is high.

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

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

The description opens with a specific verb and resource ('Returns all CloudFront distributions') and enumerates the exact fields returned, making the tool's purpose unmistakable. It is clearly differentiated from sibling overview tools by its CloudFront-specific 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 explicitly states when to call the tool: to determine which distribution/behavior serves a path, before changing routing rules, or when reviewing caching/HTTPS. However, it does not mention alternatives or exclusions, so it falls short of the highest bar.

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

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

No annotations are provided, so the description carries the full burden. It discloses that 'Client secret values are never returned,' that SDK auth calls must send SECRET_HASH when the client has a secret, and that infrawise never reads user data. These are meaningful behavioral disclosures beyond the basic read operation, though it does not cover every edge case (e.g., pagination).

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 earning its place. It front-loads the primary output, then exclusions, then usage directives. No wordy or redundant statements; it packs significant detail efficiently.

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 covers the tool's return content, security constraints (secrets never returned), usage context, and data-freshness behavior (via schema). It is sufficiently complete for the tool's purpose, though return structure is not specified.

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

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

The single parameter maxAgeSeconds is fully described in the input schema with detailed guidance on freshness tolerance and when to omit it. The tool description itself adds no additional parameter semantics. With 100% schema coverage, 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 and resource: 'Returns all Cognito user pools with MFA configuration and every app client config' and lists concrete fields (auth flows, OAuth flows/scopes, callback URLs, token validity, client secret presence). This clearly distinguishes it from sibling overview tools like get_lambda_overview or get_s3_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?

Provides explicit when-to-use: 'Call this before writing any Cognito sign-in, sign-up, or token-refresh code' and when-not-to-use: 'Do NOT call to look up users or tokens — infrawise never reads user data.' This gives clear directives without naming alternatives but effectively scopes usage.

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

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

No annotations are provided, so the description carries the full burden. It indicates a read-only operation ('Returns') and lists returned information. However, it does not disclose caching/freshness behavior or that it doesn't re-read AWS on each call; that detail is delegated to the parameter schema. Adequate but not rich behavioral disclosure.

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

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

Two sentences, front-loaded with the essential purpose and data returned. The second sentence provides targeted usage guidance. No filler or redundancy.

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

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

The tool has one optional parameter, no output schema, and no annotations. The description explains what data is returned and when to use it, while the schema documents the param. It is reasonably complete for a read-only overview tool, though it could mention the account-wide scope or data staleness more explicitly in the description itself.

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

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

The schema covers the single parameter (maxAgeSeconds) with a detailed description explaining freshness tolerance and that no AWS re-read occurs. Since schema description coverage is 100%, the tool description itself does not need to add parameter 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?

The description clearly states the verb 'Returns' and the resource 'all EventBridge rules' with specific fields (name, state, schedule expression, event pattern, target Lambda names). This highly specific phrasing distinguishes it from sibling overview tools like get_lambda_overview or get_infra_overview, which cover broader resources.

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

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

It explicitly says 'Call this when checking what schedule or event triggers a Lambda, or when reviewing rule coverage across the account.' This gives clear context for use. It does not mention when not to use it or explicitly name alternatives, but the use-case framing 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?

No annotations are provided, so the description carries the burden. It discloses the scope of returned data (all nodes/edges/findings, including low-severity), which is useful. However, it does not mention performance implications or the fact that data may be stale (though freshness is covered in the parameter schema). This is reasonable for a read-only query 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 two sentences, front-loaded with the main function, and efficiently adds usage guidance and alternatives 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?

The description adequately explains the return content (nodes, edges, findings) and gives usage guidance. No output schema exists, so the description's list of return types partially compensates. However, it could mention the output structure or potential large size, but overall it is sufficiently complete for an agent to decide and call.

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

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

The description does not discuss the maxAgeSeconds parameter, but the schema provides a 100% descriptive coverage with a detailed explanation of freshness and advisory behavior. Per the rubric, baseline is 3 when schema coverage is high.

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

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

The description clearly states that the tool returns every node, edge, and finding, using specific verbs and resource types. It distinguishes itself from get_infra_overview by noting the alternative for 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 specifies when to use: 'when you need to trace relationships across multiple services or require the complete finding set — not just high-severity ones.' Also names the alternative tool for quick overview, effectively giving a when-not-to-use.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the `configured` flag and its implications when false, the structure and meaning of the `dataHealth` block, and the critical interpretation that a non-ok source means 'not read' rather than 'none exist'. It also clarifies that no AWS re-reads occur on tool calls and directs to run `infrawise analyze` to refresh, which is essential behavioral context.

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

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

The description is longer than typical but every sentence earns its place, covering purpose, usage, configuration caveats, and dataHealth structure. It is front-loaded with the primary function, then progressively explains important nuances. The length is justified by the tool's complexity and absence of an output schema, though it could be slightly tighter.

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

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

Given the tool's broad scope, the lack of an output schema, and the absence of annotations, the description is remarkably complete. It covers what is returned, how to interpret edge cases (configured flag, source status), and the behavior of the sole parameter. It also places the tool in context relative to siblings, making it fully self-sufficient for an agent to invoke 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?

The sole parameter maxAgeSeconds has 100% schema description coverage, so the baseline is 3. The tool description references the dataHealth block and withinRequestedAge but adds no new semantics beyond what the schema already provides. Since the schema fully explains the parameter's behavior, the description does not need to compensate.

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

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

The description opens with a specific verb and resource: 'Returns a compact infrastructure snapshot' and enumerates exactly what it includes (service counts, databases, queues, topics, secrets, lambdas, high-severity findings). It also distinguishes itself from the sibling get_graph_summary by saying 'Prefer this over get_graph_summary for quick orientation', making the purpose and scope unmistakable.

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 instructs to 'Call this first at the start of any database or infrastructure task' and contrasts with get_graph_summary: 'use get_graph_summary only when you need every node, edge, and finding in full.' It also notes that this tool's dataHealth.sources covers every source, reinforcing when it is the appropriate 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?

With no annotations provided, the description carries the full transparency burden, and it excels: it states that environment variable values are never returned, that recentThrottles/recentErrors are conditional on runtime signals, that costSignal is a config-level heuristic without billing API involvement, and that unresolvedLink has specific reason values. These disclose important behavioral edges beyond the basic return type.

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 dense but every sentence earns its place: output scope, usage triggers, runtime signal behavior, cost heuristic, and unresolvedLink semantics. It is longer than average, but that length is justified by the number of non-obvious behaviors that need disclosure.

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 must explain what the agent will receive. It covers the return fields, conditional signals, edge cases like unresolvedLink, and the freshness semantics through the schema description. For a read-only overview tool, this is complete enough for an agent 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%, and the single optional parameter maxAgeSeconds is already thoroughly documented in the schema, including advisory semantics and when to pass small values. The tool description itself does not add parameter-specific meaning, 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 opens with a precise verb-resource pairing, 'Returns all Lambda functions,' and enumerates specific returned fields: runtime, memory, timeout, environment variable key names, and event source triggers. It also distinguishes itself from analyze_function by noting it provides trigger event shapes 'without running analyze_function.' This makes the tool's scope immediately identifiable.

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 explicit when-to-use guidance: auditing Lambda configuration for default memory or high timeouts, and retrieving trigger event shapes without invoking analyze_function. It names a concrete sibling alternative and the condition that favors this tool, giving an agent clear routing information.

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

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

With no annotations, the description carries the transparency burden. It reveals that only summaries are returned, not raw logs, and that the logGroup filter matches by substring. However, it does not explicitly state read-only behavior or mention caching, though the schema param description covers data freshness. Overall, good disclosure beyond the name.

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

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

The description is three sentences, front-loaded with the core function, then a limitation, then usage and filter guidance. No wasted words; every sentence adds 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?

The description covers the return payload (pattern counts/frequencies), the key limitation (no raw messages), the optional filter, and the typical use cases. It lacks explicit mention of data freshness or caching, but that is covered in the schema for maxAgeSeconds. For a read tool with only two parameters, this is quite 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 coverage is 100%, so the parameters are already well-documented. The description adds value by specifying that the logGroup filter matches by name substring, which is not in the schema. It does not discuss maxAgeSeconds, but the schema provides a detailed description there. Thus, the description supplements the schema meaningfully.

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 recent error pattern summaries from CloudWatch log groups, with counts and frequencies grouped by log group. It also specifies a key limitation (raw log messages are never returned), which distinguishes it from other get_* tools and clarifies its exact 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?

Explicit usage guidance is provided: 'Call this when investigating errors or identifying log groups with no retention policy.' It also implies a when-not by stating raw log messages are not returned, steering agents away for raw message retrieval. This is strong contextual 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?

The description discloses a key behavior: 'Parameter values are never returned,' which clarifies output boundaries. However, it does not mention that data may be cached or not re-read from AWS; this is only found in the maxAgeSeconds parameter description, not the main description. Given no annotations, there is a burden on the description to disclose such traits, so this is a notable gap.

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

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

The description is two sentences that front-load the core purpose and immediately add a usage directive. No filler or redundant information; every sentence contributes value.

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

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

For a simple overview tool with one optional parameter and no output schema, the description explains what is returned (all parameters, types, tiers) and what is not (values). The parameter schema covers freshness semantics. It could be more complete about the return format, but the tool is straightforward and the provided details are 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?

The input schema has 100% description coverage for maxAgeSeconds, so the schema fully explains the parameter. The tool description adds no parameter-specific meaning beyond what the schema already provides, matching the baseline for full schema coverage.

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

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

The description clearly states the tool returns all SSM Parameter Store parameters with type and tier, using a specific verb ('Returns') and resource ('SSM Parameter Store parameters'). It distinguishes itself from sibling tools like get_secrets_overview by focusing on parameter store metadata.

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

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

It explicitly says 'Call this when checking which config parameters exist for a service or verifying parameter types,' giving clear use cases. It does not explicitly state when not to use it or mention alternatives, but the focused purpose makes usage clear enough.

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

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

With no annotations, the description carries the full transparency burden. It discloses important behaviors: FIFO queues require MessageGroupId on SendMessage, and oldestMessageAgeSec comes from CloudWatch when runtime signals are enabled. It does not explicitly state whether data is live or cached (that appears in the parameter schema), but the core behavioral traits are covered.

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 three dense sentences with no filler. The first sentence lists return fields, the second covers the FIFO constraint, and the third bundles usage scenarios, an alternative tool, and a best-practice ratio. Each 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 read-only list tool with no output schema, it is highly complete: it enumerates returned attributes, names concrete use cases, provides a tuning guideline (6× Lambda timeout), points to a lighter alternative, and notes a conditional data-source behavior. Nothing essential 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 coverage is 100% — the only parameter (maxAgeSeconds) is thoroughly described in the input schema. The description text itself does not discuss parameters, so it adds no param semantics beyond structured data. 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 opens with a specific verb and resource: 'Returns all SQS queues with DLQ presence, encryption status, FIFO type (isFifo), visibility timeout, approximate message count, and retention days.' This clearly distinguishes it from siblings by naming exact attributes and explicitly differentiating from get_infra_overview for queue counts.

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 call it: 'reviewing messaging architecture, investigating a message backlog, checking DLQ coverage, or verifying visibility timeout is set correctly relative to Lambda timeout.' It also points to an alternative: 'Use get_infra_overview for a quick queue count only.' This is exemplary 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It usefully states that object contents are never included, and the 'Returns' phrasing implies a read operation. However, it does not mention potential side effects, data freshness, authentication requirements, or operational caveats—though the parameter schema covers caching behavior, the tool description itself lacks full 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 with no wasted words. The main purpose is front-loaded, followed by explicit usage guidance and a clear exclusion. The structure is efficient and scannable.

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 overview tool with one optional parameter and no output schema, the description covers the key return contents and usage boundaries. It lacks a detailed return structure but mentions sufficient fields (versioning, encryption, public access, security findings) to set expectations. The parameter schema compensates for freshness explanations, making it fairly 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 the single parameter maxAgeSeconds is fully documented in the schema, including its advisory nature and refresh behavior. The tool description does not add parameter-specific meaning, but the baseline of 3 applies when the schema handles the heavy lifting.

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

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

The description opens with a specific verb and resource: 'Returns all S3 buckets with versioning status, encryption, public access configuration, and security findings.' This clearly defines the tool's scope and differentiates it from siblings by explicitly naming get_infra_overview as the alternative for infrastructure counts.

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

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

Explicit when-to-use scenarios are given: checking existing buckets, reviewing security posture, and confirming bucket names before writing handlers. It also states a clear when-not-to-use case ('Do NOT call when you only need a quick infrastructure count') and names the alternative tool, providing strong guidance.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It clearly states that referencedKeys are key names inferred from application code and 'never the values', which is a critical privacy/security trait. It does not mention caching or data freshness in the main description, but that is covered in the schema description for maxAgeSeconds, so no extra credit is needed there.

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 exactly two sentences with no wasted words. The first sentence states what the tool returns, and the second explains when to use it. Every phrase contributes meaning.

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 names the return fields (rotation status, rotation interval, referencedKeys) and clarifies what they mean. It also covers typical use cases and is well-suited for a tool with one optional parameter. The schema description adds freshness behavior, making the overall definition 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% for maxAgeSeconds, and the schema description is exceptionally detailed, explaining the advisory nature, dataHealth reporting, and that nothing re-reads AWS on a tool call. While the main description adds no parameter info, the schema provides the necessary semantics, justifying a score above the baseline of 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?

The description uses a specific verb 'Returns' and identifies the resource 'all Secrets Manager secrets' with precise attributes (rotation status, rotation interval, referencedKeys). This clearly distinguishes it from sibling overview tools like get_parameter_overview or get_cognito_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?

The description provides explicit scenarios for when to call the tool: 'checking which secrets exist', 'confirming rotation is enabled before a security review', and 'before writing code that reads a secret'. It lacks explicit alternatives or when-not-to-use guidance, which would elevate it to 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?

No annotations are provided, so the description carries the burden. It discloses that it reads local IaC files rather than the deployed stack, and details CDK stale-flag behavior with 'stale' and 'staleReason' fields, warning not to rely on stale exports. This goes beyond basic safety and informs the agent about freshness semantics.

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 three sentences, each with distinct value: results, usage, and stale-caveat. It is front-loaded with the primary purpose and avoids repetitive or irrelevant detail. 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?

Despite lacking an output schema or annotations, the description covers what is returned, when to use, when not to use, and a subtle behavioral detail about stale CDK outputs. This is sufficient for an agent to select and invoke the tool correctly.

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

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

The schema has one parameter (maxAgeSeconds) with 100% coverage; the schema's own description fully explains its semantics, including advisory behavior and dataHealth reporting. The tool description does not add parameter-level details, but the schema covers it well, warranting the 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?

The description clearly states the tool returns stack outputs and cross-stack exports from local IaC files (Terraform and CloudFormation/CDK). It distinguishes itself from sibling tools by focusing on cross-stack export names and explicitly noting it does not return live resource attributes. The verb 'Returns' is specific and the resource scope is precise.

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

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

It explicitly states when to call: when wiring cross-stack references (Fn::ImportValue, terraform_remote_state) or when needing the exported name of a resource in another stack. It also provides an exclusion: do NOT call for live resource attributes, as outputs come from local IaC files. This clear when/when-not guidance is exemplary.

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 present, so the description carries the full burden. It clearly signals a read-only operation with 'Returns' and lists the returned fields. However, it does not disclose that the data may be cached or that AWS is not re-read on each call; that detail is only mentioned in the maxAgeSeconds parameter description. This is a notable transparency gap for a tool that returns an overview.

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 exactly two sentences: the first states the returned resources and fields; the second gives contextual usage and points to an alternative. It is front-loaded, concise, and every 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?

With no output schema and no annotations, the description must cover purpose, usage, and return content, which it does. The only minor gap is the lack of explicit behavioral notes on data freshness in the main description, but the parameter description compensates. For a read-only overview tool, this is reasonably complete.

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

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

The input schema has a single optional parameter with a rich description covering freshness tolerance, advisory behavior, and usage guidance. Schema coverage is 100%, so the baseline is 3; the tool description itself does not add parameter-level semantics but the schema carries the weight.

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 verb 'Returns' with specific resources ('Kinesis data streams' and 'Amazon MSK clusters') and enumerates the returned attributes, making it unmistakably clear what the tool does. It also distinguishes from the sibling tool by naming 'get_topic_details' 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?

The description provides explicit when-to-use guidance: 'Call this when writing Kinesis producer or consumer code, checking whether a stream is PROVISIONED or ON_DEMAND before writing PutRecord calls, or reviewing streaming architecture.' It also names the alternative tool for Kafka topic-level mappings.

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

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

With no annotations, the description carries the transparency burden. It discloses important behavioral traits: short-name matching and case-insensitivity, 'Row data is never included,' and the DynamoDB costSignal note. The word 'Returns' plus the explicit exclusion of row data strongly implies a read-only operation. However, it does not explicitly state the snapshot/staleness behavior (which appears only in the schema's maxAgeSeconds description) or what happens when a table is not found. These minor omissions prevent 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 concisely written and front-loaded: the first sentence states the core purpose and contents, followed by naming behavior, usage guidance, exclusions, and a final note. Four sentences cover everything without redundancy or filler. Each 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 tool with no output schema and moderate complexity, the description is remarkably complete. It covers what the return value includes (columns, keys, indexes, DynamoDB billing mode, estimated counts), the naming behavior, usage context, exclusions (no row data), and a system-specific detail (costSignal). The parameter schemas supply the remaining operational details, leaving no significant gaps for an agent to make a correct selection or 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?

The schema already describes both parameters (100% coverage), so the baseline is 3. The description adds meaning beyond the schema for `tables` by specifying 'Accepts short names ("orders" matches "public.orders") and is case-insensitive.' This is extra semantic value. It does not describe `maxAgeSeconds` in the main description, but the schema does, and the description's added naming behavior justifies a 4 rather than a 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?

The description clearly states the tool's function: 'Returns the full schema for specific tables or collections by name' and enumerates the included elements (columns, data types, nullability, primary keys, foreign keys, indexes, DynamoDB keys/billing mode, MongoDB counts). It also distinguishes from siblings via explicit comparisons: 'instead of pulling every schema with get_graph_summary' and 'Do NOT call for a table inventory; use get_infra_overview for that.'

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 explicit when-to-use guidance: 'Call this after get_infra_overview when you need column-level detail to write a SQL query, DynamoDB expression, or MongoDB filter for specific tables.' It also clearly states when not to use it and the alternative: 'Do NOT call for a table inventory; use get_infra_overview for that.' It even points to an alternative for broader schemas: 'instead of pulling every schema with get_graph_summary.'

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

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

With no annotations, the description carries the burden of disclosure. It highlights a critical behavioral detail: filter policies list required message attributes, and publishers must include them or 'messages are silently dropped.' This warns about a failure mode beyond what a simple 'get' would imply. It also implies a read-only operation via 'Returns,' though it doesn't explicitly state safety.

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 three sentences: the first states the return value, the second explains an important behavioral consequence, and the third gives usage guidance. Every sentence earns its place with no redundancy or fluff, and the key information is front-loaded.

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

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

For a read-only list tool with one optional parameter and no output schema, the description covers the essential context: what data is returned, a key caveat about message attributes, and when to use it. It doesn't mention data freshness limits, but the schema parameter description covers that. The description is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with maxAgeSeconds fully described in the schema (including dataHealth and refresh behavior). The tool description adds no parameter details beyond the schema, so the baseline of 3 applies. The schema already explains the parameter's semantics thoroughly.

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 SNS topics with specific details (subscription count, encryption status, filter policies). It uses a specific verb ('Returns') and resource ('SNS topics'), making its purpose unambiguous and distinguishable from sibling tools like get_eventbridge_details or get_queue_details.

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

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

Provides explicit usage guidance: 'Call this before writing any SNS publish code or when reviewing event fan-out patterns.' This gives clear context for when to use the tool. While it doesn't name alternatives or state when not to use it, the guidance is specific 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 provided, the description carries the full burden of disclosure. It details what the tool returns (exact ALTER TABLE SQL, composite variant, EXPLAIN guidance) and importantly notes a limitation: 'Does not verify whether the index already exists.' This is valuable behavioral context beyond the input schema.

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

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

The description is two sentences that efficiently cover function, usage, and a limitation. It is front-loaded with the core purpose and contains no filler. Every 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 2-parameter tool with no output schema, the description is remarkably complete. It explains what the tool does, when to use it, what it returns (including composite variant and EXPLAIN guidance), and a key caveat (does not verify existing index). No critical information is missing.

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

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

The input schema already provides descriptions for both parameters ('MySQL table name' and 'Column name to index'), so schema coverage is 100%. The description does not add additional meaning about parameter formats, constraints, or relationships beyond the schema. Thus, it meets the baseline but doesn't elevate 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?

The description clearly states the tool's function: 'Generates the exact ALTER TABLE ADD INDEX SQL for a MySQL table column'. It includes specific deliverables (composite variant, EXPLAIN guidance) and differentiates from siblings by emphasizing MySQL. The verb 'generates' is specific and the resource is clearly identified.

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

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

The description explicitly states when to call it: 'Call this when the analyzer flags a missing MySQL index or full table scan finding.' This is a clear trigger condition, and the mention of MySQL implicitly distinguishes from Postgres or Mongo index tools in the sibling list. Though it doesn't name alternatives, the usage scenario is 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?

No annotations provided, so description fully bears the burden. It discloses generation of both full and partial index SQL, an ANALYZE reminder, and that it does not verify existing indexes. Could mention that it does not execute the SQL, but the word 'generates' implies only SQL output.

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

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

Two front-loaded sentences: first delivers primary function, second provides usage context and an important caveat. Every sentence earns its place with zero waste.

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

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

For a tool with 2 simple string parameters and no output schema, the description is nearly complete. It covers purpose, when to use, and a key limitation. Could briefly note the output is SQL text, but otherwise adequate.

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 both parameters with descriptions (100% coverage). The description does not add extra parameter-level details beyond what the schema provides, so baseline score 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?

Description clearly states it generates exact CREATE INDEX CONCURRENTLY SQL for a PostgreSQL table column, including a partial index variant and ANALYZE reminder. It distinguishes from sibling tools like mysql_index_suggestions or suggest_gsi by specifying PostgreSQL and the exact SQL generation.

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 recommends calling when the analyzer flags a missing index or when writing a query filtering on an unindexed column. Lacks an explicit 'when not to use' statement, but the provided use cases are clear and directional.

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

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

With no annotations, the description carries the full burden. It discloses a key behavioral trait: the tool checks existing indexes and returns alreadyIndexed: true with an existing index name rather than proposing a duplicate. It also implies no mutation by saying 'generates a definition.' It could add more on error behavior or persistence, but overall it provides strong 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: main purpose, when to use, and key behavior with an alternative. Front-loaded and no filler. Every 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 2-param tool with no annotations and no output schema, the description is thorough. It explains what is produced, the alreadyIndexed special case, and points to get_table_schema for more information. This is sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces the meaning of 'attribute' as the index key and adds context on how table and attribute are used together, including the duplicate check behavior. This adds 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 uses a specific verb ('generates') and resource ('DynamoDB GSI definition'), and clearly distinguishes from sibling tools like postgres_index_suggestions and get_table_schema by naming DynamoDB and the exact output components (index name, partition key, projection type, billing mode). The alreadyIndexed behavior further differentiates 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?

Explicitly states when to call: 'when a query pattern needs an index that does not exist yet, or when the analyzer flags a missing GSI finding.' Also names an alternative: 'Use get_table_schema for the full index list on a table.' This provides clear context and exclusion.

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 bears full burden. It discloses that the tool generates commands and does not execute them, and it does not check for existing indexes. This is transparent, though it could note that it is a suggestion-only tool with 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?

Three sentences, front-loaded with the core action, no unnecessary words. 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?

The description covers the output (the command, variants, explain query) and usage context. Without an output schema, it sufficiently explains what the tool returns. It is complete for a suggestion 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 descriptions for 'collection' and 'field' are already present. The description adds context by mentioning compound and text index variants, indicating the tool's broader functionality 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 generates the exact db.collection.createIndex() command for a MongoDB field, including compound and text index variants and an explain query. It distinguishes itself from sibling tools like mysql_index_suggestions and postgres_index_suggestions by specifying MongoDB.

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 when to call the tool: when a collection scan is flagged by the analyzer or when writing a query filtering on an unindexed field. It also mentions what it does not do (check if index already exists), providing clear guidance.

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