Fine Structure

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

The description adds value beyond the annotations by mentioning the return of exact DNS records and referencing the Fine Structure Studio flow, which implies a guided process. Annotations already cover the destructive nature (destructiveHint=true), and the description's 'attach or replace' is consistent. It does not describe side effects of replacement (e.g., whether the old domain is removed) but provides useful context about 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 extremely concise with two sentences, front-loading the core action and then the key output. Every word adds value 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?

For a tool with only two parameters, no output schema, and annotations that cover safety, the description is fairly complete. It explains the action and the return value. Minor gaps remain, such as not clarifying behavior when replacing an existing domain or the need for prior ownership verification, but these are not critical for correct invocation.

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

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

Schema description coverage is 100%; both parameters are documented in the schema. The tool description does not add additional semantics beyond what the schema provides (e.g., the domain format is already in the parameter description). Thus, a 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?

The description clearly states a specific action ('attach or replace') on a specific resource ('the app custom domain'), and even notes the return of DNS records. It implicitly distinguishes from sibling tools like remove_custom_domain and set_primary_domain by its action and 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 indicates what the tool does but does not explicitly say when to use it versus alternatives. It does not name sibling tools like remove_custom_domain or set_primary_domain, nor does it state when not to use it. The context is clear enough that an agent could infer, but there is no direct 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 behavioral trait: 'Does not modify the live app until apply_change_set.' This adds critical context beyond the annotations (readOnlyHint=false, destructiveHint=false), clarifying that the operation is non-destructive to the live app but does modify the change set. It also provides a reference for path conventions, which is useful. It does not elaborate on idempotency or error behavior, but the staging nuance is valuable.

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 concise sentences, each serving a purpose: the main action, the non-live-side-effect, and the path API reference. It is front-loaded with the core purpose and contains no redundant or vague language. Efficient and well-structured.

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 moderate complexity (6 parameters, no output schema), the description covers the essential operational context: what it does, when it takes effect, and how paths are defined. The schema handles parameter details. Missing explicit references to sibling tools (e.g., apply_change_set) or potential validation steps, but the description 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 high (83%), so most parameters are already documented. The description adds a reference to the Fine Structure app file API for path semantics, which complements the 'path' parameter but does not explain details like content requirements for upsert vs. delete. Since the schema carries most of the burden, the description adds marginal value, aligning with 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 clearly states the tool's purpose: 'Stage one file upsert or delete inside a change set.' It identifies the specific action (stage), resource (file change), and scope (one file within a change set). It also distinguishes itself from direct modification tools by noting the change isn't applied until apply_change_set, making the purpose 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?

The description implies usage context: you stage a file change for later application via apply_change_set. However, it does not explicitly state when to prefer this over direct file write tools (e.g., write_app_file) or provide exclusions. The mention of apply_change_set is a hint, but the guidance is not explicit enough for an agent to decide between staging and direct modification without additional inference.

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

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

Annotations already indicate this is a mutation (readOnlyHint=false). The description adds behavioral detail: the ownership transfer only occurs after the client logs in with the invited email, and the agent may remain a collaborator based on the parameter. This goes beyond the annotations by clarifying the post-claim state. No contradiction found.

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 with no unnecessary words; the critical constraint ('Agency mode only') is front-loaded, followed by the core action and a key behavioral consequence. 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?

Despite having 6 parameters and no output schema, the description, combined with full schema documentation, provides enough for correct invocation. It clarifies the ownership transfer timing and existing-app requirement. Minor gaps like how the link is delivered are not essential for calling the tool.

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

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

Schema description coverage is 100%, so all six parameters are documented in the schema. The description does not add additional semantic context beyond the schema, such as relationships between parameters or practical examples. Baseline of 3 is appropriate.

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

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

The description explicitly states the action (create), the object (client claim link), and the context (agency mode, existing app owned by agent). It clearly distinguishes from sibling tools like agency_create_client_app by focusing on the claim-link transfer mechanism. The verb-resource pairing 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?

It mentions 'Agency mode only' as a usage constraint and specifies that the app must already exist, which is helpful. However, it does not explicitly name alternative tools or describe scenarios where this tool should not be used, leaving some routing to inference.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description carries the burden of behavioral disclosure. It explicitly states the operatio is create/update and clarifies non-obvious effects: it does not create a verified user account and does not transfer ownership. This adds valuable context beyond the annotations without contradicting them.

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

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

The description is concise: two sentences, the first front-loading the 'Agency mode only' condition and the main verb+resource, the second adding important limitations. No wasted words, and all information is essential.

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 focuses on operation semantics and side-effect limitations, which is sufficient for a simple create/update tool. It does not explain return values or error conditions, but for a tool with a single required parameter and clear schema descriptions, completeness is adequate. The limitation about not creating a verified account adds needed context.

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

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

Schema description coverage is 100%, so all three parameters have descriptions. The tool description does not add any extra parameter semantics beyond the schema; it only mentions the client record context. The baseline of 3 applies because the schema already documents the parameters.

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

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

The description clearly states a specific action ('create or update a client record') with a defined resource context ('for an account-level agent'). It explicitly distinguishes itself from related operations by noting it does not create a verified Fine Structure user account or transfer ownership, which differentiates it from potential siblings like agency_create_client_app.

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 on when to use it ('Agency mode only') and the target audience ('account-level agent'). It implies differentiation from alternatives by stating what it does not do, but it does not explicitly name alternative tools or provide exclusion criteria beyond the 'Agency mode' restriction.

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 the ownership transfer condition (client must log in and accept claim) which is not implied by annotations. It also notes that generation is started. This adds value beyond the annotations (readOnlyHint false, destructiveHint false), though it doesn't cover all side effects like rate limits or failure cases.

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, efficient and front-loaded with the critical 'Agency mode only' restriction. The ownership transfer condition is important and clearly stated. 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?

With 8 parameters and no output schema, the description should explain what the tool returns (e.g., claim link URL) and any failure modes. It doesn't. The ownership transfer logic is explained, but the agent is left guessing about the return value. Given the complexity, this is a gap.

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

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

Schema coverage is 100%, so the schema fully documents parameters. The description adds relevant context about ownership transfer (client_email) and the claim link process, slightly enhancing meaning. However, it doesn't explain parameter syntax or relationships beyond that, so 3 is appropriate.

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

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

The description states a specific verb ('create'), a specific resource ('a new app'), and the additional actions (start generation, create claim link). It clearly distinguishes from siblings like create_app (which likely lacks the claim link) and agency_create_claim_link (which is only the link).

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 restricts usage to 'Agency mode only', which is a clear prerequisite. However, it doesn't mention when to use this combined tool instead of the separate agency_create_claim_link or create_app, leaving some inference to the agent. Still, the context is helpful.

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, idempotentHint, and destructiveHint=false. The description adds two meaningful behavioral details: it exposes only the status (not the raw claim token) and it is agency-mode only. These go beyond what annotations provide and are useful for safe invocation.

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, tightly written sentence. It front-loads the access restriction ('Agency mode only') and then states the action and its security property. There is zero 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 simple read operation with one parameter and robust annotations, the description is sufficient. It clarifies the scope (one handoff) and the token-protection behavior. It does not specify return format, but with no output schema and simple status, that is not a critical gap.

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

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

Schema description coverage is 100%, so the single parameter handoff_id is fully documented in the schema. The description does not add any additional parameter context, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('inspect') and a clear resource ('handoff status'), and immediately distinguishes itself with 'Agency mode only' and 'without exposing the raw claim token.' This clearly separates it from generic status tools like get_app_status or get_job_status.

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 agency-mode usage and that it is for handoff status, but it does not explicitly state when to prefer this over alternatives. Siblings include many status getters, and no exclusion or selection criteria are given.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds the agency-mode restriction and the fact that the authenticated agent's clients are listed, which is extra context. It does not contradict annotations and provides a meaningful constraint beyond the structured metadata.

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 sentence, front-loading the key qualifier ('Agency mode only') and ending with the action. Every word earns its place, and there is no fluff or redundant phrasing. It is optimally concise for the amount of information conveyed.

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

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

For a simple read-only list tool with one optional parameter, the description covers the essential points: it lists client records and handoff status, is agency-only, and scoped to the authenticated agent. It does not outline pagination or output format, but given the low complexity and no output schema, this is acceptable. A bit more detail on what 'handoff status' contains could be useful, but not necessary.

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 parameter 'include_handoffs' is fully described in the schema with 'Include claim links status without raw tokens.' The description mentions 'app handoff status' which loosely maps to this parameter but does not provide additional meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description states a clear verb (list), a specific resource (client records), and an additional scope (app handoff status). It also includes a distinguishing qualifier ('Agency mode only') that separates it from sibling list tools like list_apps and list_agents. The purpose is unambiguous and actionable.

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 a clear usage context: 'Agency mode only.' This implies it should be used when operating in agency mode and needing client records. However, it does not explicitly name alternative tools or specify when not to use it, though the agency qualifier effectively provides a condition. It is clear enough for most cases.

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

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

Annotations only indicate non-read-only and non-destructive, so the description carries the burden. It adds two important behaviors: it 'Creates a Saved Version before applying' and 'Blocks on validation errors unless force=true.' These go beyond annotation hints and inform the agent of side effects and conditional behavior, though it does not mention post-application state (e.g., whether the change set is consumed).

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

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

Two sentences, no filler. The core action and key side effect are front-loaded, and the blocking condition is stated compactly. Every phrase earns its place.

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

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

