data-breach-detector

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

The description discloses that the tool performs 'pure local analysis: it collects nothing, stores nothing and reaches no network; the text never leaves the server.' This adds meaningful privacy and network behavior not covered by the annotations' readOnlyHint and idempotentHint. No contradiction exists.

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-loaded with the core action and output list, followed by a concise privacy note and usage directive. Every sentence serves a purpose, with no redundancy or 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 that there is no output schema, the description does a good job of listing the outputs (threat level, matched categories, financial-target flags, confidence score, recommended action) and the input scenario. It does not specify possible values or formats, but it provides sufficient context for understanding the tool's role and use case.

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 fully describes the single parameter ('text' with description 'the security text to classify — an advisory, alert or forum post'). The tool description repeats this phrasing almost verbatim without adding new meaning, so with 100% schema coverage, 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 uses a specific verb ('Classify') and identifies the resource ('a piece of security text') and the outputs (threat level, categories, flags, confidence, recommended action). This clearly distinguishes it from sibling tools like breach_news and check_exposure, which focus on retrieving data rather than analyzing text.

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 context: 'Use it to triage findings surfaced by breach_news or from your own monitoring.' This tells the agent when to invoke the tool, though it does not name alternative tools or give when-not-to-use conditions.

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, openWorldHint=true, and idempotentHint=true, covering mutation safety. The description adds valuable behavioral disclosures: it returns only metadata (no contents), notes that large pages are heavy for an agent loop (in the limit param), and explains offset semantics for reaching the tail of a ~16k-post archive. This goes well 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 yet information-dense, with the core action ('Search the FULL historical breach archive') front-loaded. Every sentence earns its place: sources, filter capabilities, return-type limitation, and concrete example queries. It is well-structured and does not over-elaborate.

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 (9 parameters, multiple sources, no output schema), the description is remarkably complete. It covers the full date range, data sources, filter dimensions, return scope, and even performance guidance for large pages. The absence of an output schema is mitigated by 'Returns disclosure metadata only', which sets clear expectations for the agent.

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 baseline is 3. The description provides a high-level summary of filter types ('keyword, year range, sector, exposed data type or minimum scale') and ordering ('by date or size'), but this does not add meaningful detail beyond what is already in the schema parameter descriptions. Thus, no score above baseline is warranted.

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 tool searches the FULL historical breach archive, enumerates specific data sources (HIBP, ransomwatch, RansomLook, SEC filings), and clarifies it returns disclosure metadata only. This clearly distinguishes breach_history from sibling tools like breach_news or breach_stats by emphasizing the historical, archive-wide scope. Examples ('biggest breaches of 2013') further anchor its 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 provides clear usage context with 'Use this for questions like...' and defines what it does not return ('never breach contents'). However, it does not explicitly name alternatives or state when to prefer other sibling tools, so it falls short of a 5 which requires explicit 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses that 'Every row is metadata only — entity, date, scale, exposed data TYPES, threat level and source — never the leaked data, and a redaction pass strips anything credential-shaped before it is returned.' This clearly explains what the tool does not return and its redaction 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 dense paragraph that front-loads the core purpose and then covers key constraints (metadata only, redaction, ordering) and usage pointers. Every sentence contributes 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?

The description explains the output row composition (entity, date, scale, data types, threat level, source), ordering (newest first), and redaction. Combined with a fully self-documenting schema and sibling disambiguation, the context is complete for an agent to invoke the tool 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 detailed parameter descriptions (e.g., limit default, range, 'large pages are heavy', offset semantics, sector filter scope). The description adds little new parameter semantics beyond the schema, simply reiterating the sector filter usage. This meets the baseline 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?

The description clearly states it 'Read[s] recent breach and ransomware DISCLOSURES from public threat-intel feeds' and specifies the sources (HaveIBeenPwned, RansomLook, SEC 8-K). It explicitly distinguishes itself from siblings by noting 'for one specific organization use check_exposure; for all-time history use breach_history.'

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 when-to-use guidance: 'Use sector to narrow to an industry keyword; for one specific organization use check_exposure; for all-time history use breach_history.' It also mentions offset/limit behavior in the schema descriptions, reinforcing 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, openWorldHint, idempotentHint. The description adds meaningful behavior beyond those: 'Aggregate counts only; no leaked records' clarifies it never returns raw records, and 'plus the five largest incidents ever recorded' discloses an extra output. These traits are not covered by annotations, so the description adds useful 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?

Two tightly packed sentences: first states capability and dimensions, second gives real usage examples and a clear boundary. No filler or redundancy; 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?

Given no output schema, the description reasonably conveys return shape ('incidents and accounts exposed per year...' plus five largest incidents). It addresses complexity with examples and the no-leaked-records caveat. Slight gap is not detailing limit behavior or bucket ordering, but those are covered in the schema, so remaining context 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 covers 100% of parameters with detailed descriptions, including default values, min/max, and semantic notes (e.g., limit buckets_total behavior). The tool description adds no new parameter-specific meaning beyond restating group_by options already in the schema, 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?

