Forge Magery

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals a non-obvious trait: check names and categories are localized to the account locale and change with language, so matching must be by slug or checkId. It also details the entire return payload, providing transparency about the operation's outcome. Minor omissions like rate limits or side effects are acceptable given the read-like nature.

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 moderately long but every sentence adds value. The purpose is front-loaded, followed by requirements, return content, and a critical caveat about localization. It is logically structured with no fluff, balancing detail with brevity.

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 tool with an output schema, the description is comprehensive. It lists all return components (status, score, overview, history, checks with details) and highlights an important edge case (localization). It lacks explicit error handling or pagination details, but the output schema likely covers structural expectations, and the description sufficiently guides 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 compensate. It explains that audit_id is the id returned by start_audit or list_audits, which is critical context for obtaining the correct value. This goes beyond the raw integer type in the schema, effectively clarifying the parameter's provenance and usage.

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 clear verb and resource: 'Get the full results of one audit.' It distinguishes from siblings like get_audit_status by emphasizing 'full results' and enumerates the comprehensive return content, making its 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?

The description explains the required parameter (audit_id) and where to obtain it (from start_audit or list_audits), but does not explicitly contrast with alternatives like get_audit_status. It implies usage context but lacks explicit when-to-use vs. when-not-to-use 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?

With no annotations, the description carries the full burden. It discloses that the call is cheap, returns only specific fields with conditional presence, and is intended for repeated polling. It does not explicitly state read-only or lack of side effects, but 'check' and 'status' strongly imply non-mutation. A small explicit safety note would make it fully transparent.

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 four sentences, each earning its place: purpose, required parameter and source, response fields with conditions, and usage guidance versus get_audit. It is front-loaded with the core purpose and contains 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?

For a single-parameter status polling tool with an output schema, the description covers the purpose, parameter source, response field behavior with conditions, and alternative tool guidance. An agent has everything needed to invoke it correctly without additional lookups.

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 no description for audit_id (0% coverage). The description fully compensates by explaining that audit_id is required and is the id returned by start_audit or list_audits, giving essential provenance. This uniquely identifies the parameter's meaning beyond the schema's type and title.

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 action ('Check the progress of an audit') and resource, then explicitly contrasts it with get_audit, which returns much more detail. This distinguishes it from the sibling tools without requiring schema inspection.

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 explicitly says this is the tool to call repeatedly while waiting, and that get_audit is better for reading finished results. It also specifies where to obtain audit_id (from start_audit or list_audits), providing clear when-to-use and parameter sourcing 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?

With no annotations, the description carries the burden of behavioral disclosure. It does well by specifying that a nonexistent id or one from a different account is reported identically as 'not found', and it references the return fields as being the same as list_domains. It could have explicitly stated the operation is read-only, but 'look up' and the absence of side effects makes that reasonably clear.

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 sentences with no filler. The first sentence states the purpose, the second explains the parameter prerequisite and return shape, and the third covers error behavior. Every sentence serves a distinct informational purpose and the most important information is front-loaded.

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 one-parameter, read-only lookup with an output schema, the description is nearly complete. It explains the parameter source, the return field equivalence, and the not-found edge case. The only minor gap is that it does not explicitly say 'this is a read-only operation' or cross-reference list_domains as the alternative for listing, but these are implied and the output schema covers return 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. It does so effectively by explaining that domain_id must be an id previously returned by list_domains, and it adds behavioral meaning by stating what happens for invalid or foreign ids. This goes beyond the raw schema type of 'integer' and gives the agent everything needed to provide a correct value.

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 ('Look up'), a specific resource ('one domain'), and a precise mechanism ('by its id'). It also names the sibling tool list_domains and clarifies that this is the singular counterpart, making the distinction 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?