For a mutation tool with no output schema, the description covers the essential behavior (apply, create Saved Version, block on errors), and the schema covers parameters. It does not mention prerequisites like needing an existing change set, but the phrase 'staged change set' implies that. Considering the simple tool complexity and that sibling validate_change_set exists, it is sufficiently complete, though it could hint at the recommended workflow (validate before apply).

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 descriptions cover all three parameters (app_id, change_set_id, force) at 100% coverage, so the description adds little parameter-level detail. The only extra is the phrase 'Blocks on validation errors unless force=true,' which reiterates the force parameter's role. This meets the baseline but adds minimal value beyond the schema.

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

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

The description clearly states the action ('Apply a staged change set to the app') and distinguishes itself from sibling lifecycle tools like discard_change_set by noting the side effect of creating a Saved Version. The verb and resource are specific, and it reads as a distinct operation among the change-set siblings.

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

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

The description implies the tool is for applying a previously staged change set and mentions blocking on validation errors, which gives context for when to use it (after validation). However, it does not explicitly reference siblings like validate_change_set or discard_change_set, so alternatives are not spelled out. Still, the usage context is clear enough for an agent to infer the right moment to call it.

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

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

Annotations indicate readOnlyHint=false (mutation) and openWorldHint=true. The description adds valuable behavioral context by stating that numbers already used by other accounts are still valid, and specifically that it answers only the verified phone. It also highlights the verification requirement. No contradiction with annotations; it supplements them with meaningful details.

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, concise, and front-loaded with the primary purpose. It packs in the prerequisite, parameter source, and an important edge case without unnecessary detail. 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 tool with only 2 parameters, no output schema, and clear annotations, the description covers the essential context: what the tool does, the prerequisite (owner verification), the parameter source, and a special-case behavior. An agent has all the information needed to call it correctly.

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

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

Schema description coverage is 100%, so the parameters are already documented well (agent_id and phone_number_id with descriptions). The description adds the note 'Take phone_number_id from get_agent_whatsapp', which reinforces the source but doesn't significantly alter parameter meaning. It also adds the owner-verification context, but that's tool-level, not parameter-specific. Baseline of 3 is appropriate.

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

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

The description clearly states the action 'Connect a platform WhatsApp number to one of the account's agents', the resource (the number and agent), and the outcome (owner can message that number). It distinguishes itself from sibling tools like get_agent_whatsapp (listing) and detach_agent_whatsapp (removal) by focusing on the attachment action.

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 a clear prerequisite ('Requires the owner to be verified first') and tells the agent where to get the phone_number_id from ('Take phone_number_id from get_agent_whatsapp'). It doesn't explicitly say when not to use it versus alternatives, but the sibling detach_agent_whatsapp implies the opposite action, so the context is reasonably 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?

The description explicitly discloses a side effect ('then save the latest status'), which adds behavioral context beyond the annotations. Annotations already indicate readOnlyHint=false, so the description is consistent and provides the specific nature of the mutation (saving status). It does not go into details of failure modes or overwriting behavior, but the core side effect is clearly disclosed.

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 sentence that is concise and front-loads the primary action ('Check...') followed by the side effect ('then save...'). It wastes no words, though splitting the check and save into separate sentences could improve readability. Overall, it is efficiently structured for an agent.

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 relatively simple, but the description leaves gaps: it does not clarify what happens if no custom domain is configured (though 'configured' implies one exists), what 'status' encompasses (verification and SSL states), or what the function returns. Without an output schema, this information would help an agent understand expectations. It is adequate but not fully complete given the context of related domain tools.

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

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

The description does not elaborate on parameter usage beyond what the schema already provides. Schema coverage is 100%, so the parameters are fully documented in the schema. The phrase 'the configured custom domain' hints at the domain param, but it does not add syntax or format details. Baseline 3 is appropriate given high schema coverage and no additional value from the description.

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 ('Check') and resource ('Fine Structure custom-domain verification and SSL status'), and includes the side effect 'save the latest status.' This clearly distinguishes it from siblings like get_domain_verification and get_domain_ssl_status, which only retrieve without saving. The action 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?

No guidance is given on when to use this tool versus the sibling get_domain_verification or get_domain_ssl_status. The description does not mention alternatives or the condition for choosing this combined check-and-save approach. An agent might not know if they need this tool or one of the read-only getters, leaving the decision to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds that the output is 'compact per-file diffs', which tells the agent the format is summarized rather than full file contents. No contradictions 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 is a single concise sentence that states the action and output format, with no extraneous information. It is well-structured and 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?

The description provides the core purpose and output format, and with annotations covering safety, it is sufficient for the tool's simplicity. However, it does not mention any prerequisites like needing a valid snapshot_id obtained from list_saved_versions, which could improve completeness.

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 describes app_id and snapshot_id but leaves max_diff_chars undocumented. The description does not add any parameter details beyond the schema, so it doesn't compensate for the missing explanation of max_diff_chars. With 67% coverage, the description adds minimal value for parameter understanding.

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

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

The description clearly states the action: comparing current app files to a saved version (identified by snapshot_id) and returning compact per-file diffs. This distinguishes it from siblings like compare_saved_versions (which compares two saved versions) and get_app_files (which reads files without diffing).

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 indicates the tool compares the current state to a specific Saved Version, implying it is used to inspect changes since a checkpoint. However, it does not explicitly mention when not to use it or alternatives, such as compare_saved_versions for comparing two historical versions. This leaves some ambiguity for an agent deciding between the two.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the output format (per-file changes and diffs) but does not elaborate on any other behaviors such as ordering, size limits, or error handling. With annotations carrying the core transparency, a 3 is appropriate.

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

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

The description is a single, concise sentence that states the action, resource, and expected output types. It is front-loaded with the operation and immediately provides the key information without any filler.

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

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

For a read-only comparison tool, the description covers the essential output (what the tool returns) and, thanks to annotations, the side-effect profile. It does not discuss any pagination or limits on the diff size (though max_diff_chars parameter exists), but given the simplicity of the operation and the existing annotation coverage, it is largely 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 75% (three of four parameters have descriptions; max_diff_chars lacks one but has a default). The description does not add any parameter-level meaning beyond what the schema already provides, such as clarifying the difference between base_snapshot_id and target_snapshot_id. Since the schema covers most parameter details, the description adds minimal 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 verb 'compare' and the resource 'two Saved Versions', and specifies the output: per-file additions, removals, modifications, and compact diffs. It is specific enough to distinguish from most siblings, though it does not explicitly differentiate from the closely related 'compare_current_to_version'.

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

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

No guidance is provided on when to use this tool versus alternatives like 'compare_current_to_version' or 'list_saved_versions'. The description does not mention prerequisites or selection criteria, leaving the agent to infer based on the resource names.

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 indicate a non-read-only, non-idempotent, non-destructive operation. The description adds no further behavioral detail (e.g., whether it replaces existing redirects, if it affects live traffic immediately, or if it fails when the domain is unverified). With annotations covering the basic mutation profile, the description offers minimal added 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?

A single, front-loaded sentence that captures the core purpose and key options without fluff. No wasted words; every part is informative.

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

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

For a configuration operation with four parameters and no output schema, the description is adequate but leaves out important context like prerequisites, side effects, or failure conditions. Given the openWorldHint and mutating nature, more context would help an agent call it correctly, though it's not severely incomplete.

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 each parameter has a clear description. The summary sentence merely re-iterates the parameter list without adding new meaning, so the schema carries the semantic burden. 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 action: 'Configure custom-domain redirect policy' and lists the specific aspects (primary domain, www/root redirect, HTTPS enforcement). This distinguishes it from siblings like set_primary_domain, which likely only sets the canonical domain without redirect policy.

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

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

No guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., domain must be verified or added), nor does it differentiate from set_primary_domain or check_domain_verification. An agent cannot infer the appropriate context without extra knowledge.

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 consistent with the annotations (readOnlyHint=false implies a write, matching 'Store'). It adds the 'safe non-secret' boundary beyond what the annotations convey, which is useful misuse prevention. However, the safety profile is largely already carried by the annotations (destructiveHint=false, idempotentHint=false), so the description adds only marginal behavioral context. 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 dense sentences with zero filler: the primary purpose is front-loaded, and the critical alternative-routing to set_secret comes second. 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?

For a non-destructive write tool with full parameter schema coverage and annotations carrying the safety profile, the description covers the essential decision the agent must make — what data belongs here vs set_secret. It doesn't describe return values, but no output schema exists and this is a storage operation where the return is not critical to correct invocation.

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

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

Schema description coverage is 100%, with each parameter (app_id, provider, config, is_active) already explained in the schema. The description reinforces the config constraint ('safe metadata only'), which echoes the schema, but doesn't add meaningful new semantics beyond what the schema provides. The baseline of 3 for full schema coverage is appropriate.

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

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

The description states a specific scope — storing safe, non-secret integration metadata for an app — and explicitly marks the boundary against set_secret, which handles API keys/tokens. The verb 'Store' is slightly generic, but the resource (integration metadata) and the non-secret qualifier distinguish this clearly from its most probable confusion sibling.

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

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

It gives an explicit routing rule: 'Use set_secret for API keys/tokens.' This tells the agent when NOT to use this tool and names the exact alternative for the most likely mis-selection. It doesn't cover other sibling relationships (e.g., vs list_integrations), but for the critical secret-vs-metadata decision the guidance is direct and unambiguous.

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 indicate this is a mutation (readOnlyHint=false). The description adds the effect on success (owner verified, agents can message, platform numbers connectable), which is useful context. However, it does not mention failure behavior, idempotency (already false), or error handling beyond that. It adds some value but is not comprehensive.

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 with no waste. The first sentence states the action and source, the second gives the consequence. All essential information is front-loaded, making it quick for an agent to parse.

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 verification confirm, the description provides the flow context (paired with start_owner_phone_verification) and the outcome. It does not cover failure scenarios or return format, but this is not critical for a basic confirmation tool. The lack of an output schema is not a major gap here.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema. The description adds minimal extra meaning—it mentions the code was received from start_owner_phone_verification, but this is already implied by the schema's 'from the WhatsApp message.' With complete schema coverage, 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 action ('Confirm the 6-digit code') and the resource (owner phone verification from start_owner_phone_verification). It also explains the outcome, distinguishing it from siblings like start_owner_phone_verification by referencing that paired flow.

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 ties the tool to start_owner_phone_verification, indicating it should be used after that flow and after receiving the code. It does not explicitly state exclusions or alternatives, but the context is clear enough for an agent to know when to use it.

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

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

With annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), the agent already knows this is a mutating, non-idempotent operation. The description adds useful context by mentioning the creation of a Saved Version before the change and the 'native Fine Structure' nature. No contradiction with annotations. The side effect disclosure goes beyond 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?

Three sentences, each carrying essential information: the primary purpose, a prerequisite workflow step, and a side effect. Front-loaded with the core action. No redundant or filler content.

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

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

The tool is complex (7 params, nested objects, no output schema), but the schema fully documents parameters, including constraints like 'Traffic must total 100.' The description adds the critical side effect (Saved Version) and prerequisite (update_app). The only minor gap is that it doesn't state what the tool returns, but since there is no output schema, that is not mandatory.

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

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

Schema description coverage is 100% (all 7 parameters have descriptions in the schema). The tool description does not add parameter-level detail; it only provides an overall prerequisite. According to the calibration, baseline 3 is appropriate when schema covers the parameters, and the description doesn't need to repeat them.

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

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

States a specific verb+resource ('Create a native Fine Structure A/B test') and distinguishes from siblings like delete_ab_test, update_ab_test, list_ab_tests, and get_ab_test_stats. The description makes it clear this is about creating a test between existing app pages, leaving no ambiguity.

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 a concrete prerequisite: 'Use update_app first if a variant page still needs to be generated.' This clearly indicates a common workflow step. It also notes the side effect of creating a Saved Version, which informs when to use this tool. However, it does not explicitly list alternatives or conditions when not to use it, so it falls short of a 5.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false, which is minimal. The description carries the full burden of behavioral disclosure and does so thoroughly: it states the agent gets a default safe tool policy, its own email address, read/write access to the app database, messaging capabilities contingent on owner verification, and a prerequisite for messaging others. This goes far beyond what annotations provide and fully informs the agent of 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?

