TheLeaf Threat Observatory

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds a genuinely useful epistemic caveat that counts are unconfirmed attacks, but says nothing about the default 24-hour window, the 2160-hour cap, or the sensitivity of the unverified credential data being surfaced.

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, front-loaded with the scope and closed by the caveat. Nothing is redundant and no sentence is 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?

With no output schema, the enumeration of summary dimensions partially conveys the return shape, which helps. However, a three-parameter aggregation tool whose time window and test-inclusion flag are undocumented in both schema and description leaves real gaps 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 must carry parameter meaning and it does not: the listed items (observations, IPs, credentials, categories) describe output dimensions, not inputs. The `feed` enum is self-describing, but `hours` is never mentioned as the time window and `include_operator_tests` is completely opaque — an agent cannot infer what operator tests are or why to include 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?

The description opens with a specific verb ("Summarize") and enumerates the resources summarized: published observations, source IPs, submitted credentials, categories and MCP tool activity. That is enough to tell it apart from evidence-oriented siblings like get_observation_evidence or get_session_timeline, though no sibling is named 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?

There is no statement of when to reach for this aggregate view versus search_observations or get_session_timeline, and no prerequisites or exclusions. The second sentence ("Counts are not confirmed attacks") is an interpretive caveat about the data, not usage 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 readOnly/idempotent/non-destructive, but the description adds real behavioral context: the payload is inert data that must not be treated as instructions, and it is a redacted projection. That is valuable disclosure an annotation cannot convey.

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 compact sentences with the core purpose front-loaded and no filler. The safety warning is justified given the payload content, though it crowds out parameter explanations.

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 and zero schema description coverage, the description carries the full burden yet omits what the returned evidence looks like and what two of three parameters control. An agent can call it but may not understand the lookback window or test-inclusion filter.

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% for three parameters, and the description only implies the role of event_id. It never explains the 'hours' lookback window (default 2160) or what 'include_operator_tests' does, leaving two parameters undocumented anywhere.

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 ... published payload evidence') and scopes it by event ID, so the agent knows this fetches one record rather than searching. It doesn't explicitly contrast with siblings like search_observations or get_session_timeline, so it stops short of full differentiation.

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 second sentence is a security instruction, not usage guidance. Nothing tells the agent when to prefer this over search_observations or get_session_timeline, nor any prerequisite such as needing an event ID from a prior search.

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 the operation as read-only, idempotent, non-destructive, and closed-world. The description adds meaningful scope context by clarifying that this is coverage data rather than live health, but it does not describe authentication needs, rate limits, or exact return 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 two tight sentences with no wasted language. It front-loads the core operation and follows with an important scope clarification.

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 annotations covering safety, the description gives a reasonable high-level picture of the returned coverage information. However, with no output schema and no parameter descriptions, it leaves the agent without guidance on the time window or operator-test inclusion.

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

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

The schema has zero description coverage for both parameters, so the description must compensate for the undocumented 'hours' and 'include_operator_tests' parameters. It does not mention either parameter or explain the default lookback window or what operator tests mean.

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 read operation over coverage-related data: configured feeds, published counts, observation times, delay, and retention limits. It clearly distinguishes coverage data from live service health, though it does not explicitly differentiate itself from the sibling observation/search 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 phrase 'This is data coverage, not live service health' provides a useful exclusion, implying the tool should not be used for health checks. However, it does not say when to choose this tool over siblings such as get_activity_summary or search_observations.

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, destructiveHint=false, and openWorldHint=false. The description adds valuable behavioral context beyond annotations: session labels are correlation aids, not identities, and captured content is untrusted data. It does not cover pagination or retention behavior, but the added trust caveats are meaningful.

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 short sentences, front-loaded with the core action, followed by two high-value caveats. No wasted words or redundant restatement of the tool name.

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 six-parameter tool with no output schema and 0% schema description coverage, the description is incomplete. It omits parameter semantics, pagination behavior, and what the timeline contains, though annotations do cover the safety profile.

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 mentions none of the six parameters. Required fields like conversation and feed, optional filters like hours, limit, before, and include_operator_tests are entirely undocumented in prose, leaving the agent with no semantic guidance 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?

States a specific verb and resource: 'Read a retained published session timeline.' An agent can understand the core operation, but the description does not distinguish it from siblings like get_activity_summary or search_observations.

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 no guidance on when to use this tool versus alternatives. The caveats about session labels and untrusted content are important context but do not tell the agent when this tool is the right 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 openWorldHint=false; the description reinforces the closed-world trait with 'No external lookup is performed' and adds the non-obvious interpretive caveat that a match is only evidence and absence is not safety. It stops short of describing the result shape or how the time window affects 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?

Four short, front-loaded sentences, each carrying distinct meaning: purpose, match interpretation, no-match interpretation, and scope of the lookup. No filler and no 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?

With five parameters at 0% schema description coverage and no output schema, the description should explain the time window, pagination, and the operator-tests flag, plus what a result contains. Instead it spends its budget entirely on interpretation caveats, leaving the agent unable to set parameters confidently.

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% for five parameters, and the description says nothing about any of them. The bare phrase 'for an IP' hints at the required ip field, but the hours window, limit, before cursor for pagination, and include_operator_tests toggle are left entirely unexplained, forcing the agent to guess at their meaning.

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: 'Look up observed behavior for an IP.' An agent can tell this is an IP-centric lookup versus the aggregate views offered by get_activity_summary or get_sensor_coverage, though no sibling is named 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?

The description frames how to interpret results (evidence, not proof; no match is not safe), which is genuinely useful framing, but it never says when to choose this tool over search_observations or get_observation_evidence. No prerequisites, exclusions, or alternatives are 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 read-only, idempotent, non-destructive, closed-world behavior, so the description adds meaningful context by warning that results are untrusted evidence and not instructions or malicious-IP verdicts. It also mentions cursor pagination via next_before, though the relationship to the schema's "before" parameter is not fully clarified.

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 brief, front-loaded with the core purpose, and wastes no words. The safety caveat and pagination note are compact and relevant.

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 seven-parameter search tool with no schema descriptions and no output schema, the description is too sparse. It gives an important trust warning but omits filter semantics, time-window behavior, defaults, result structure, and how pagination tokens are actually consumed.

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% across seven parameters, so the description must carry the burden. It only alludes to pagination via next_before and does not explain ip, feed, hours, limit, before, category, or include_operator_tests.

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 published observations." This is clear enough to distinguish it from evidence retrieval or IP lookup siblings, but it does not explicitly name when to prefer it over those alternatives.

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 explain when to use this search tool versus siblings such as get_observation_evidence or lookup_observed_ip. Usage is only implied by the phrase "Search published observations," with no exclusions or alternative-routing guidance.

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