[OBSERVATION TOOL] Return temporal physical events for a port as a ChangePacket (physical-event.v1).
Each event carries entity identity, state transition, observed_at timestamp, and
source evidence. Use this tool to understand WHAT changed and WHEN.
Args:
port_id: UN/LOCODE e.g. "BRPNG" (Paranaguá), "BRSSZ" (Santos).
| Name | Required | Description | Default |
|---|---|---|---|
| port_id | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden and does well: it labels itself an 'OBSERVATION TOOL,' states the return type, and lists event fields such as entity identity, state transition, observed_at timestamp, and source evidence. It does not mention potential error conditions or limitations, but the observation nature is explicit.
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-organized: a front-loaded tool type, a precise main sentence, a brief field explanation, and an Args section with examples. Every sentence adds useful information 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 a single parameter, no annotations, and an existing output schema, the description is largely complete: it explains what is returned, the key event fields, the input format, and the intended use. It could more explicitly route between siblings, but the output schema covers return-value 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 coverage is 0%, so the description must compensate for the bare 'port_id' string property. It does so by specifying the format (UN/LOCODE) and giving concrete examples like 'BRPNG' (Paranaguá) and 'BRSSZ' (Santos).
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: 'Return temporal physical events for a port as a ChangePacket (physical-event.v1).' It also clarifies the semantic focus, 'WHAT changed and WHEN,' which distinguishes it from state/trend tools like get_port_state and get_port_trend.
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 clear context for when to use the tool: 'Use this tool to understand WHAT changed and WHEN.' It does not explicitly name excluded sibling tools or contrast them, but the intent is clear and an agent can infer it is for event/history data rather than current state or trend.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.