The description is four sentences but packs a wealth of information without redundancy. It front-loads the core purpose, then explains capabilities, then provides usage context. Every sentence earns its place and the structure is logical, making it easy for an agent to parse.

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 what the agent gets, its capabilities, prerequisites, and usage examples. It does not explicitly state the response format (e.g., returned agent object), but given the absence of an output schema, that is the only gap. Overall, it is complete enough for an agent to understand the tool's effects and how to use it, so a 4 is appropriate.

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 description coverage is 100%, meaning every parameter already has a description. The tool description does not add meaning beyond the schema, such as clarifying parameter interactions or providing examples. The baseline of 3 applies because the schema does the heavy lifting; the description adds no extra parameter 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 uses a specific verb ('Create') and resource ('autonomous AI agent on the user's Fine Structure account'), and clearly distinguishes it from a chat session. It also names a related sibling (schedule_agent_task) and sets expectations about its standing-worker nature. This differentiates it from the many other creation tools in the sibling list.

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 guidance: it says 'Pair it with schedule_agent_task for recurring work' and gives concrete examples (following up leads, watching for errors, weekly summaries). It also directs the reader to get_agent_whatsapp for phone verification and explains constraints on messaging other than the owner. This clearly defines when and how to use the 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?

Discloses asynchronous behavior (returns a job_id and requires polling) and states the outcome ('app is ready' when done). This goes beyond the annotations, which only indicate non-read-only, non-idempotent, and non-destructive. No contradictions 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?

Three concise sentences with no fluff. The main purpose is front-loaded, followed by return value and next steps. 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?

There is no output schema, but the description specifies the return value (job_id) and how to track it (poll get_job_status), which is essential for the agent to use it correctly. For a creation tool with only three parameters, this is sufficiently 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 has 100% description coverage for all three parameters, so the baseline is 3. The description adds minor context by calling the 'prompt' a 'natural language prompt' and mentioning generated aspects, but does not substantially enhance parameter meaning beyond what the schema already provides.

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 and resource: 'Create a new application' and specifies it builds a complete web app with pages, components, styling, and data models. It distinguishes from siblings like create_agent (creates agents) and update_app (modifies an app) by focusing on creation from a natural language prompt.

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: use this to create a new app from a prompt, and it tells you to poll get_job_status for progress. However, it does not explicitly list alternatives or when not to use it, so it lacks explicit exclusions or sibling comparisons.

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 says 'apply atomically,' which suggests a write/apply operation, but annotations declare destructiveHint=false. While the existence of apply_change_set suggests create_change_set only creates a set, the description's wording could mislead an agent into thinking it applies changes. It also doesn't disclose that this is a write operation (though readOnlyHint=false implies it) or mention idempotency. The description fails to clarify its actual behavioral scope.

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 only two sentences, so it's concise, but the second sentence is redundant and potentially misleading. It could be trimmed to just 'Create a staged file change set' and then note that applying is separate. It doesn't front-load the essential differentiator from siblings. It's not too long, but not optimally structured.

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 doesn't explain what happens after creation—whether to use add_file_change and apply_change_set—or what the tool returns. There's no output schema, so the description should at least hint at the next steps or return value. It also doesn't mention any prerequisites (e.g., existing app). The workflow is incomplete, leaving the agent without a clear sequential path.

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 both label and app_id already described. The description adds no extra meaning about parameter relationships, defaults, or constraints. It only mentions 'staged file change set' which doesn't directly illuminate the parameters. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description opens with 'Create a staged file change set,' which names the action and resource. However, it then adds 'Add multiple file changes, validate them as one app state, then apply atomically,' which could be misread as the tool performing all these steps, especially given sibling apply_change_set. It doesn't explicitly differentiate itself from apply_change_set, leaving the exact scope ambiguous.

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

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

There is no guidance on when to use this tool versus apply_change_set or add_file_change. The description implies a workflow but never states 'Use apply_change_set to apply' or 'Create a set before adding changes.' The agent is left to infer the sequencing from sibling names.

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 are all false (readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false), so they offer no safety profile. The description adds that it executes directly for the authenticated owner and returns created record IDs, which is useful. However, it does not disclose potential side effects, failure behavior (such as the expected_count safety abort mentioned in the schema), or whether the operation is batch-atomic. With weak annotations, the description should carry more of this burden.

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, concise sentence that front-loads the core action and includes the key behavioral detail (return of created IDs). There is no redundancy or fluff; every phrase contributes to understanding the tool's purpose and outcome.

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 create operation with five parameters and no output schema, the description is adequate but not exhaustive. It explains the execution context (direct for owner) and return value (IDs), but does not mention batch behavior, error conditions, or prerequisites like entity existence. Given the tool's moderate complexity and the absence of an output schema, some additional context would improve completeness, though it is not severely lacking.

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

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

Schema description coverage is 100%, so all five parameters (app_id, entity, reason, records, expected_count) are already documented in the input schema. The description does not add any additional meaning or clarification beyond what the schema provides. Per the standard, a high-coverage schema sets a baseline of 3, and the description offers no extra value here.

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 starts with 'Create/insert records in one app entity,' which clearly states the action (create/insert) and the resource (records in an app entity). It distinguishes itself from siblings like create_entity_schema (which creates the schema) and update_entity_records (which modifies existing records) by focusing on insertion. The added detail 'returns the created record ids' further clarifies the outcome.

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 this tool is for creating records, but it does not explicitly say when to use it versus alternatives such as update_entity_records, delete_entity_records, or seed_entity. The phrase 'Executes directly for the authenticated app owner' hints at an ownership requirement but provides no exclusions or conditions. There is no comparison with sibling tools to guide selection.

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 indicate write behavior (readOnlyHint=false). The description adds a notable detail that a Saved Version is created before writing, which is useful. However, it omits other behavioral aspects like handling of existing files (overwrite parameter), whether directories are created, or potential failure modes. While it adds some context, it does not fully compensate for the lack of annotation coverage on 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?

The description is two concise sentences with no redundant words. The primary action is front-loaded, and the saved-version behavior is stated succinctly. Every word 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?

Given the tool has 7 parameters, nested objects, and no output schema, this description is far too brief. It lacks details about the schema structure, optional parameters, behavior when overwriting, and expected return value. An agent would need to consult the schema extensively and might still be uncertain about semantics for the optional fields.

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 low (43%), so the description should clarify parameters. It only infers that 'entity' becomes part of the file path, and mentions nothing about 'schema', 'indexes', 'metadata', 'overwrite', or 'relationships'. The description adds minimal meaning beyond the schema, failing to compensate for the undocumented parameters.

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

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

The description clearly states the action ('Create an entity schema file') and the resource ('in entities/<Entity>.json'). It uses a specific verb and names the output location, distinguishing it from siblings like update_entity_schema. The purpose is immediately obvious.

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

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

No guidance is provided on when to use this tool versus alternatives such as update_entity_schema or create_entity_records. The description does not mention conditions, prerequisites, or typical scenarios, leaving the agent to infer usage from the tool name alone.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds a valuable behavioral detail—'Creates a Saved Version before the change'—which agents need to understand the tool's safety net. This goes beyond the annotations and is precise.

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-loads the core action, and adds one crucial behavioral note. No wasted words or repetition of schema information.

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

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

For a simple destructive tool with two well-documented required parameters, the description covers purpose, side effects, and scope. It doesn't detail return values or error behavior, but with no output schema and straightforward parameters, nothing critical is missing. An agent can safely invoke it with the given info.

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

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

Schema coverage is 100%, so both parameters (app_id and test_id) are documented in the schema. The description adds no additional meaning about parameters beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific action ('Delete') on a specific resource ('a native A/B test from an app') and mentions a side effect ('Creates a Saved Version'). This differentiates it from siblings like update_ab_test or create_ab_test, even without reading their schemas.

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 purpose implies when to use it (to delete an A/B test), but the description does not explicitly contrast with alternatives like update_ab_test or note conditions where deletion might be inappropriate. No when-not-to-use 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 already declare destructiveHint=true. The description adds that it executes directly for the authenticated app owner, clarifying authorization scope, and explains the expected_count safety check that aborts on mismatch. This provides useful behavioral 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?

Two sentences with no filler. The key action and safety check are front-loaded. The description is efficient and clean, with every sentence earning its place.

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

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

No output schema exists, so the description doesn't need to explain return values. It covers the core action, safety mechanism, and authorization. Some ambiguity remains about whether filters and record_ids can be combined, but for a destructive tool with annotations, the description is sufficient.

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

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

Schema coverage is 100% and each parameter already has a description. The description mentions record_ids and filters for exact matches and expected_count as a safety check, but these are already stated in the schema. It adds minimal meaning beyond what the schema provides, so a baseline 3 is appropriate.

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

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

The description states a specific verb ('delete') and resource ('entity records'), and clarifies the method (by ID or exact-match filters). This clearly distinguishes it from sibling delete tools like delete_ab_test and delete_secret, and from create/update entity record tools.

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

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

The description implies usage for exact deletions but does not explicitly mention when to use this tool versus alternatives like update_entity_records or create_entity_records. There is no guidance on when not to use it, leaving the agent to infer based on intent.

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 destructiveHint=true and readOnlyHint=false, so the description does not need to restate these. It adds the nuance that deletion is by key, but does not disclose additional behavioral details such as irreversibility or permission requirements. The description is consistent with annotations but adds limited context beyond them.

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, concise sentence with no superfluous words. It is front-loaded with the core action and resource, making it immediately 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 two-parameter deletion tool with no output schema, the description provides enough information for an agent to use it correctly. The destructive nature is covered by annotations, and the schema documents the parameters. Nothing critical is missing for the described scope.

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?

Both parameters (app_id and key) have descriptions in the schema, covering 100% of the parameters. The description does not add any extra semantic information beyond what the schema provides, so the 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?

The description clearly states the operation ('Delete'), the resource ('app secret'), and the selection criteria ('by key'). It is unambiguous and distinguishable from sibling tools like list_secret_keys and set_secret, which have different purposes.

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 when to use this tool (when you need to delete a specific app secret), but it does not explicitly state alternatives or provide exclusions. No guidance is given about when not to use it or how it compares to set_secret or list_secret_keys.

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 destructiveHint=true and readOnlyHint=false. The description adds value by specifying the destructive scope (only this account's route, not others), giving the agent a precise understanding of what is affected. This goes beyond the bare annotation and clarifies the non-idempotent nature implicitly. 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?

Two sentences, zero fluff. The core action and the distinction from other accounts are front-loaded, and the second sentence only adds essential scope information. 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 single-parameter action with clear annotations and no output schema, the description provides everything needed to call the tool correctly: what it does, what it affects, and the key nuance about shared numbers. There are no missing prerequisites or hidden behaviors that an agent would need to know.

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

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

Schema coverage is 100% for the single parameter, and the description does not add any additional parameter-level detail beyond the schema's own description ('The number to disconnect'). The phrase 'platform number' maps directly to the parameter, but no new semantics are introduced. Baseline 3 applies due to 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 states a specific action (disconnect/detach) on a defined resource (owner's WhatsApp route from a platform number) and explicitly delimits the scope to this account only, distinguishing it from sibling tools like attach_agent_whatsapp and get_agent_whatsapp. The verb-resource pairing 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?

The description clearly implies when to use (to remove the owner's route from a number) and provides context that other accounts are unaffected. However, it does not explicitly name alternatives or state when not to use it, though the opposite action (attach) is self-evident from the sibling list. Lacks explicit exclusions but context is clear.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating, destructive operation. The description adds valuable context that discarding does not change app files, clarifying the precise side-effect scope. This goes beyond what annotations convey without contradicting them.

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, efficient sentence that front-loads the core purpose and includes the key qualifier. There is no fluff or redundant wording, and every element 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 two-parameter tool with annotations covering safety profiles and the schema documenting parameters, the description provides sufficient context on what the tool does and its side-effect boundaries. It doesn't repeat return-value information (no output schema) and the missing usage guidance is already addressed in the usage dimension.

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 fully describes both parameters (app_id: 'The app ID', change_set_id: 'Change set ID'). The description adds no additional parameter-level meaning, so with 100% schema coverage the 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?

The description uses a specific verb ('discard'), identifies the resource ('pending staged change set'), and adds a clarifying qualifier ('without changing app files'). This distinguishes it clearly from sibling tools like apply_change_set and create_change_set. An agent knows exactly what action and scope this tool covers.

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

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

The description states the action ('discard a pending staged change set') but provides no explicit guidance on when to use it versus alternatives like apply_change_set or validate_change_set. It implies usage for discarding changes, but there are no explicit when-not or alternative selection cues, leaving the agent to infer the proper 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds no additional behavioral context such as authentication requirements, rate limits, or response format details beyond naming the metrics. It neither contradicts annotations nor enriches them, resulting in a neutral score.

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 states the action and the specific data returned. There is no fluff or redundant information; every word contributes to the 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?

The description covers the key return values (views, unique visitors, conversions, conversion rates) and the two required parameters are fully documented in the schema. While it doesn't mention potential nuances like time period or filtering, these are likely implied by the A/B test context. For a simple read tool with annotations covering safety, the description is nearly complete, though a note on returning aggregated historical stats would make it fully self-sufficient.

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

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

Schema description coverage is 100%, as both app_id and test_id have descriptions in the schema. The tool description does not add any extra semantic detail about the parameters (e.g., formats, how to locate them, or relationships), so it adds no value beyond the schema. Baseline 3 applies because the schema already documents both parameters.

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

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

The description states a specific verb (Get), a clear resource (A/B test stats), and enumerates exactly which metrics are returned (views, unique visitors, conversions, conversion rates). It distinguishes itself from sibling tools like create_ab_test, update_ab_test, and list_ab_tests by focusing on stats retrieval, leaving no ambiguity about its role.

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 purpose is self-evident as a read operation for a specific A/B test, so usage is implied. However, the description does not explicitly state when to use this tool over alternatives (e.g., list_ab_tests for listing tests, get_app_analytics for broader analytics) or mention any exclusions. It relies on the agent inferring from the sibling list.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it reveals that the response includes a 'next_step' that should be repeated to the user, and it describes the contents of the state. 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 is two sentences with zero wasted words. The key functional information is front-loaded, and the usage guidance is concise and actionable. Every sentence serves a purpose.

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

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

For a simple read-only tool with full schema coverage and safety annotations, the description is quite complete. It explains what state is read, when to call it, and hints at a 'next_step' in the response. It does not fully detail the response structure, but this is a minor gap given the tool's simplicity and the mention of next_step.

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 fully documents the only parameter, agent_id, with a clear description ('Optional: report only this agent's WhatsApp state.'). The tool description does not add any additional meaning about this parameter, so it relies entirely on the schema's coverage, which is already complete. 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 tool's purpose: reading the WhatsApp state of the connected account, listing specific aspects (owner's phone verification, platform numbers, conversation-agent routing). It uses a specific verb ('Read') and resource, and is easily distinguished from sibling tools like attach_agent_whatsapp and detach_agent_whatsapp because it is explicitly read-only.

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

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

Provides explicit guidance: 'Call this first whenever the user asks to talk to an agent on WhatsApp' and instructs to repeat its 'next_step'. This gives clear when-to-use context, but it does not explicitly mention when not to use it or name alternative tools, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by detailing the exact output categories (daily series, top pages, referrers, device split), which informs the agent what the response will contain. It does not contradict annotations and adds non-redundant information about behavior.

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

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

A single sentence that is well-structured, front-loading the main purpose ('Traffic analytics for an app's published site over a chosen window') followed by a concise list of returned metrics. No redundant words or filler; every phrase earns its place.

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

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

The description is quite complete for a read-only analytics tool. It tells the agent what metrics to expect, and the annotations cover safety. Minor gaps include not specifying ordering for 'top pages' or whether the daily series is per day in the window, but these are not critical for calling the tool correctly. Given the moderate complexity and no output schema, this is sufficiently 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 100% description coverage for both parameters: 'app_id' is described as 'The app ID' and 'days' includes the range and default. The description does not add any extra parameter-specific details, but with high schema coverage, a baseline of 3 is appropriate. No further compensation is needed.

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 ('get'), a specific resource ('app analytics'), and the scope ('published site over a chosen window'). It enumerates the exact metrics returned (total views, unique visitors, daily series, top pages, top referrers, device split), which strongly distinguishes it from sibling tools like get_app_detail or get_app_status.

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 context that the tool targets the published site over a chosen window, which implies when to use it (when analyzing traffic of the live site). However, it does not explicitly contrast it with alternatives like get_ab_test_stats or get_app_detail, nor does it give any exclusion criteria. The guidance is present but not explicit about 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the scope of returned data (entities, pages, settings, etc.), which goes beyond the annotations. It does not contradict annotations; it complements them with content coverage.

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 concise sentences: the first lists the tool's scope, the second gives the usage context. There is no fluff or repetition. The key information is front-loaded, and every word serves a purpose.

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

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

The tool is complex (aggregating many app components) and has no output schema. The description lists the major categories of data returned, which provides decent guidance. It does not specify the exact structure or whether pagination is involved, but for an introspection tool, the listed categories are likely sufficient for an agent to decide to call it. It's complete enough for effective selection.

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

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

The only parameter, app_id, is fully described in the schema with 'The app ID' (100% coverage). The description adds no additional parameter details. Per the rubric, with high schema coverage, a baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Deep introspection' with a clear resource ('an app') and enumerates its contents: entities, pages, settings, integrations, environment variables, and file structure. This clearly distinguishes it from more targeted siblings like get_app_files, get_pages, and get_entities, which cover only subsets.

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 a clear usage context: 'Use this to understand what an app contains before updating it.' This implies a proactive overview use case. However, it does not explicitly mention alternatives or when not to use it, though the existence of numerous narrower sibling tools suggests they exist. It's clear but not exhaustive.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds what data is returned (paths and byte sizes) but does not describe the structure of the file tree (e.g., hierarchy, recursion, inclusion of directories). No side effects are relevant, but more detail on the exact output shape would be helpful.

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, clear sentence that includes the verb, resource, and output specifics. No filler, front-loaded with the key action and result. Highly efficient for a simple getter.

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 getter with a single parameter and full schema coverage, the description is mostly sufficient. However, it leaves ambiguity about what 'file tree' means (full recursive structure vs. top-level listing) and does not clarify how it relates to read_app_files. Given the presence of sibling tools, a bit more context on the intended use would improve completeness.

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% (app_id described as 'The app ID'), so the schema already handles parameter documentation. The description adds no extra meaning about app_id beyond what the schema states, so baseline 3 is appropriate.

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

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

The description states a specific verb ('Get'), resource ('file tree for an app'), and the data returned ('paths and byte sizes'). This is clear and distinguishes it from tools like get_app_detail. However, it does not explicitly differentiate from the sibling read_app_files, which could be confused as similar in 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?

No guidance on when to use this tool vs. alternatives. The sibling list includes read_app_files and read_app_file, but the description does not clarify whether this is the right choice for listing file metadata vs. reading content. No exclusions or alternative routing 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 already declare readOnlyHint, idempotentHint, and destructiveHint, so the description is not burdened with those. It adds the behavioral nuance that results depend on publish and auth settings, which is useful context beyond the schema, but it does not mention error conditions or output structure. This is moderate added value.

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 sentence that front-loads the primary outcome ('Return editor, preview, published path...') but packs a lot of detail. It is efficient and not padded, maintaining good structure for quick scanning.

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 only one parameter, no output schema, and annotations covering safety, the description adequately explains what links are returned and the access dimension. It could specify the response structure more explicitly, but for a simple read-only fetch it is sufficiently 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 schema already documents app_id with a clear description ('The app ID'), and coverage is 100%. The tool description adds no additional information about the parameter, so it stays at the baseline of 3 without compensating for any 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 clearly states it returns multiple types of app links (editor, preview, published path, subdomain, custom-domain) plus access info, which is specific and informative. It does not explicitly contrast with siblings like get_preview_url, but the scope is distinct enough to be understood.

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 no guidance on when to use this tool versus alternatives such as get_preview_url or get_app_detail. It simply describes what it returns without clarifying use cases, prerequisites, or exclusions, leaving the agent to infer 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?

Annotations already declare the tool as readOnly, idempotent, and non-destructive, which the description aligns with. The description adds the 'recent' and 'server-side' qualifiers, which provide some context, but does not disclose whether events are paginated, sorted, or filtered. Given annotations cover the safety profile, a 3 is appropriate.

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

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

The description is a single, well-formed sentence with no redundancy. The core action and object are front-loaded, making it instantly 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 read tool with annotations covering safety, the description is adequate but incomplete. It omits details about the output structure, the meaning of 'recent' (time window), and any constraints on the limit parameter. With no output schema, some return format guidance would improve completeness.

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 app_id but not limit. The description does not clarify the meaning of limit (e.g., max count, default behavior) or the scope of 'recent'. Since schema coverage is only 50% and the description fails to compensate, parameter understanding is weak.

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 (read), resource (security audit events), and scope (for an app). It distinguishes the tool from generic getters like get_app_analytics, but does not explicitly differentiate from the closely named sibling get_app_security_context. Still, 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?

The description provides no guidance on when to use this tool versus alternatives such as get_app_security_context or get_app_status. There is no mention of prerequisites or exclusions. An agent must infer usage from the tool name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable context by stating the response excludes secrets and does not grant cross-app access, which informs the agent about data sensitivity and permission boundaries. This goes beyond the annotations and provides actionable behavioral guidance.

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 concise sentences that front-load the primary purpose and then state exclusions. Each sentence adds meaningful information without redundancy, making it highly efficient and easy to parse.

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 returns a complex security context object, and the description outlines the main components but lacks details on the response structure, field types, or how audit_limit behaves. Since there is no output schema and only partial parameter documentation, the description is not fully complete for an agent to predict the response shape or usage nuances.

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 mention either parameter. The schema provides a minimal description for app_id and none for audit_limit, leaving its meaning unclear. With 50% schema coverage, the description fails to compensate for the un-documented audit_limit parameter, which is a significant 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 clearly states the tool returns a safe security context for one owned app, listing specific components (owner id/email, collaborators, members, policies, audit entries). It explicitly notes it does not return secrets or grant access to other apps, which distinguishes it from broader app management tools. This is a specific verb+resource with clear scope and boundaries.

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 does not explicitly state when to use this tool over alternatives like get_app_security_audit or get_app_detail. It implies it's for owned apps and includes a warning about not granting access to other apps, but no direct comparison to sibling tools. This leaves usage context implicit rather than explicit.

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

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds useful content-scope context by listing what the response contains (files, published state, URL, active jobs), which is beyond the annotations. No contradictions, but it adds nothing about reach, pagination, size limits, or response shape.

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

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

A single front-loaded sentence with zero filler. The purpose leads immediately, and the component list (files, published state, URL, active jobs) earns every word by demarcating the tool's scope. Nothing could be trimmed without losing 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?

For a simple one-parameter, read-only tool with rich annotations and no output schema, the description is reasonably complete: it names the sole required parameter's purpose via the schema and lists the four return components. It could note the aggregate nature versus get_app_detail or describe the response structure, but these are minor against the tool's low 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?

Schema description coverage is 100% — the single parameter app_id is documented as 'The app ID' in the schema. The description adds no additional parameter meaning (format, origin, or examples), so it rests on the schema's documentation, matching the baseline for full 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 states a specific verb and resource ('Get app overview') and enumerates the returned components (files, published state, URL, active jobs), which clearly conveys a summary/aggregate tool. It distinguishes itself from the focused siblings like get_app_files and get_job_status by signaling it is an aggregate overview, though it does not explicitly name any alternative.

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

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

There is no guidance on when to use this overview tool versus the many overlapping siblings (get_app_detail, get_app_files, get_app_links, get_job_status, get_pages). The word 'overview' only implies a quick-summary use case; no exclusions or selection criteria are given, leaving the agent to infer 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds useful behavioral context by specifying that it returns 'pending certificate validation DNS records,' which is not in the annotations and helps the agent understand what actionable information is provided. This goes beyond the annotation baseline.

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, well-structured sentence that front-loads the core purpose. It contains no fluff, filler, or redundant information, and every word 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?

For a simple read-only getter with just two parameters and no output schema, the description provides sufficient context for an agent to understand what is returned at a high level. It does not detail the exact output structure, but given the simplicity of the tool and the annotations covering safety, nothing critical is missing.

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

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

Schema description coverage is 100% for both parameters (app_id and domain), so the schema already documents them fully. The description does not add additional meaning beyond what the schema provides, though it does mention the domain is a custom domain. This meets the baseline for high coverage without extra enrichment.

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 SSL/certificate status and pending certificate validation DNS records for the app custom domain. The verb 'Return' and specific resource make the purpose unambiguous, and it is distinct from sibling tools like get_domain_verification, which focuses on domain verification rather than SSL status.

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 clearly implies the tool is for retrieving SSL status, but it does not explicitly state when to use it versus the many related domain tools (e.g., check_domain_verification). There is no mention of when not to use it or alternatives, leaving the selection largely to inference from the name and description.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds value by specifying the exact return content ('exact DNS records and instructions') and its purpose (verification and routing), which gives the agent a clear expectation of the output. It does not contradict 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 a single, efficient sentence that front-loads the key action and resource. No fluff or redundant details. 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?

The description covers the essential purpose and what it returns, which is sufficient given the tool's simplicity and the annotations' coverage of safety. It lacks an output schema, but the description explicitly states what it returns. Minor omission: it doesn't mention that the output may vary depending on the domain parameter, but the schema already clarifies that behavior.

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

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

Schema description coverage is 100%: both parameters already have clear descriptions in the schema. The tool description does not add any additional semantics beyond what the schema provides. Baseline of 3 is appropriate when schema fully documents parameters.

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

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

The description states a specific verb ('Return') and resource ('exact DNS records and instructions') and the purpose ('to verify and route the app custom domain'). It clearly distinguishes from siblings like check_domain_verification (which likely checks status) and get_domain_ssl_status by focusing on the records and instructions needed for setup.

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: call this when you need the DNS records to verify and route a custom domain. However, it does not explicitly name alternatives or state when not to use it. There's no guidance on choosing between this and check_domain_verification or get_domain_ssl_status, leaving the agent to infer based on the name and description.

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 indicate readOnlyHint: true, idempotentHint: true, and destructiveHint: false, covering safety. The description adds that it returns record counts, which is a behavioral detail not in the schema, and mentions 'fields, types, and relationships', giving a sense of the payload. However, it doesn't disclose potential large response sizes or pagination behavior, which might be relevant for an app with many entities, but given the annotation coverage, the bar is lowered.

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

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

The description is concise: two sentences with no fluff. It front-loads the main action ('Get all entity schemas') and adds a useful detail (record counts) and content aspects. It's efficient, though it could have been slightly more specific about the output shape without adding much length.

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 simplicity of the tool (one parameter, no output schema, no nested objects), the description covers the core purpose and content. With annotations covering safety and idempotency, the description is adequate for correct invocation. It might be slightly incomplete regarding potential pagination or large result sets, but that's not critical for basic usage. The result format is not described, but since there's no output schema, a brief hint about the return structure could help, but it's not blocking.

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 only parameter 'app_id' is fully described in the schema with 'The app ID', giving 100% coverage. The description does not add clarity beyond what the schema provides; it repeats that it is for an app. Baseline is 3, and the description adds no special value here.

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

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

The description clearly states the tool retrieves all entity schemas for an app and includes record counts, adding detail about content ('fields, types, and relationships'). However, it could be more specific about the exact scope (e.g., whether it includes computed or related entities) and does not distinguish itself from sibling tools like 'create_entity_schema', 'update_entity_schema', or 'query_entity', though the read-only retrieval intent is clear from context.

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 entity schemas and counts but provides no explicit when-to-use or when-not-to-use guidance. It doesn't name alternatives like 'query_entity' (to fetch actual records) or 'get_entity_schema' (if it existed), leaving the agent to infer that this is a high-level metadata listing. The instruction 'for an app' gives some context, but there's no explicit exclusion of record-level operations.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the behavioral detail of returning the 'last 20' errors and emphasizes 'recent', which provides context beyond the structured annotations without contradicting them.

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 efficiently written in two short sentences with no filler. It front-loads the action and scope, and the second sentence adds a relevant use case. 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 read-only tool with no output schema and two well-documented params, the description provides enough context: what it does, the scope, and a use case. Annotations cover the safety profile, so nothing critical is missing for an agent to call it correctly.

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

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

Schema description coverage is 100% and both parameters (app_id, limit) have descriptions in the schema. The description does not add any meaning beyond what the schema already provides; it only mentions 'last 20' which mirrors the default value, so no extra value is added.

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 action ('Get'), the resource ('recent runtime errors'), and the scope ('for an app', 'last 20'). It distinguishes itself from sibling tools like get_app_status or get_app_analytics by focusing specifically on errors, so an agent can easily identify what it does.

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 phrase 'Useful for diagnosing issues before updating' provides a clear context for when to use this tool. While it doesn't explicitly mention exclusions or alternatives, given the tool's simplicity and the absence of a directly competing error-specific sibling, 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.

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds behavioral detail by listing what the tool returns ('status', 'progress events', 'result summary'), which goes beyond the annotations and helps the agent know what to expect from the call.

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 focused sentences: the first states the purpose and reference to preceding calls, the second details the return payload. All key information is front-loaded with zero 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?

Given its simplicity (single parameter, no output schema, read-only annotations), the description fully equips an agent to call it correctly: it tells when, what it returns, and the parameter source. No additional guidance is necessary.

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 job_id adequately documented as 'The job_id returned by create_app or update_app'. The tool description repeats this context but adds no deeper semantic detail beyond the schema baseline, so a 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 states a specific verb ('poll'), a specific resource ('status of an async generation job'), and the exact triggering context ('after create_app or update_app'). This distinguishes it from sibling tools like get_app_status by scoping it to job lifecycle rather than app state.

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

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

Explicitly states when to use the tool ('Use this after create_app or update_app to know when the job is done'), which is clear context. It doesn't spell out exclusions or alternatives, but the mention of the generating calls implicitly routes the agent. Meets 'clear context' but not full 'when-not/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?

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds the scope 'all pages', which implies no filtering, but does not elaborate on potential large result sets, pagination, or other behaviors. It is consistent with annotations but provides minimal extra context, so a 3 is appropriate.

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

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

The description is a single, concise sentence with no redundant words. It front-loads the key action and resource, and immediately states what is returned. It is perfectly sized for the tool's simplicity.

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

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

For a simple read-only tool with one parameter and no output schema, the description is nearly complete. It states what it returns (file paths and sizes) and covers the essence. The only minor gap is the lack of mention of pagination or result limits, but given the context and the explicit 'all pages', this is a minor omission. A 4 is justified.

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 app_id completely (100% coverage), including a description. The tool description does not add any extra meaning about the parameter beyond saying 'in an app', which aligns with the schema. Thus, schema documentation carries the burden, and the description adds no additional 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 action (Get) and resource (all pages in an app), and specifies return contents (file paths and sizes). This differentiates it from sibling tools like get_app_files or read_app_files by focusing specifically on pages. It is precise and 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?

The description does not provide any guidance on when to use this tool versus alternatives. It only states what it does without mentioning scenarios where it should be preferred, such as when needing page-specific data versus app-level files. No exclusions or pointers to siblings are given.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by enumerating the guide's contents, letting an agent know what to expect. It does not contradict annotations and adds contextual detail beyond the structured fields.

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

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

The description is two sentences, with the primary action and onboarding context front-loaded. Every word earns its place; it is concise without sacrificing informative 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?

With zero required parameters, no output schema, and an onboarding guide as the deliverable, the description fully covers what an agent needs to know: when to call (start of session), what the guide contains, and that optional parameters refine it. 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 description coverage is 100%; each parameter (app_id, sections, task_type) has a meaningful description in the schema. The tool description itself does not add semantics beyond what the schema already provides, so it meets the baseline of 3 for high-coverage cases.

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 a machine-readable Fine Structure / FSe2 guide for AI agents, listing the specific topics covered (app files, entities, safe edit workflows, validation, publishing, A/B testing, secrets, platform rules). It uses a specific verb (return) and resource (guide), and the 'at the start of an MCP session' context differentiates it from siblings like get_recommended_workflow.

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 to call this at the start of an MCP session, giving clear when-to-use guidance. It does not mention when not to use it or name alternative tools, so it misses the exclusion aspect that would earn a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description merely says 'Return,' which is consistent and adds no extra behavioral details. It does not contradict annotations, but it also doesn't add value beyond what annotations provide, so a baseline score of 3 is appropriate.

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

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

The description is a single, concise sentence with no fluff. It front-loads the verb 'Return' and clearly states what is returned. Every word adds value, making it appropriately sized for a simple read-only tool.

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 getter with one parameter and no output schema, the description adequately explains the tool's purpose by specifying that it returns editor preview and published/public URLs. It doesn't detail the return format or error cases, but for a read-only URL fetcher, this is sufficient. The presence of siblings like get_app_links makes the description more complete than a generic 'get URLs' description, earning a 4.

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 app_id already described as 'The app ID.' The tool description does not add any additional meaning about the parameter, such as format, validation, or how it influences the result. Since the schema fully covers the parameter, a baseline score of 3 is correct; the description adds no extra clarity.

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 'Return' and the resource 'editor preview and published/public URLs for an app.' It is specific about what is returned, distinguishing this from a generic 'get links' tool by specifying preview and public URLs. However, it does not explicitly contrast with siblings like get_app_links, so it doesn't fully eliminate ambiguity, but the purpose is clear.

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 no guidance on when to use this tool versus alternatives. There is no mention of alternatives, exclusions, or context for when this tool is preferable. Given that siblings like get_app_links, inspect_preview, and get_app_detail exist, the description offers no help in selecting this specific 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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, which establishes a safe, read-only, idempotent operation. The description adds a useful behavior detail: when app_id is provided, the workflow includes a safe app context summary. This is beyond what annotations convey. It doesn't disclose output format, but for a planning tool that's acceptable given the safety profile.

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 with zero redundancy. It leads with the core purpose, then immediately provides the usage contexts. Every word adds value, and it is efficiently 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?

The tool is simple: zero required parameters, all optional, and a well-defined enum for task_type. The description covers what it does and when to use it. While it doesn't describe the return format or behavior for 'unknown' task_type, the schema defaults cover that, and the agent can infer the output is a sequence. It's complete enough for correct usage, but a bit more detail on output expectation would make it a 5.

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% — each parameter has a description, and task_type has a full enum. The tool description does not add extra semantics beyond what the schema already provides (e.g., it doesn't explain how goal affects the output or what the 'safe app context summary' means). Since the schema already documents parameters thoroughly, a baseline of 3 is appropriate; no improvement from the description.

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 action ('Return the recommended MCP tool sequence') and a specific resource ('for a task type'). It also lists concrete use cases (creating apps, editing files, seeding data, etc.), which differentiates it from sibling tools like get_platform_guide or get_app_status. An agent can immediately understand what this tool does and when it applies.

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 'Use this before creating apps, editing files, seeding data, publishing, setting up A/B tests, restoring versions, or configuring secrets/integrations.' This gives clear positive contexts. It doesn't explicitly state when not to use it or name alternatives, but the directive use-before list is strong guidance. The lack of exclusions or named alternatives keeps it from a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds useful context about what data is returned (URLs, errors, clickable candidates, pages, live-browser availability), which goes beyond the annotations. However, it does not disclose the exact structure of the response or mention error handling when the app_id is invalid. Given the annotation coverage, a 3 is appropriate – the description adds value but is not rich in behavioral detail.

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 sentence that front-loads the core purpose and then concisely lists the returned content. Every word earns its place; there is no fluff, no redundancy, and it is easily 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?

The tool has no output schema, so the description is the only source for what the agent receives. It lists the categories of returned data but does not explain the structure (e.g., object vs array), how parameters like route or auth_as affect the result, or what 'explicit live-browser availability' means in practice. While not incomplete enough to be unusable, an agent would benefit from more detail on parameters and response format. This is adequate but leaves 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 descriptions cover 100% of parameters, so the schema already documents each parameter's basic meaning. The tool description does not add additional semantics for parameters like route, auth_as, or auth_as_role, so it provides no extra value beyond the schema. With full coverage, the baseline of 3 is correct.

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

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

The description clearly states the tool returns server-side preview context and enumerates the specific elements it includes (URLs, errors, clickable candidates, pages, live-browser availability). The verb 'return' and the resource are specific, distinguishing it from siblings like get_preview_url or get_pages. Minor ambiguity around 'static clickable candidates' but overall purpose is clear.

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 no guidance on when to use this tool versus alternatives. It does not mention any conditions, choose-this-over-that logic, or exclusions. Sibling tools like get_preview_url, get_pages, and get_errors overlap in scope, so the absence of usage guidance is a notable gap. The agent is left to infer when to pick this.

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 indicate a mutating, non-idempotent operation. The description adds crucial behavioral detail: it never generates a password and explains the security rationale (avoiding live credentials in the transcript). This goes beyond annotations and helps the agent understand side-effects and password handling without contradicting the structured metadata.

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 deliver purpose, exclusions, and a password requirement with justification. Every sentence earns its place, with the most critical constraint (password) front-loaded. No redundancy or fluff.

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

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

For a mutation tool with no output schema and 5 parameters, the description covers the core purpose, exclusions, and a key security constraint. It does not specify success/error return values or exact allowed roles, but given the absence of an output schema and the presence of sibling tools for listing/removal, this is sufficiently complete for an agent to call it correctly.

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

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

Schema coverage is 80%, so the baseline is 3. The description adds meaningful parameter-level info: it explicitly forbids the owner role, which directly informs the 'role' parameter, and clarifies that 'password' is owner-chosen and never echoed. This exceeds schema descriptions, though it does not enumerate all allowed roles beyond the schema's examples.

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 (provision) and resource (generated-app runtime member) and explicitly distinguishes from 'Studio collaborator', helping differentiate from sibling tools like list_app_members or update_app_member_role. It also notes the owner role restriction, adding precision. The term 'generated-app' is slightly niche but the overall purpose is clear.

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 'when not' guidance (not for Studio collaborator) and an actionable operational step (ask the account owner for the password). It does not name specific alternative tools, but the exclusions and required-password instruction give enough context for an agent to decide when to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds no additional behavioral context such as rate limits, pagination, or result format. It is consistent with annotations but does not enhance them.

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

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

One concise sentence with the action verb and scope front-loaded, no unnecessary words, making it efficient.

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 list tool with one parameter and no output schema, the description adequately captures what the tool does. However, it does not mention the expected return format or any limitations (e.g., pagination), but given the simplicity, it is largely 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 schema describes app_id as 'The app ID,' and the description mentions 'for an app,' which aligns. Since schema coverage is 100%, the description does not need to add extra semantics; it merely confirms the parameter's role, which is already clear.

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 'List' and resource 'platform A/B tests' scoped to an app. It clearly distinguishes from siblings like create_ab_test, update_ab_test, and get_ab_test_stats by focusing on listing all tests rather than individual operations.

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 indicates that it lists tests for an app but does not explicitly mention when to use it versus related tools like get_ab_test_stats or create_ab_test. Context is clear, but no exclusions or alternatives are provided, leaving usage to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the specific fields returned, which is behaviorally useful and goes beyond annotations. It does not contradict annotations and does not conceal any side effects, as this is a simple read 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?

The description is a single, well-structured sentence that front-loads the action and lists the output fields. No wasted words or redundant information. It is ideal in length for the tool's simplicity.

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 there is no output schema, the description explicitly enumerates the fields returned, which is crucial for an AI agent. It also mentions the optional filter parameter and its purpose. It does not address pagination or limits, but for a simple list tool with one optional parameter, the information is sufficiently complete for correct invocation.

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

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

The single parameter app_id is fully described in the schema as 'Optional filter by attached app' (schema coverage 100%). The description does not add any extra semantic detail about the parameter beyond what the schema provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description states a specific verb ('List') and resource ('AI agents on the user's account'), and enumerates the returned fields (id, name, role, status, FineMail address). This clearly distinguishes it from siblings like list_agent_tasks or list_apps, which target different entities.

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 purpose is immediately clear: this is the tool for listing agents. While it does not explicitly name alternatives or exclusions, the context (sibling tools like create_agent, list_agent_tasks) implicitly defines its scope. There is no ambiguity about when to use it, but it stops short of explicit when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds value by specifying the returned fields (schedule, status, next_run_at) and the scope (agent or whole account), which helps the agent understand what data to expect. It does not mention pagination or edge cases, but given annotations, the extra context is sufficient.

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

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

The description is a single, concise sentence that front-loads the main action and scope. It includes the key returned fields without extraneous detail. 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 list tool with optional parameters and no output schema, the description covers the purpose, scope, and some return fields. It does not explicitly state the default limit (50) or that results are paginated, but those are in the schema. The mention of 'schedule, status and next_run_at' gives a good sense of the output. It is adequate for an agent to call it effectively.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema. The description does not add parameter-specific details beyond mentioning the scope (agent_id is implied via 'one agent'), but does not describe the limit or status filters beyond what schema already states. Since the schema carries the full parameter documentation, a baseline of 3 is appropriate.

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

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

The description clearly states a specific verb ('List') and resource ('scheduled tasks') with an explicit scope ('for one agent or the whole account'). It also indicates the fields returned (schedule, status, next_run_at). This distinguishes it from sibling tools like schedule_agent_task (which creates tasks) and list_agents (which lists agents).

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 implicitly conveys when to use the tool—when you need to view scheduled tasks—but it does not explicitly name alternatives or state when not to use it. It does not mention that it is read-only or that it is for querying rather than modifying. Since annotations already cover safety, the lack of explicit routing to siblings is a minor gap. The grounds are implied but not stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by enumerating the fields returned, which informs the agent of the output scope. However, it does not disclose any additional behavioral traits such as pagination, authentication requirements, or rate limits, which are not covered by annotations.

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

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

A single, focused sentence that front-loads the action ('List') and then concisely enumerates the scope. No wasted words, and every element adds clarity. The structure makes it easy to scan and understand.

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 parameter, no output schema, and the description enumerates the exact fields returned. This is sufficient for an agent to invoke it correctly and anticipate the response shape. It could be slightly more explicit about the return format (e.g., whether it returns a single object or array), but the listing nature suggests an array of domain-related info. Overall, it is nearly complete for a list operation.

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 only parameter, app_id, has a schema description ('The app ID') that fully covers its meaning (100% schema coverage). The description does not add any additional context about the parameter, such as format or usage. Since the schema already provides adequate semantics, 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 ('List') and resource ('an app's platform path, subdomain, and configured custom domain') and enumerates the specific attributes returned (verification, SSL, primary-domain, redirect, publish, login-gating status). This clearly distinguishes it from sibling tools like get_domain_ssl_status or configure_domain_redirects, which target narrower aspects.

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 does not explicitly state when to prefer this tool over alternatives. It implies a comprehensive overview use case, but unlike the high-calibration example, it does not name sibling tools or provide exclusion criteria. An agent would need to infer from the context that this is the go-to for a full domain status snapshot.

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, idempotentHint, and destructiveHint, covering the safety profile. The description adds useful scope context about 'generated-app runtime users' but does not disclose return format, pagination, or other behavioral details. With annotations carrying the safety burden, the added context justifies a 3.

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

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

Two concise sentences with no wasted words. The purpose is stated first, and the distinguishing note is placed second. 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 single-parameter read-only list operation, the description covers the essential scope and distinguishes it from collaborators. It doesn't mention return shape or pagination, but given the simplicity and annotation coverage, it is largely complete. A 4 reflects that minor gap.

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

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

The single parameter app_id is fully described in the schema with 'The app ID' at 100% coverage. The description does not add any additional param semantics or format details, 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 clearly states the tool lists 'generated-app runtime users/members' for an app, a specific verb and resource. It also distinguishes this from 'Studio project collaborators', helping differentiate from related tools like invite_app_member or remove_app_member.

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 context by specifying this is separate from Studio project collaborators, implying when not to use it. However, it does not explicitly name alternatives or describe conditions for choosing this tool over other member-related tools, though the distinction gives a helpful 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context about pagination ('Returns up to limit apps per call plus the total count; page with offset') and the total count, which goes beyond the annotations without contradicting them.

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

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

Two concise sentences: the first establishes purpose, scope, and ordering; the second explains return behavior and pagination. No wasted words, and 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 simple parameters, no output schema, and strong annotations, the description covers everything needed: purpose, scope, ordering, pagination, and response summary (limit + total). It is complete for correct invocation.

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

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

Schema description coverage is 100%, so parameters are documented. The description enhances the schema by explaining how limit and offset interact ('page with offset when the account has more'), which adds usage semantics beyond the individual field 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 states a specific verb ('List'), resource ('applications'), and scope ('owned by the authenticated user') with ordering ('newest activity first'). It clearly distinguishes from sibling list_* tools that target other resources (agents, AB tests, domains, etc.).

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 for when to use it (listing apps owned by the user) and explains pagination with offset. However, it does not explicitly mention alternatives or when not to use it, though the scope implicitly differentiates it from sibling list tools.

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

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

The annotations already declare readOnlyHint and idempotentHint, but the description adds valuable behavioral context by promising that tokens/secrets are never returned. This is beyond what the structured annotations provide and clarifies the safety of the operation, though it does not detail the exact return format or pagination behavior.

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

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

The description is a single, well-structured sentence that front-loads the action and resource while also adding the safety disclaimer. Every word contributes meaning, with no filler or redundant content.

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

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

Given the simplicity of the tool (one parameter, no output schema), the description adequately covers the core behavior, especially the important detail about never returning secrets. It could be more explicit about whether 'supported integrations' includes both connected and unconnected ones, but overall it provides enough context for correct invocation.

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

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

The input schema already documents app_id with a basic description ('The app ID'), and coverage is 100%. The tool description does not add any additional parameter-specific meaning or elaboration beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool lists supported integrations and safe metadata for an app, using a specific verb and resource. It also distinguishes itself from other tools by noting that tokens/secrets are never returned, which helps differentiate it from configuration or write tools like configure_integration.

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?

While the description implies a read-only listing use case (e.g., 'safe metadata', 'tokens/secrets are never returned'), it does not explicitly mention when to use this tool over alternatives like configure_integration. There is no direct comparison or exclusion of other sibling tools, so the agent must infer the usage 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds behavioral context by specifying that versions are 'restorable' and 'including versions created by MCP writes,' which goes beyond the structured data. However, it does not detail pagination, ordering, or return format, so the description adds moderate but not rich behavioral insight.

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 with zero wasted words. It states the action, resource, scope, and the key distinguishing trait (MCP writes) efficiently, making it easy for an agent to parse quickly.

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 list tool with one parameter and no output schema, the description is sufficient for an agent to identify the operation. It clearly states the purpose and scope, and the 'restorable' and 'MCP writes' details provide necessary context. The lack of explicit return-format information is a minor gap given the tool's simplicity, but not critical.

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 100% coverage of the sole parameter (app_id) with a description of 'The app ID.' The tool description does not add any additional parameter details, so the schema already does the heavy lifting. Baseline 3 is appropriate since the parameter is fully documented structurally.

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 clear action (list) and resource (restorable Saved Versions) with a specific scope (for an app). It also distinguishes itself by noting it includes versions created by MCP writes, setting it apart from related tools like compare_saved_versions or restore_file_from_version without ambiguity.

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 that this is a listing operation for a specific app, but it does not explicitly say when to use this tool versus alternatives (e.g., compare_saved_versions). The inclusion of 'restorable' and 'MCP writes' implies a broad listing use case, but there is no explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds a valuable behavioral note: 'Secret values are never returned.' This goes beyond the safety hints to specify output content, helping the agent understand that the tool only provides names, not sensitive values. No contradictions 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?

Two short sentences with zero waste. The first sentence states the action and resource, and the second sentence adds a critical constraint. Information is front-loaded, making it easy for an agent to parse quickly.

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

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

For a simple read-only list tool with one parameter and no output schema, the description fully conveys what the tool does and what it returns (names). It does not mention pagination or ordering, but these are likely not critical for this basic operation. The behavior is well covered given the simplicity and annotation support.

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

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

Schema coverage is 100% for the single parameter app_id, which is described as 'The app ID'. The description mentions 'for an app' which reinforces the parameter's role but adds no additional format, constraints, or semantics beyond the schema. Baseline score of 3 is appropriate 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?

States a specific verb (List) and resource (secret key names for an app) and explicitly notes that values are never returned. This clearly distinguishes it from set_secret and delete_secret in the sibling list, leaving no ambiguity about what the tool does.

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?

Implicitly clear from the name and description that it is used to retrieve secret key names. The added caveat that values are never returned implies it should be used when only names are needed, but it doesn't explicitly reference alternatives or exclusions. Given the tool's simplicity and the obvious contrast with set/delete operations, this is adequate context, though not explicit 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 are all false (readOnlyHint, idempotentHint, destructiveHint), so they provide no behavioral signals. The description adds meaningful disclosure: it creates a Saved Version before modification, claims to be safer, and links to API documentation for path conventions. These go beyond the schema and 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?

Three concise sentences: action, safety/comparison, and path guidance. No filler. The key information is front-loaded, and the documentation link is placed last without disrupting the core message.

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 mutation tool with no output schema and 5 parameters, the description covers purpose, when to use it, a key side effect (Saved Version), and points to external docs for path details. It doesn't address error handling or replace_all behavior, but those are covered by schema or less critical for invocation. Overall, it's sufficiently complete for an agent to decide and call 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%, with each parameter described. The description's reference to 'replacing exact text' reinforces old_text/new_text, but this is redundant with schema. The only value-add is the path documentation link, which is more about API conventions than parameter semantics. Since schema already covers everything, 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 precise verb and object: 'Patch one file by replacing exact text.' It immediately distinguishes itself from sibling tools like write_app_file by calling out 'Safer than full overwrite for targeted edits,' which positions it as the refined alternative. The resource (app file) and operation (patch) are unambiguous.

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

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

It states when to use this tool: 'for targeted edits' and contrasts with 'full overwrite,' which clearly implies using write_app_file for wholesale rewrites. It also mentions the Saved Version creation, which may influence choice. It doesn't explicitly name alternatives, but the guidance is 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?

Annotations already declare readOnlyHint=false, not destructiveHint=false, and openWorldHint=true, which gives some safety context. The description adds that it 'freezes current state' (implying a snapshot) and 'makes it live,' which is useful. However, it does not explain side effects like whether previous published versions are replaced or how versioning works. The addition is moderate but not rich enough for a 4.

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 with no filler. The core action is front-loaded, and the second sentence efficiently covers the access configuration. Every word earns its place, making this highly concise and clear.

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

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

Given the straightforward nature of the tool and that all parameters are documented in the schema, the description is largely complete. It clearly states what publishing does. The absence of an output schema means return values are not required. Minor gaps include not specifying prerequisites (e.g., app must exist) or post-publish steps, but these are not critical for this operation.

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

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

Schema coverage is 100% for all 4 parameters, so the description carries little additional weight. The description's mention of 'public URL is open, app-login gated, private, or inferred' matches the access_mode enum, but it does not add detail beyond what the schema descriptions already provide for make_public and auth_required. 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 action: 'Publish an app' and specifies what that entails: 'freeze current state and make it live at a URL.' It also mentions configuring access modes, which aligns with the access_mode parameter. This distinguishes it from sibling tools like create_app and update_app by focusing on the deployment/live stage.

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

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

The description implies the tool is used after creating/updating an app but does not explicitly say when to use it over alternatives. It lacks guidance such as 'use this after building your app to deploy it' or 'use update_app to modify the working version instead.' The reader must infer that publishing is the appropriate final step.

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

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

The annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lowered. The description adds value by clarifying that filters are 'exact-match' and that the query is for 'one entity', which informs expected behavior (no fuzzy search, scoped to a single entity type). This is contextual detail beyond the annotations, though it does not describe pagination or return format.

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

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

The description is a single, efficient sentence that front-loads the verb and resource. There is no filler or repetition. Every part earns its place by conveying action, scope, and a key behavior (exact-match) in minimal words.

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

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

Given the tool has 6 parameters (2 required) and no output schema, the description provides the core purpose but omits details like the return structure (probably a list of records) and how filters interact with nesting (filters is an object). The schema covers parameter types, but without an output schema the agent might benefit from a note on the response. The description is adequate for a simple query tool but not fully 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 all six parameters have their own descriptions in the schema. The tool description mentions 'exact-match filters' which echoes the filters parameter's schema description but does not add new semantics. With full coverage, the baseline is 3, and the description does not exceed that.

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 action (Query), the resource (app data records for one entity), and the optional capability (exact-match filters). It is specific enough to distinguish from mutation siblings like create_entity_records or delete_entity_records, and from get_entities which likely lists entities rather than records. It is not a tautology and uses a precise verb.

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 when to use this tool (to query records of a single entity) but does not explicitly state when not to use it or mention alternatives. For instance, it does not say 'use get_entities to list entities' or 'use update_entity_records to modify'. An agent must infer the appropriate sibling based on context, so guidance is adequate but not explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the path-format context (Fine Structure app file API, external docs), which is useful. However, it does not disclose truncation behavior implied by the max_chars default, non-existent-file handling, or return shape. With annotations carrying the safety burden, a 3 is appropriate.

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

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

Two sentences with no filler; the primary purpose is front-loaded and the path-API pointer is a single adjunct clause afterward. The only minor inefficiency is that the external-docs link could arguably be shortened, but the sentence count and ordering are economical.

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

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

Adequate for a simple single-file read tool whose annotations cover the safety profile. It lacks an output schema and does not describe error behavior, truncation, or response format; it defers path semantics to an external doc. Acceptable but not richly complete for an agent that must call it correctly.

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

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

Schema coverage is 100%: path, app_id, and max_chars are all self-describing in the schema. The description adds nothing beyond 'one source file' that isn't already in the property definitions, so it sits at 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?

States a specific verb-resource pair ('Read one source file from an app's virtual filesystem') and deliberately emphasizes 'one', which differentiates it from the sibling read_app_files. The path-API reference further pins down exactly what kind of file is targeted.

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

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

The 'one source file' phrasing implies a contrast with the plural sibling read_app_files, but the description never explicitly says when to prefer this tool over read_app_files, write_app_file, or patch_app_file. Usage context is implied rather than stated, so an agent must infer the boundary.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds the external documentation link but does not disclose behavior such as truncation (max_chars_per_file), error handling, or response format. It provides minimal incremental transparency 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 concise: one functional sentence and one reference link. It is front-loaded with the action and resource. The external link is useful but could be integrated more naturally; nevertheless, it is efficient 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?

Given the read-only nature, annotations cover safety, and the schema documents parameters, the description is adequate but not complete. It lacks details about return content, handling of missing files, or the effect of max_chars_per_file. It points to external docs but does not summarize key behavior. For a batch read tool, this is a moderate gap.

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