It clearly states a prerequisite: the domain_id must come from a previous list_domains call. This implies the natural workflow of listing first, then fetching details, which gives clear context for when to use this tool versus list_domains. It does not explicitly say 'do not use list_domains for a single domain', but the instruction is effectively explicit enough.

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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses ordering (newest first), filter semantics (contains, inclusive date ranges), pagination behavior (cursor from previous call, nextCursor absent on last page), and the exact fields returned per audit.

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 efficiently organized: one purpose sentence, one sentence per parameter group, and a return summary. Every sentence adds necessary information, especially given the 0% schema description coverage. It is front-loaded with the core purpose before diving into details.

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 is complete for a read-only listing tool with 8 optional parameters. It covers filtering, pagination, output fields, and the terminal-page sentinel. Given the output schema exists and the description already explains the return shape, nothing essential is missing 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 explain every parameter, and it does. Each of the 8 parameters gets a clear semantic explanation including enum meanings, inclusive date behavior, default/maximum limit, and how cursor pagination works.

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 starts with a specific verb and resource: 'List security audits run on your domains, newest first.' This clearly differentiates it from siblings like get_audit (single audit) and start_audit (create an audit). The plural 'list' and the domain scope make the tool's 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?

The description gives strong context about when this tool is appropriate: listing audits with optional filtering and pagination. It does not explicitly name alternatives or state when not to use it, but the 'every argument is optional' framing and pagination details make the intended usage clear.

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?

With no annotations provided, the description carries the full burden. It discloses detailed behavioral semantics: return fields include id, name, added timestamp, ownership proof via email or DNS TXT with timestamps or absence, active status, and plan limit. This is substantial disclosure beyond the empty 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 front-loaded with the primary purpose and every sentence adds value. The field enumeration is detailed but directly relevant to using the tool correctly. No filler or redundant content.

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 zero-parameter listing tool with an output schema present, the description is complete. It explains what is returned, clarifies the meaning of ownership proof timestamps, and includes the plan-level limit. An agent can confidently invoke and interpret the result without further context.

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 and the schema confirms this. The description explicitly states 'Takes no arguments,' which satisfies the baseline for a no-parameter tool. No further parameter explanation is needed.

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: 'List every domain registered on your account.' It clearly differentiates from sibling tools like get_domain (single domain) and list_audits (audits, not domains).

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 clearly states this is for listing all domains on the account and that it takes no arguments. It does not explicitly name sibling alternatives or exclusion conditions, but the context is clear enough for an agent to select it when a full domain list is needed.

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?

With no annotations, the description carries the full burden of behavioral disclosure, and it delivers thoroughly. It explains that the tool runs every plan-granted check, that email/DNS verification level changes thoroughness, that it fails if an audit is already running, and that it returns the audit id, starting status, and queued-check count. It even advises polling via get_audit_status, giving the agent a realistic model of the tool's asynchronous 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 three short paragraphs but every sentence earns its place: the first states the core purpose, the second details prerequisites and failure modes, and the third covers return values and follow-up polling. It is concise yet information-dense, with the main action front-loaded.

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 one-parameter tool with an output schema already present, the description is complete: it covers the parameter, the behavior, all failure conditions, the return values, and the recommended next step (polling). There is no missing information an agent needs 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?

Input schema coverage is 0% and the schema only shows domain_id as an integer, but the description compensates by defining it as 'the id of a domain on your account that is active for checks.' This adds semantic meaning, constraints, and selection criteria far beyond the bare schema. For the single parameter, this is more than adequate.

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 'Start a new security audit,' which combines a specific verb and resource, leaving no doubt about the tool's function. It clearly distinguishes itself from sibling query tools (get_audit, list_audits) by being the only one that initiates an audit, not just retrieves or lists them.

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 preconditions (domain_id must refer to a domain active for checks) and enumerates all failure situations: domain nonexistence, not being active, no checks granted by the plan, or an audit already running. It also routes the agent to get_audit_status for polling. It stops short of explicitly saying 'use this instead of get_audit/list_audits,' but the usage context is unambiguous.

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