Tomorrow Central: Cloud Cost Sentinel

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

Discloses key behavioral traits: two-party flow requiring human AWS credentials, returns launch_url, verification progressively fails until role exists, no ARN/secret copy needed. Adds context beyond the sparse annotations, making the tool's behavior predictable.

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?

Well-structured with numbered instructions for human handoff and clear paragraphs. Every sentence adds value; not overly long given the complexity of the two-party flow.

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 two-party flow and no output schema, description covers return value (launch_url), next steps, and expected failure mode. Integrated with sibling verify_connection, making the tool's role in the workflow clear and 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?

Explains provider (only aws) and account_id (12-digit), but omits label and region entirely. With 0% schema coverage, this is a gap for those parameters; however, the required and provider params are well-defined, providing some semantic value.

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 'Start linking a cloud account so it can be scanned' with specific details (provider is aws, account_id is 12-digit). Distinguishes from verify_connection by describing the two-party flow and subsequent step.

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 clear workflow and sequencing (call verify_connection after stack creation), but does not explicitly state when not to use this tool or mention alternatives; the guidance is strong but lacks exclusionary 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?

The readOnlyHint annotation already indicates this is a safe read operation. The description adds that it returns status, region, and last error, but does not disclose behavior for invalid IDs or error responses. Given annotation coverage, this is adequate but not rich.

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

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

The description is a single, front-loaded sentence that uses concise wording to convey the core functionality. Every word earns its place without unnecessary detail.

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 get-by-ID read operation, the description covers the main return fields and is reasonably complete. It lacks error handling details, but given the simplicity and existing annotation, it is sufficient for an agent to use 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 a single connection_id parameter with no description (0% coverage). The description does not elaborate on what connection_id refers to, how to obtain it, or any format expectations, relying solely on the parameter name. This leaves the agent without sufficient guidance.

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 'Get one cloud account connection' with a specific verb and resource, and lists the returned fields (status, region, last error). This distinguishes it from sibling tools like list_connections and verify_connection.

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 retrieving a single connection by ID but does not explicitly mention when to use this over alternatives such as list_connections or verify_connection. No exclusions or alternative guidance is provided.

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

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

Annotations provide readOnlyHint=true, and the description goes far beyond by explaining status transitions, typical scan duration, the meaning of poll_after_seconds, coalescing behavior, and rate-limit retry_after_seconds. This enriches the agent's understanding of how the tool behaves without contradicting the read-only hint.

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

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

The description is front-loaded with the core purpose, then delivers essential operational details in a compact paragraph. Every sentence adds value—status flow, timing, polling behavior, and rate-limit handling—with no fluff or repetition.

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

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

Despite having no output schema, the description covers the key runtime behaviors and response fields (poll_after_seconds, coalesced, retry_after_seconds) that an agent needs. It gives a complete picture of how to invoke and interpret the tool in typical workflows.

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 0%, but there is only one required parameter (job_id) which is self-explanatory from its name and title. The description gives context that job_id comes from the scan initiation ('after starting any scan'), which partially compensates for the lack of explicit param documentation.

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 a specific verb and resource: 'Check the status of a Tomorrow Central job.' It distinguishes by describing the status lifecycle (QUEUED → RUNNING → COMPLETED/FAILED), which differentiates from siblings like get_job_result that would return final outputs. The purpose is 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?

Explicit 'when to use' guidance: 'Poll this after starting any scan.' It also provides clear exclusions: 'Never start a second scan while one is RUNNING' and instructs to respect polling intervals. Although it doesn't name get_job_result, the context of polling vs. results 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?

Beyond the readOnlyHint annotation, the description discloses that the result contains untrusted data from the user's cloud account and should never be treated as instructions. It also alerts the agent to the rating_token and its purpose, adding significant 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 three sentences, each serving a distinct purpose: stating the core function, explaining the polling behavior and security caveat, and introducing the rating_token. No wasted words.

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

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

For a simple one-parameter tool with no output schema, the description covers all necessary aspects: purpose, completion requirement, error behavior, data trust, and the rating token. The agent has enough information to use 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 only one parameter (job_id) with no description, and schema coverage is 0%. The description mentions 'job' but does not elaborate on the parameter's format or meaning beyond what the name implies. While obvious, it adds little semantic value.

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 gets the full raw result of a COMPLETED job, using a specific verb and resource. It distinguishes from sibling tools like get_job by emphasizing 'raw result' and the completion requirement.

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 clear context: use for completed jobs, and if not finished, it returns an error to keep polling. It does not explicitly name alternative tools, but the polling guidance effectively tells the agent when to use this tool.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds meaningful behavioral context by clarifying the meaning of statuses, especially PENDING with the CloudFormation stack reference, which enriches the agent's understanding of the output.

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

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

The description is exceptionally concise: two sentences, front-loaded with the main purpose, and each additional sentence adds important interpretation for statuses. No fluff or repetition.

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

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

