LogTriage

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

Adds substantial behavior beyond the annotations: authentication requirement and header format ("Authorization: Bearer ltk_..."), credit consumption/billing impact, a hard 10 MB size limit, and the asynchronous job-id-then-poll contract with a 30-90 second wait. These are exactly the traits an agent cannot infer from readOnlyHint=false / idempotentHint=false.

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 sentences, both earning their place, with the capability summary leading and the operational prerequisites/async pattern following in workflow order. The first sentence is quite long and densely packed with feature lists, which slightly hurts scanability, but there is 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?

No output schema exists, so the description carries the return-value burden and does so: a job id is returned immediately and get_analysis yields the report after a known delay. Combined with auth, credit, and size constraints, nothing an agent needs in order to call this correctly 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?

Schema coverage is 100%, so both parameters are already documented and the baseline is 3. The description earns an extra point by attaching a real constraint to the log parameter ("Up to 10 MB of text") that the schema does not state; filename remains purely schema-described.

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+resource ("Runs LogTriage's full analysis on a log") and enumerates the concrete stages: parsing across 50+ formats, enrichment, risk scoring, attack-pattern detection, and an AI incident report with MITRE ATT&CK mapping. This clearly positions it as the broad, end-to-end tool versus narrower siblings like scan_log_for_attacks or explain_log_record, though it never names those alternatives 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 the practical usage context an agent needs: an API key is required, credits are consumed, input is capped at 10 MB, and the call is asynchronous so get_analysis must be polled after 30-90 seconds. It stops short of explicit when-not-to-use guidance or a direct contrast with the other analysis 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?

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, and the description still adds real context: a 500-address cap, twice-daily list refresh, no API key, and the interpretive caveat that 'being on a list is evidence, not proof'. Those freshness and rate-limit facts are exactly the kind of trait annotations cannot express. It omits any hint of response shape beyond private-range labelling.

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?

Front-loaded with the core action and scope, then limits and caveats; the trailing no-key and evidence-not-proof notes are short and useful. The parenthetical enumeration of all 12 blocklists is longer than strictly necessary but does inform trust decisions, so it earns its place—barely.

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 single-parameter read tool with no output schema, the description covers sources, input forms, batching limit, data freshness, and the special-range exception, which is close to enough to call it correctly. The main gap is that it never sketches what a result entry looks like, leaving the agent to infer the per-address verdict format.

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% for the single 'text' parameter, so the baseline is 3. The description earns the extra point by expanding what 'text' tolerates (raw addresses, log lines, CSV) and adding the 500-address ceiling, which materially affects how the agent batches a call.

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 ('Checks IPv4 addresses against 12 free public blocklists') and names the exact data sources, so an agent can distinguish it from analyze_log_file or scan_log_for_attacks without opening a schema. The named list set and the reference to logtriage.app ground what the tool actually does.

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?

Clear about input flexibility ('a list of addresses or any text containing them (log lines, CSV)') and about scope boundaries ('private and other special-purpose ranges are labelled, not looked up'), which tells the agent what inputs are wasted. It does not explicitly name a sibling or say when to prefer this over scan_log_for_attacks, so it stops short of full alternative 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 establish read-only, idempotent, non-destructive, closed-world behavior, so the description adds real value on top: it discloses that the operation is free with no API key, that meanings are sourced from reference pages or vendor definitions, and that attack checks are included in the result. It does not cover latency, rate limits, or failure modes for malformed records, which keeps it below a 5.

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 lead sentence front-loads the core action, with decoding and attack-check behavior following in logical order and cost information last. The format enumeration is long but functional; a small amount of tightening would make it sharper without losing information.

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 carries the return-value burden and does so adequately: it states the output is a per-field listing with meaning plus source, decoded values, and attack-check results. For a single-parameter analysis tool with annotations already covering the safety profile, nothing essential 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?

Schema coverage is 100% and the single parameter is fully documented in the schema, so the baseline would be 3. The description earns an extra point by enumerating the accepted record formats (access-log line, syslog/auth.log, Windows event XML, CloudTrail, Entra ID, CrowdStrike, firewall, CEF/LEEF), which tells the agent concretely what counts as a valid 'record' input.

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 specific verbs tied to a concrete resource: identify the format of ONE log record, list every field with its meaning and provenance, decode values, and run attack checks. It is immediately clear this operates on a single record rather than a file, which implicitly separates it from analyze_log_file, but it never names that sibling 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?

