import_traffic_log

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

Adds substantial context beyond the annotations: annotations only say readOnlyHint=false, but the description clarifies that the default call is actually a dry-run preview and that mutation only happens with apply=true. It also discloses that the raw log never reaches the agent, values are masked, and that scenario_path writes a YAML file under scenario_root — file-system side effects an agent would otherwise not anticipate.

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?

Five tight sentences, each carrying new information, with the core purpose front-loaded before the mutation/masking caveats and parameter guidance. The first sentence is long and list-heavy but still scannable; nothing is redundant.

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?

An output schema exists and returns needn't be described, so the remaining burden is on behavior and inputs. The description covers masking, preview-vs-write, service/env derivation, and scenario file output well; the gaps are the path/content/format inputs, which a 7-parameter tool with zero schema descriptions should spell out.

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 seven parameters. It explains apply, service, environment, and scenario_path well, and hints at format via 'mobile app transaction log or HAR', but leaves path and especially content (server path vs inline log payload) ambiguous and never explains the format parameter's accepted 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?

States a specific verb and resource ('Read a traffic log ... and propose catalog changes') and enumerates the concrete artifacts produced (new/changed/unchanged operations, kinds, session need, test customer fields, draft scenario). This makes it clearly distinguishable from siblings like run_scenario or list_operations, though it never names an alternative explicitly.

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

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

Gives a clear operational workflow: apply=false is a preview to show the user, apply=true writes the catalog, and service/environment should only be given when the host is not in services.yaml. It covers when to use which mode but does not state when to prefer this tool over manual catalog authoring or other siblings.

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