Reads the full official AWS document behind a search result when its excerpt is insufficient, using a fixed upstream URL instead of arbitrary fetching.
Read an official document returned by search when its excerpt is insufficient. Fixed upstream; no arbitrary URL fetch.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| maxLength | Yes | ||
| startIndex | Yes |
Changes observed during successful MCP inspections.
v0.4.1Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds genuinely non-obvious context beyond them: the URL is fixed upstream and arbitrary fetching is not permitted, which tells the agent where valid inputs come from. It omits any mention of truncation or paging behavior, which matters for a long-document reader.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the usage trigger front-loaded ahead of the URL-provenance constraint. Every clause 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?
The tool is a read-only fetch with no output schema, so the description does not need to explain return values, and the URL constraint is well communicated. However, with three required, undocumented parameters and no explanation of how chunked reading works, an agent cannot reliably page through a long document.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the parameter burden, and it documents only the url indirectly ('no arbitrary URL fetch'). startIndex and maxLength are never mentioned; an agent has no cue that they page through a long document in chunks of up to 12000 characters.
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 (read an official document) and scopes it to documents 'returned by search', which distinguishes it from aws_knowledge_search. It stops short of saying what 'read' actually returns (a slice of the document), leaving the retrieval semantics implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Read ... when its excerpt is insufficient' gives a clear trigger condition and implies the two-step search-then-read workflow without naming the sibling explicitly. There is no statement of when not to use it or what to do if the URL is not from search results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.