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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds meaningful behavior beyond that: 'Costs are fetched once and aggregated locally', 'total_cost always covers every row in range, even when groups is cut to top_n', and costs are strings with 4 decimals. 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?

Long but tightly organized: purpose, example-driven usage, workspace-wide caveat, Args list, and Returns. For a tool with 10 parameters, the length is justified and every sentence adds operational value; no filler or repetition.

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

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

Covers all 10 optional parameters, return shape, cost formatting, date-range edge cases, and view-specific explanation behavior. The description is complete enough for an agent to invoke this tool correctly without external documentation, even with an output schema present.

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

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

Schema description coverage is 0%, but the description documents every parameter: view values, period named ranges, start/end inclusivity, resolution alternatives, timezone requirements, app filtering, environment scoping, top_n default, and tag_names format. This fully compensates for the schema's lack of property 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?

States a specific verb and resource ('Break down what the workspace is spending ... modal billing') and enumerates distinct views. It is unambiguous and clearly differentiated from sibling tools like deploy, run, logs, and resource management, none of which cover cost analytics.

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 common-question mappings ('what is my costliest app?' -> view="by_app", period="this month"') and explains scope ('Billing is workspace-wide... use environment to narrow it after the fact'). This gives an agent concrete decision rules for selecting the right view and parameters.

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 idempotentHint=false, so the agent knows deployment is a mutating operation. The description adds useful context by stating that deployed endpoints persist and that returned URLs are live shareable links. It does not disclose what can be overwritten or replaced during deployment, which would have strengthened transparency given the destructive hint.

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

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

The description is compact and well-structured: a one-sentence purpose with the most important behavioral fact, followed by a succinct argument list and a return summary. Every sentence earns its place and there is no filler or repetition of schema defaults.

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 six parameters, an output schema, and annotations, the description covers the key call-time prerequisites, parameter semantics, and return fields. It could mention failure/conflict behavior or rollback semantics, but the output schema and annotations already cover safety and return structure, so the description is reasonably complete.

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

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

Schema description coverage is 0%, so the description carries the explanatory burden for parameters. It documents all six arguments, including the absolute path precondition (uv + modal in virtualenv), the mapping of name/tag to `--name`/`--tag`, the valid strategy values, and stream_logs behavior. It could add more detail on env naming or tag format, but it already adds substantial meaning beyond the raw schema.

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

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

The description uses a specific verb and resource: 'Deploy a Modal app', and reinforces it with the underlying command `modal deploy`. It also distinguishes deployment from ephemeral execution by noting that endpoints persist after the call returns. However, it does not explicitly contrast itself with siblings like run_modal_app or manage_modal_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 implies persistent deployment through the phrase 'endpoints persist after this returns', but it gives no explicit guidance on when to choose deploy over run_modal_app or manage_modal_app. There are no stated exclusions, prerequisites beyond the app's directory, or alternative tools to consider.

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 mark readOnly, idempotent, and non-destructive, and the description adds genuinely new behavior knowledge beyond those: only stdout/stderr/system streams are covered, dashboard crash events never appear, `since` without `tail` fetches every entry in range, and returns a `truncated`/`output_capped` flag. This is the kind of context agents need to avoid misreading results.

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

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

The description is long, but for a 10-parameter tool with subtle behaviors, every sentence adds necessary information. It is front-loaded with purpose and direction, uses a clean Args list, and closes with the Returns shape. No filler or repeated schema details.

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 10 parameters and an output schema, this description provides crucial contextual constraints: volume pitfalls, stream coverage, crash-event exclusion, defaults, maximum bounds (35 days, tail 20000), and return flag meanings (truncated, output_capped). It is complete enough to invoke correctly without clicking outside docs.

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

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

Schema description coverage is 0%, so the description carries the entire burden for parameter semantics. It fully compensates by explaining identifier formats ('my-app', 'ap-...', 'ta-...'), the `target` auto resolution logic, `timeout_seconds` default, environment scope, ISO/relative and max 35 days for `since`/`until`, `tail` max, allowed sources, `follow` behavior, and `timestamps`. Every parameter in the schema is addressed meaningfully.

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

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

The description opens with a specific verb and resource ('Fetch logs for an app or container') and maps it to the underlying CLI commands. It explicitly differentiates itself from the sibling search_modal_logs by contrasting raw logs with matches plus surrounding context, so an agent can tell them apart immediately.

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 not to use this tool: 'To find where something went wrong, prefer search_modal_logs... instead of a raw tail.' It also excludes crash events, which is a clear boundary for agent decision-making. This is explicit when/when-not guidance plus an alternative.

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 goes well beyond the annotations by disclosing that a call starts remote compute, costs money, takes tens of seconds, and may trigger an image build on first run. It also explains the probe mechanism and assures that values never leave the container. These are critical behavioral traits not captured by readOnlyHint=false or destructiveHint=false. There is 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?

Although the description is long, it is front-loaded with the most critical information (keys only, not values) and the cost warning. The explanation of why no API exists, the specifically scoped probe detail, and the per-parameter Args all earn their place. The structure is clean and skimmable.

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 return value semantics even beyond the output schema, explaining filtered vs unfiltered results. It also addresses cost, latency, prerequisites, alternatives, and parameter provenance. For a tool with remote side effects and unusual constraints, nothing important 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?

With schema description coverage at 0%, the description fully compensates via an Args section. Each parameter is explained: secret_name's source, env's purpose, image's optionality and recommended fallback, and timeout_seconds' default and meaning. This addresses the gaps left by the bare 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 opens with a specific action and scope: 'List the KEY NAMES inside a Modal secret — never the values.' It clearly names the resource and differentiates this tool from sibling tools like list_modal_resources and manage_modal_secret by emphasizing it inspects secret contents, not resource existence or management.

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

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

The description explicitly states when to use the tool versus alternatives: 'use list_modal_resources(resource="secrets") to see which secrets exist, and reach for this only when you need to know what is inside one.' It also warns that this is 'not a free lookup' and should be used sparingly, giving clear decision 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 non-destructive behavior, and the description adds substantial behavioral context beyond that: 200-entry cap with omitted_items, the return shape, that secret values are never returned, and that env is ignored for 'environments'/'profile'. This fully discloses what happens when the tool is invoked.

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 detailed yet tightly structured with a front-loaded purpose line and a bulleted resource list. Every sentence adds operational value; no filler or redundant restatement of the name/schema exists.

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 broad read-only lookup tool, the description covers purpose, all parameter behaviors, return format, pagination truncation, and caveats like secret value redaction. An agent has enough context to select the right resource and correctly interpret results without opening the output schema.

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

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

Schema description coverage is 0%, but the description compensates completely by documenting every parameter: the full set of resource enum values, the polymorphic meaning of name, the path default, and when env applies. It adds meaning far beyond the raw schema properties.

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

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

The description opens with a specific verb and resource ('Read-only lookup of everything in the Modal account') and enumerates eight clearly differentiated resource types. It distinguishes this discovery tool from the sibling action tools by positioning it as the starting point to find identifiers those tools consume.

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 'Start here to find the app name, container ID or volume name that the other tools take,' and each resource option includes its intended use, such as using 'app_history' to pick a version for manage_modal_app(action='rollback'). It also gives exclusions, e.g. secrets return names only and env is ignored for certain resources.

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 mark destructiveHint=true, readOnlyHint=false, idempotentHint=false. The description adds concrete behavioral detail: stop 'shut the app down, ending web endpoints' and rollback 'restore a previous deployment,' plus the warning that both actions affect live traffic. This goes beyond the structured hints.

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 compact: an opening one-line summary, a tidy Args list, and a Returns line. There is no redundant prose, and the live-traffic warning is front-loaded for safety.

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 tool's purpose, both actions, all four parameters, return shape ({message, stdout, stderr} or {error}), and a cross-reference to list valid rollback targets. It doesn't discuss failure cases or reversibility, but output schema and destructive annotations cover part of that, making this adequate.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning. It explains action with both permitted values, app_identifier with name/ID formats, version with omission semantics and a pointer to list_modal_resources, and env as the Modal environment to target. The env entry is brief, but every parameter receives usable semantics.

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 'Change a deployed app's state,' naming a specific verb and resource, then enumerates two concrete actions (stop and rollback) with their effects. This clearly distinguishes it from siblings like deploy_modal_app or run_modal_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?

It states that both actions affect live traffic, framing when this tool is relevant, and explicitly directs users to list_modal_resources(resource='app_history', name=...) to find valid versions. It does not list exclusions vs. deploy/run, but the action-specific guidance is strong 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?

Beyond the destructiveHint annotation, it discloses that stop cancels and reschedules in-flight inputs, that exec is equivalent to SSH, and that container IDs are environment-unique so no env arg is needed. This meaningfully surfaces risk and runtime behavior the agent could not infer from annotations alone.

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

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

The description is front-loaded with what the tool does, then organized as Args/Returns. Every sentence adds value, including examples, defaults, and the SSH warning, with no 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 tool with two modes, four parameters, and meaningful destructive/execution risk, the description covers inputs, behavior, risks, ID discovery, and return shapes. The output schema is also available, but the description already explains exec and stop return structures.

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?

With 0% schema description coverage, the description carries full parameter documentation: action values, container_id format ('ta-...'), command shape for exec, and timeout_seconds semantics with default. It fully compensates for the schema's bare property definitions.

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

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

The description opens with 'Act on one running container' and immediately enumerates the two concrete actions, 'exec' and 'stop', with exact CLI commands. This clearly distinguishes the tool from sibling app/volume/log tools by resource type and operation.

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 tells the agent to discover container IDs via list_modal_resources(resource="containers"), and warns that exec is 'arbitrary remote code execution... not a lookup.' This is clear, practical guidance, though it doesn't explicitly contrast every sibling tool such as manage_modal_app or get_modal_logs.

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 mark the tool as destructive and not read-only, and the description aligns with those flags. It adds valuable context by stating that values are never readable and are redacted from every returned field, including error fields, preventing transcript leaks.

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 tight and well-structured: a one-line purpose, a critical security note, a compact Args list, and a return-shape line. Every sentence adds useful information and no space is wasted.

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

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

Given the tool's complexity, an output schema exists, and the description covers all parameters, the create/delete distinction, file-based alternatives, overwrite behavior, environment targeting, and security-redaction behavior. Nothing essential is missing 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 0%, so the description carries the full burden for all seven parameters. It explains action, secret_name, key_values, from_dotenv/from_json, force, and env, including which parameters apply to 'create' and the shape of key_values.

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 or delete a secret,' naming the specific verb and resource. It also distinguishes itself from the listing path by directing users to list_modal_resources(resource='secrets'), making its scope unmistakable.

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

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

The description explicitly tells users to use list_modal_resources for listing secret names, which is the main alternative. It does not exhaustively enumerate when to choose inspect_modal_secret or other siblings, but the create/delete scope is clear enough for appropriate routing.

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 'removes the volume and ALL its data — irreversible' for the delete action, and by disclosing the return format '{message, stdout, stderr} or {error}'. These details enrich the behavioral picture beyond what structured hints provide, though it could mention reversibility of create/rename or permission requirements.

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 efficient: a one-line summary, a sibling-routing sentence, a concise Args block, and a Returns line. It is front-loaded with purpose and the most important caveat (irreversibility) appears in the action list. Slightly verbose with the 'Returns' line but not bloated; 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?

Given the 4 parameters, existence of an output schema, and destructive annotations, the description covers the essentials: action semantics, parameter requirements, environment constraint, and return type. It could be more explicit about what 'create' does regarding naming (e.g., that volume_name serves as the new name) and whether rename affects existing file references, but overall it is sufficiently complete for an agent to use the tool safely.

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 zero description coverage, so the description carries the full burden. It explains every parameter: action with allowed values and the irreversibility note for delete, volume_name as the current name for rename, new_name as required for rename, and env with the environment-scoping rule. This fully compensates for the lack of schema documentation.

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

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

The description states 'Volume lifecycle' and explicitly lists the three actions (create, delete, rename), making the tool's purpose unambiguous. It also differentiates from sibling tools by directing file-level operations to modal_volume_files and list_modal_resources, so an agent can distinguish it from those alternatives without opening 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?

It provides explicit guidance on when to use this tool versus the siblings: 'For the files inside a volume use modal_volume_files (writes) or list_modal_resources(resource="volume_files") (reads).' It also adds a requirement that 'env' must match the volume's environment, which is a concrete precondition for correct invocation. This goes beyond mere context to actionable routing.

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

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

Beyond the destructiveHint annotation, the description discloses meaningful behavior: rm deletes remote files, force overwrites existing files, get with '-' returns contents instead of writing, and put/get are refused for paths outside the MCP_MODAL_ALLOWED_LOCAL_PATHS allowlist. It also documents the return envelope as {message, stdout, stderr} or {error}.

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 front-loads the core purpose and sibling distinction in its first two sentences, then uses a compact Args list where every line adds needed information. It is appropriately detailed for an 8-parameter tool without being padded.

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 multi-action tool with eight parameters and no enum constraints, the description covers all action modes, path conventions, directory handling, overwrite semantics, allowlist restrictions, and return value shape. The presence of an output schema further reduces the need to explain return details.

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

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

Schema description coverage is 0%, so the description must fully carry parameter meaning, and it does. Every parameter is explained with functional semantics: action values and their roles, local/remote path direction, paths for cp, recursive and force behavior, and env context for the volume.

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 'Write operations on a volume's files' and enumerates the specific actions put/get/cp/rm, making the tool's purpose concrete. It also immediately distinguishes itself from list_modal_resources, so an agent can tell which tool handles file listing versus file mutation.

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 LIST a volume's contents use list_modal_resources(resource="volume_files")', giving a clear when-not-to-use condition and naming the alternative. It also provides operational guidance for each action, including when recursive or force flags are needed.

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

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

Annotations are sparse (no readOnly, no idempotency), so the description carries the disclosure burden. It explains one-shot execution, output collection, detach persistence, and timeout truncation behavior—valuable details 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 compact and front-loaded with purpose and alternative routing, followed by a scannable Args list and a sharp Returns line. Every sentence adds functional 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?

Despite no schema descriptions, the definition covers prerequisites, parameter behavior, return shape, timeout handling, and the publish alternative. It is complete enough for an agent to invoke the tool correctly without external information.

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

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

Schema description coverage is 0%, and the description fully compensates by explaining each parameter: absolute path requirements (uv + modal installed), function_name disambiguation, env target, detach semantics, and timeout default. This adds meaning the schema alone does not provide.

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

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

The description states a specific verb ('Run') and resource ('Modal function or local entrypoint') and explicitly contrasts with deploy_modal_app ('use deploy_modal_app to publish'). This clearly differentiates the tool from its main 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 says 'Use this to test on Modal compute; use deploy_modal_app to publish,' giving direct when-to-use and when-not-to-use guidance. It also notes detach for long jobs, helping agents select the right mode for the task.

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 read-only, open-world, and idempotent behavior, but the description adds substantial behavioral context beyond structured data: logs are fetched once and grepped locally, crash events are absent from log streams, a single bounded 'since' range can fetch megabytes and be cut off by timeout, and prefilter changes what context_lines shows. These are meaningful, non-obvious behaviors an agent needs to know.

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 structure is purposeful: a front-loaded purpose statement, a critical stream-coverage caveat early, and then parameter documentation that earns its place by adding real semantic and operational value. Despite being long, there is little redundancy, and the return-value summary is compact.

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 16-parameter tool with 0% schema coverage, the description covers every parameter's semantics, gives default behaviors, failure modes, performance trade-offs, and explains the return shape. It is complete enough for an agent to select and invoke the tool correctly with no additional information.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it succeeds: every parameter is explained with non-schema semantics. identifier gets app/container ID prefixes, target gets an 'auto' rule, since/until gets a format warning and a 35-day cap, tail gets a max and default, prefilter gets a clear server-side behavior, and exclude' is defined as pre-search filtering.

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 ('Search an app's or container's logs') and clarifies the unique selling point: returns each hit with surrounding context to find tracebacks, errors, or request IDs. It also distinguishes itself from sibling tools by scoping coverage to stdout/stderr/system streams and explicitly excluding Modal dashboard crash events.

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

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

The description gives explicit when-to-use guidance ('fastest way to find a traceback, an error or a request ID') and a clear when-not-to-use case: crash events are not log lines and should be checked on the dashboard. It also gives operational guidance for large logs, such as preferring bounded ranges, using prefilter for huge logs, and re-querying a window after locating the hit.

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