Description uses specific verb 'Aggregate' with clear resource 'full breach archive' and enumerates exact output dimensions (per year, source, data type, threat level, actor). It differentiates from siblings via 'Aggregate counts only; no leaked records' and answers concrete analyst questions, making 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?

Provides explicit when-to-use guidance via example questions ('how has breach volume trended...', 'which ransomware groups...'). While it doesn't name alternative tools or state when not to use it, the context is clear enough for an agent to select it over the listed siblings.

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 readOnlyHint annotation, the description discloses that the tool is metadata-only ('never the leaked data'), that the timeline list carries a window (not all incidents) and how paging works, and that repeat victimhood is a forward-looking risk signal. This adds meaningful behavioral context not derivable from annotations or schema.

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 verbose but every sentence earns its place: purpose, summary fields, timeline behavior, interpretative note on repeat victimhood, metadata-only disclosure, and alternative tool. It is front-loaded with the main action and structured logically, though slightly longer than strictly necessary.

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 compensates by naming the summary fields and the timeline list structure, explaining the window and paging, and stating the metadata-only limitation. It does not enumerate every field in the incident list, but given the tool's complexity and that all parameters are documented, 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 covers 100% of parameters, so baseline is 3. The description adds valuable semantics for limit and offset by explaining the paging behavior ('paging backwards with offset' and the default window), and gives examples for entity ('yahoo.com' or 'Adobe'). This enhances beyond the schema descriptions, justifying a 4.

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 builds an incident-by-incident chronology for one organization across all sources, with summary judgments like first/latest incident, incidents per year, repeat victim status, worst threat level, and total accounts. It explicitly differentiates from check_exposure by directing users to that tool for yes/no presence checks, satisfying sibling 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 description provides explicit usage guidance: it explains the timeline window and paging behavior ('defaulting to the most recent limit incidents and paging backwards with offset'), notes that summary fields always cover every incident, and gives an explicit alternative for a different use case ('For a yes/no presence check use check_exposure'). This tells the agent when to use this tool vs. 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?

Beyond annotations (readOnly, openWorld, idempotent), the description adds critical behavioral details: it never returns exposed records, it is built from disclosure feeds rather than proof of compromise, and it explains that aggregates cover all matches while the matches list is paged via limit/offset. These go well beyond the structured 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 dense but well-structured, front-loading the core purpose before expanding into caveats, alternatives, and pagination. Each sentence adds necessary information, and there is no fluff. It is appropriately sized for the tool's complexity.

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 lacking an output schema, the description enumerates the return fields (yes/no, mention count, worst threat level, total accounts exposed, data types, metadata) and clarifies API behavior. It fully covers the necessary context for an agent to use the tool 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?

While schema description coverage is 100%, the description adds meaning beyond the schema by explaining how limit/offset affect only the matches page, not the aggregates or mention count, and that since_days default covers all history. This clarifies interaction between parameters and return 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 clearly states the tool's purpose: to answer whether a domain, company, or brand appears in breach/ransomware disclosures across all history, returning a yes/no with aggregates and metadata. It also explicitly distinguishes from siblings by naming breach_timeline and breach_news for other use cases.

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 when-to-use guidance: it labels the tool as a triage signal, warns against treating it as proof of compromise, and directs users to breach_timeline for chronological details or breach_news for recent news. It also clarifies that the tool never returns exposed records, setting expectations.

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 provide readOnlyHint and idempotentHint. The description adds valuable context: an 'honest staleness flag', cache ages, and explicit limitations on what is NOT provided (no PII, no arbitrary crawling). This 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?

The description is dense and well-structured: first sentence lists the output, second confirms no args, third states scope, and fourth gives usage guidance. Every sentence earns its place, with no fluff 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?

Given the zero-parameter, no-output-schema design, the description fully covers what the agent needs: what is returned (feeds, counts, new items, staleness, cache ages), scope limits, and when to use it. It is complete for a read-only health-check 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?

The tool has zero parameters, so the baseline is 4. The description explicitly states 'Takes no arguments', which confirms the empty schema and removes any ambiguity for the agent. This is clear and sufficient.

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 ('List') and a precise resource ('public disclosure feeds'), then enumerates exact output elements (cached disclosure counts, newest item, staleness flag, cache ages). This clearly distinguishes it from siblings like breach_news or breach_history, which focus on content rather than feed health.

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 says 'Check this first if another tool's answer looks thin', giving a concrete usage scenario. It also states scope exclusions ('no .onion access, no arbitrary fetching or crawling, no credential or PII output'), which tells when not to use the tool. This is clear when/when-not guidance.

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