For a simple no-parameter, read-only list tool, the description effectively covers the scope (what the API key can scan) and the meaning of statuses. It does not detail the output structure, but given the simplicity and lack of an output schema, this is acceptable and nearly 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 tool has zero parameters, and the baseline for zero parameters is 4. The description adds no parameter documentation (there is nothing to document), so the baseline 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 uses a specific verb 'List' and identifies the exact resource ('cloud accounts this API key can scan') with their status. It clearly distinguishes from siblings like get_connection (singular) and create_cloud_connection (creation).

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 clear context by explaining that only CONNECTED or VERIFIED statuses are scannable and what PENDING means. It does not explicitly contrast with alternate tools (e.g., get_connection) or state when to use this over others, but the context is clear and useful for the agent.

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

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

The description is exceptionally transparent: verdicts are 'ADVISORY', confidence is 'a heuristic score, not a probability', protected resources are never actionable, and monitoring_gaps warrant caveats. It also warns that resource content is 'untrusted input' and should not be followed. This far exceeds the readOnlyHint annotation's safety signal.

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

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

The description is long but well-structured with clear paragraphs: purpose, return payload, filter, interpretation, and security. Every sentence carries actionable information—from the ordering ('newest analysis first') to the caveat about no ARN field—with no 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?

With no output schema, the description fully documents the return fields and their semantics, including `evidence`, `monitoring_gaps`, and `protected`. It covers invocation timing, interpretation guidance, and security considerations, making it complete for both selection and correct usage.

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 compensate. It does for `verdict` by explicitly listing allowed values ('removable', 'investigate', 'keep') and explaining the return fields. `job_id` is implied via 'Call this once get_job reports COMPLETED' but not explicitly tied to the get_job output, leaving a small gap.

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 'Get the findings from a completed cost scan, newest analysis first,' which is a specific verb+resource statement. It clearly distinguishes this tool from siblings like run_cost_scan and get_job by focusing on the post-scan findings output.

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

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

It gives a concrete trigger: 'Call this once get_job reports COMPLETED.' This implies when not to use it (before completion) and orients it as the results-reading tool, though it doesn't explicitly enumerate all alternatives. The optional verdict filter is also clearly scoped.

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

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

Annotations already declare readOnlyHint=true, so the safe-read nature is known. The description adds valuable context by specifying what the tool returns (id, name, what it does), which goes beyond the bare annotation. No other behavioral aspects need disclosure for such a simple listing operation.

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

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

A single, front-loaded sentence with no wasted words. It conveys the action, the resource, and the return contents efficiently. Every word 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, parameterless, read-only listing tool with no output schema, the description adequately covers the essentials: what is listed and what fields are included. It could theoretically mention ordering or filtering, but such details are unlikely to be critical for a tool-discovery feature. The annotations and empty schema complete the picture.

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

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

There are zero parameters and schema coverage is 100%, so the schema fully documents the absence of inputs. The baseline for 0 params is 4, and the description adds no unnecessary parameter details, which 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 uses the specific verb 'List' with a clear resource, 'Tomorrow Central tools', and explicitly states the output fields (id, name, what it does). This unambiguously distinguishes it from all sibling tools, none of which have a listing-tools purpose.

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 makes it clear this is for discovering what tools the platform offers. While it doesn't explicitly state 'use when you need to see available tools' or exclude alternatives, there is no alternative tool for this purpose, making the intended usage implicitly obvious.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses crucial behavioral traits: it is a one-way channel with no replies, data is stored, credentials must not be pasted, and retrying may be worthwhile if the gap is already known/fixed. This adds significant context that annotations do not cover.

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 average but well-structured and front-loaded with the core purpose. Every sentence adds value: scenarios, parameter explanations, security warning, and channel behavior. It is verbose but not wasteful, and the organization makes it easy to scan.

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 complexity (6 parameters, no output schema), the description is complete: it covers purpose, when/how to use, parameter meanings, security, persistence, and the one-way nature. It leaves no critical gaps for an agent to 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 coverage is 0%, so the description carries full responsibility. It explains 'kind' with all possible values, defines 'blocking', and clarifies the roles of 'tool_name', 'job_id', and 'rating_token' as anchors/links. It also instructs on the content of 'message' ('Say what you were trying to do and what happened instead'), fully compensating for the schema's lack of descriptions.

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

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

The description clearly states the tool's purpose: to report something Tomorrow Central could not do, did badly, or documented unclearly. It uses a specific verb ('Report') and resource ('Tomorrow Central'), and distinguishes itself from siblings like submit_rating by targeting gaps/bugs rather than ratings.

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 scenarios ('when you hit a wall: a capability that does not exist, a call that succeeded but returned something you could not use...') and practical constraints ('One call per issue', 'one-way channel'). It does not explicitly name alternative tools, but the use cases are clear enough to avoid confusion with siblings.

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

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