Usage context is implied by 'one log record' versus sibling analyze_log_file, and the 'Free; no API key needed' line tells the agent there is no cost barrier. However, there is no explicit when-to-use/when-not guidance, and the overlap with scan_log_for_attacks ('Runs LogTriage's attack checks on the record too') is left unresolved for the agent to infer.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context — and it does: the async status-then-report behavior and the authentication requirement ('Needs the same API key'). It does not disclose how long results are retained or how an incomplete or failed job is represented, which would be the remaining useful detail.

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?

One front-loaded sentence that leads with status-then-report before listing payload fields. The trailing enumeration of report contents is long but each item is informative rather than filler; it could be trimmed slightly without loss.

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 single-parameter read tool with full schema coverage and annotations, the only real gap is the return shape — and the description enumerates severity, attack pattern, summary, patterns, indicators, MITRE techniques, remediation, and a report link. Nothing an agent needs in order to call it correctly 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?

Schema coverage is 100% and the single parameter is already described as 'The job id analyze_log_file returned.' The description reinforces the provenance of job_id but adds no format, validation, or error behavior beyond what the schema states, so the baseline 3 applies.

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 ('Returns the status and, once complete, the incident report of an analysis') and anchors it to the sibling that produces the input ('started with analyze_log_file'). It also enumerates the report payload, so an agent can tell it apart from analyze_log_file or scan_log_for_attacks without opening either schema.

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 precondition is explicit: this is the follow-up call for a job created by analyze_log_file, and the phrase 'once complete' signals it may return only status and must be re-called. It stops short of stating polling cadence, retry guidance, or what to do if the job failed or expired.

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, and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: what is returned (official name, description, where the code is logged, an investigation page when available) and that the tool is free with no API key required.

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?

It is a single dense paragraph that front-loads purpose before formats and return values, with no filler sentences. The long parenthetical code examples cost some readability, but each one demonstrates a distinct accepted input shape rather than repeating itself.

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 one required parameter, no output schema, and full schema coverage, this description carries everything an agent needs: what it does, the input formats it accepts, and what comes back. There is no output schema to explain, and the description still summarizes the return payload.

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%, so the baseline is 3. The description still adds meaningful semantics beyond the schema's one-liner by spelling out the accepted formats: prefixed or bare AADSTS numbers, hex with or without 0x, decimal and negative-decimal forms, official constant names, whole pasted messages, and free-text keywords.

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 leads with a specific verb and resource: 'Explains Microsoft authentication error codes from Microsoft's official tables.' It then enumerates the exact code families covered (Entra ID AADSTS, NTSTATUS, Kerberos, official names), which makes it unmistakable versus siblings like search_reference or explain_log_record.

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 concrete input strategies: 'Paste a whole error message or event to find every code in it, or give words to search names and descriptions.' That is clear when-to-use guidance. It stops short of naming alternatives or exclusions (e.g., when to prefer explain_log_record or search_reference), so it doesn't reach a 5.

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, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavior beyond that: deterministic (non-AI) checks only, in-memory processing with no persistence, and a hard 5 MB input ceiling. It stops short of describing output shape or how findings are ordered, so it is solid but not exhaustive.

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 capability statement is front-loaded and the exclusion plus operational limits come after, which is the right order. It is dense to the point of being a single sprawling sentence with a long parenthetical format list, but nearly every clause carries information an agent needs.

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 two-parameter, non-destructive scan with no output schema, the description covers scope, detection coverage, input limits, data handling, cost/auth requirements, and the sibling alternative. Nothing an agent needs to invoke it correctly 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?

Schema description coverage is 100%, so the baseline is 3; the description earns one extra point by adding a constraint the schema does not carry — the 5 MB text limit on the log payload. The optional filename parameter and its format-hinting role are left entirely to the schema, which is acceptable given full 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?

States a specific verb (detects format, runs deterministic attack checks) on a specific resource (the supplied log), enumerates the covered formats and detection classes (brute force, spraying, injection, port scans), and explicitly separates itself from analyze_log_file. An agent can distinguish it from every sibling without opening a schema.

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 an explicit routing rule: threat-intelligence lookups and AI analysis are out of scope, and analyze_log_file is named as the tool for those. It also states the operational precondition (up to 5 MB of text) and that no API key is needed, so an agent knows both when to pick this tool and when to switch.

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 and non-open-world, and the description adds useful context beyond them: it is free, requires no API key, and returns the best matches with links to pages containing explanations and KQL/CQL/SPL/bash queries. It does not state result-count limits or how ranking behaves, which keeps it short of a 5.

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 purpose and breadth are front-loaded in the first sentence, and the second sentence adds what each page contains and what is returned. The parenthetical example lists are somewhat dense, but each item conveys real coverage information rather than 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 single-parameter read-only search tool with no output schema, the description covers scope, return shape ('best matches with links'), and access requirements ('free; no API key needed'). Nothing an agent needs in order to call it correctly appears to be 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 only one parameter and 100% schema description coverage, the schema already defines the query field as 'an event ID, event name, code, log message or words'. The description echoes that accepted scope when listing the covered reference types but adds no syntax, formatting or matching-behavior details beyond the 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 verb and resource ('Finds LogTriage's reference pages for an investigation') and then enumerates the exact content domains covered: Windows event IDs, AADSTS, NTSTATUS, CloudTrail events, Falcon events, sshd/PAM messages and field references. An agent can tell this is a reference/knowledge lookup rather than a log-scanning or per-record explanation tool.

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 'for an investigation' implies when to reach for it, but there is no explicit routing guidance against overlapping siblings such as lookup_error_code, explain_log_record or check_ip_blocklists. The agent must infer that this is the keyword-search entry point while those handle specific codes or individual records.

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