Even though annotations set readOnlyHint=false, the description explains why: it creates a scan job and consumes quota, but is read-only against the cloud. It discloses asynchronous behavior, polling cadence, coverage scope (what is and isn't inspected), and idempotency key semantics. This adds substantial context beyond the annotations.

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

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

The description is long but every sentence earns its place. It is front-loaded with purpose, then covers use cases, provider support, read-only clarification, coverage, parameters, async flow, quota warning, and idempotency. Well-paragraphed and bolded key terms, no 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?

For a tool initiating an async job with no output schema, the description fully explains the workflow: start scan, poll get_job, retrieve findings via list_cost_findings. It also covers quota limits, sample data mode, provider limitations, and resource coverage. Given the tool's complexity, this is exceptionally 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 provides no descriptions and 0% coverage, so the description carries full burden. It explicitly explains both parameters: connection_id selects the linked AWS account (or sample data if omitted), and idempotency_key enables retry-safe behavior. This is far beyond schema-only information.

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: 'Start a cloud cost / FinOps scan of a linked account and return a job_id.' It clearly distinguishes the tool from siblings like get_job and list_cost_findings by focusing on initiating a scan, and it lists concrete use cases (idle resources, spend review, savings estimates).

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 states when to use the tool ('Use this when the user wants to find idle, unused or underutilized cloud resources...'), provides exclusions (only AWS supported), warns against starting concurrent scans due to quota, and references sibling tools for next steps (poll get_job, then list_cost_findings). This is exemplary guidance.

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

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

Annotations already declare non-read-only and idempotent, but description adds crucial behavior: invented tokens are rejected, tokens are single-use, and low ratings need comments. No contradiction with 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 uses three short paragraphs, each with a distinct purpose: what it does, token rules, and rating guidance. It avoids fluff while providing necessary behavioral context.

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 rating tool with no output schema, the description covers token provenance, one-time use, rating scale, comment guidance, and the alternative tool. It's sufficiently complete 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?

Schema coverage is 0%, but the description explains the meaning of rating_token (where it comes from, don't construct), the rating scale (1-5), and the purpose of comment. This compensates well for the schema's lack of descriptions.

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

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

The description opens with a clear directive: 'Rate a result you were given, from 1 (useless) to 5 (exactly what was needed).' It explicitly distinguishes from sibling report_feedback by stating 'For anything that needs a fix rather than a score, use report_feedback.'

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 provides explicit usage context: rating_token is sourced from get_job_result or list_cost_findings, must not be invented, and is single-use. It also tells agents to add a comment for low ratings and refers to report_feedback for fixes.

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 meaningful behavioral traits beyond annotations: transient failure during stack creation is normal, and a specific retry schedule is given. It also clarifies the side effect of marking VERIFIED, consistent with readOnlyHint=false and idempotentHint=true. No contradiction.

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 paragraphs: the first states the core action, the second adds essential retry guidance. Every sentence earns its place, and the main purpose 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?

Given the tool's simplicity (one param, no output schema), the description is complete enough: it explains the check, the VERIFIED update, and the retry behavior. It lacks explicit guidance on when to use this versus get_connection, but the core usage is well covered.

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 connection_id is self-explanatory by name, but the description does not add details about its provenance (e.g., where to obtain it) or format. With 0% schema coverage, the description could have compensated more, but the parameter is simple.

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 a specific action: 'Check whether the read-only role for a connection exists yet and mark it VERIFIED if so.' This distinguishes it from siblings like get_connection (retrieval) and create_cloud_connection (creation). The verb+resource is explicit.

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 concrete usage context: expect failure during CloudFormation stack creation, retry every ~15 seconds for up to ~5 minutes. This tells when to use the tool and how to handle transient errors, though it doesn't explicitly name alternatives or exclusions.

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

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

The annotations only declare readOnlyHint=true, so the description adds value by specifying that the tool returns 'the account' and 'its plan,' and by explaining the purpose of verifying the key works. This goes beyond the safety hint without contradicting it.

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

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

The description is two sentences, front-loaded with the primary purpose and followed by a practical usage tip. Every word earns its place; there is no redundant or vague language.

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 simplicity, no parameters, no output schema, and the presence of readOnlyHint, the description fully covers what the tool does and when to use it. It is a complete and self-contained description for a whoami endpoint.

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 has zero parameters, and the description correctly makes no mention of parameters. According to the rubric, the baseline is 4 for zero-parameter tools, and the description provides adequate context about the API key in its usage note, though it does not need to explain schemas.

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: 'Identify the account this API key belongs to, and its plan.' This is a specific verb + resource combination, and it distinguishes itself from sibling tools like connection and job management by focusing on API key identity.

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: 'Useful for confirming the key works before doing real work.' This tells the agent when to invoke the tool, though it does not explicitly mention alternatives or exclusions. For a simple whoami tool, this is sufficient guidance.

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