Foliora Managed AI Search

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

Annotations already mark this as non-read-only, open-world, idempotent, and non-destructive, but the description adds meaningful context: stale/mismatched hashes are refused, approval must come from the customer, and the follow-up path depends on fix.publisherReady. It also discloses the required OAuth/API scope, which is not present in 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?

Every sentence earns its place: purpose, precondition, failure mode, customer-decision boundary, conditional workflow, and auth requirement. The most important usage condition is front-loaded immediately after the action statement.

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 covers preconditions, auth, failure behavior, and the exact conditional post-approval workflow, while the output schema handles return-value details. Nothing needed to invoke this tool 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?

Schema description coverage is 0%, so the description must compensate. It does clarify expectedHash's meaning ('exact canonical hash') and the refusal behavior for stale or mismatched values, but it does not explicitly explain changeSetId beyond the schema's name and UUID format. Still, the phrase 'one drafted change set' anchors changeSetId well enough.

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 names a specific action ('Approve one drafted change set'), a precise identifier ('exact canonical hash'), and clearly separates it from siblings like reject_change and reask_change. It is immediately obvious what the tool does and how it differs from nearby operations.

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 states an explicit precondition ('Call this only after the customer has read the operations from get_page_job and told you to approve that hash') and clarifies that approval is the customer's decision, not the agent's. The conditional workflow for connected publishers versus manual application plus report_publication gives concrete when-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?

Beyond the annotations, the description adds valuable behavioral detail: it does not crawl, does not accept credentials, does not modify the site, and produces a URL that requires a human to act on. This clearly sets expectations for a safe, non-invasive link-building operation.

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 with no redundancy. The core purpose is front-loaded, and each sentence contributes useful information about behavior or next steps.

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, 100% schema coverage, a full output schema, and strong annotations, the description is complete. It also covers the critical human-in-the-loop behavior that an agent must understand 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?

Schema description coverage is 100%, and the single parameter websiteUrl is already described as a public website URL or host with https optional. The description reinforces that no credentials are needed but adds little parameter-level meaning 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 states a specific verb and resource: 'Build a Foliora /preview URL for a public website.' It is clearly distinct from the read-only sibling tools and explains the core deliverable (previewUrl) without confusion.

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 clear context: the tool is for public websites, does not crawl, does not take credentials, and does not change the site. It also explains that the human must start the snapshot in a browser, but it does not explicitly name sibling tools as alternatives or give a when-not-to-use comparison.

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, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds valuable behavioral detail beyond annotations: it discloses that the returned hash is canonical and that operations are ordered, and it warns against reinterpretation. This is meaningful but lacks depth—it doesn't mention what happens if the change is not approved or any potential errors.

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 with no waste. The core function is stated first, and the critical behavioral instruction is front-loaded. It is efficiently structured for a tool with a single parameter and a self-explanatory 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?

Given the tool's low complexity (one UUID parameter, clear name, and annotations covering safety), the description is nearly complete. The output schema exists, so return values are presumably structured elsewhere. The only real gap is the lack of parameter explanation, which is minor for a single self-descriptive parameter like changeSetId.

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 the parameter, but it doesn't. The only parameter, changeSetId, is not mentioned at all in the description. An agent must infer from the name and format that it identifies the change set, but there is no explicit explanation of how to obtain it or its format beyond the schema's uuid format. This is a significant gap.

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: returning an already-approved canonical hash and its ordered typed operations. The verb 'Return' plus the resource 'approved Foliora change' makes the intent clear. However, it doesn't explicitly distinguish this from sibling tools like get_product or get_snapshot beyond the 'approved' qualifier, and the lack of parameter explanation slightly limits full clarity.

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 instruction 'Apply exactly these values; do not reinterpret or regenerate them' implies a use case where exactness is critical, perhaps for deterministic application of an approved change. However, there is no explicit guidance on when to use this tool versus alternatives like get_snapshot or create_preview_link, nor any stated exclusions. The usage context is implied rather than explicit.

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 mark this as readOnly, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: stale editions have null hashes and an approval prohibition, and the operations should not be paraphrased as approved text. This materially changes how an agent should interpret and use the result.

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 with no wasteful filler, and the most important framing ('One proposed page change') comes first. The first sentence is dense and lists many required fields, but each element earns its place because it tells the agent what to expect in the payload.

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 output schema exists, so return-value details are already structured. Annotations cover the read-only and non-destructive safety profile. The description supplies the remaining operational context: when to read this, what cannot be approved, and how the content should be presented to the customer. 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?

The schema has one required parameter, jobId, with a uuid format and 0% description coverage. The description never mentions jobId explicitly, but it does clarify what the job object refers to ('One proposed page change'), which indirectly clarifies what the id identifies. A single obvious uuid parameter makes this adequate, though a mention would have been stronger.

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 exactly what the tool does: it reads a single proposed page change in full — rationale, brief, objectives, drafted operations with before/after values and canonical hash, and `fix` status. This precise verb+resource pairing distinguishes it from related tools like get_approved_change, which would return an already-approved change.

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 explicit workflow guidance: 'Read this with the customer before approve_change; never paraphrase the operations as approved text.' It also tells the agent when not to treat the result as approvable via the stale-edition clause ('A stale edition is readable history with a null hash; it can never be approved').

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 destructiveHint, so the safety profile is covered. The description adds behavioral context by clarifying that this tool returns product facts rather than crawling a live site, which helps manage expectations about freshness and scope.

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 with no filler. The core purpose is front-loaded, the content list is compact, and the exclusion is stated in one short clause.

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?

This is a simple zero-parameter, read-only tool with rich annotations and an output schema. The description fully covers what the agent needs to know to select and invoke it 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?

The tool accepts zero parameters, so parameter semantics are not applicable. With no required inputs, the description's clarity about what the tool returns is sufficient; the baseline of 4 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 states a specific verb ('Return'), a clear resource ('Foliora product facts'), and enumerates the exact contents: brand, per-site plans, canonical URLs, and product boundaries. It also distinguishes itself from site-level tools by noting it does not crawl a site.

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 tells the agent when to use this tool: when the user asks what Foliora is, how much it costs, or which URL to open. It also gives an exclusion ('Does not crawl a site'), though it does not explicitly name sibling 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 (readOnlyHint, idempotent, non-destructive), the description adds important behavioral details: it returns only public findings and pages, unknown tokens yield not_found, and it does not trigger a crawl. These are meaningful, non-obvious behaviors that an agent cannot infer from the schema or 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 compact, with four short sentences each carrying distinct information: the action, token source, return scope, error behavior, and lack of side effects. It is front-loaded with the main 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 read-only tool with an output schema and full annotations, the description is complete. It covers prerequisites, return filtering, error semantics, and side-effect negation, so an agent has everything needed to invoke it 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?

The schema already covers the token parameter fully with a pattern and description, so the baseline is 3. The description adds provenance by specifying the token comes from a /preview/{token} URL and that it is 32-hexad?character hex, which is genuinely useful beyond the schema's description.

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, 'Fetch a Foliora preview snapshot the human already started', which clearly distinguishes it from create_preview_link. It also adds 'Does not start a crawl', further disambiguating from the creation sibling.

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 says the snapshot must already be started by the human, establishing when to use it, and it requires a token from /preview/{token} as a prerequisite. It does not explicitly name an alternative like create_preview_link, but the exclusion 'Does not start a crawl' gives clear contextual 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, and non-destructive behavior. The description adds useful transparency by specifying the row contents (code, severity, evidence URL, fix guidance) and the 'open findings' filtering behavior. No contradiction with 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?

Two tight sentences lead with the core action and scope, then add concrete examples and row-level expectations. Every sentence contributes value with no fluff.

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 list tool with an output schema, the description covers the purpose, result contents, and safe behavior. The only real gap is the ambiguous relationship between 'open findings' and the status parameter.

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, but it only explains what findings look like, not the semantics of siteId or status. The 'open' phrasing hints at a default filter but does not clarify the status enum or how to request other statuses.

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: list crawl findings for a site, with concrete examples (missing descriptions, blocked AI crawlers, missing llms.txt). This clearly distinguishes it from sibling tools like list_sites and list_approved_changes.

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?

Describes the tool as retrieving open crawl findings for a site, which implies when it should be used. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it over the list-based 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?

The description adds substantial behavior beyond the readOnly/idempotent annotations: rows are sorted by impact, the list matches the customer dashboard, and each row includes the fix state, the reason a draft may be absent, live finding statuses, and nextAction. It also signals that the full proposal is available elsewhere, which helps the agent set expectations when invoking this list.

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, each earning its place: the first establishes purpose, scope, and ordering; the second describes row semantics; the third names the follow-up tool. Important details are front-loaded and there is no filler 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?

With an output schema and readOnly annotations present, the rich description covers sorting, row content, and the path to get_page_job. The main remaining gap is the meaning of the status parameter, which an agent would need to filter correctly. Otherwise the definition is complete for a read-only listing 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?

Schema description coverage is 0%, so the description must compensate. It does clarify that the list is for 'one owned site', which maps to siteId, but it never explains the optional status enum ('proposed' vs 'all') or the default behavior. The description partially bridges the schema gap but leaves a meaningful parameter unexplained.

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: 'The page changes Foliora proposes for one owned site.' It adds meaningful scoping ('highest impact first', 'same list the customer's dashboard shows') and distinguishes itself from the deeply related get_page_job sibling. There is no ambiguity about what this tool returns.

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 positions the tool as the list-level view and explicitly routes deeper inspection to get_page_job: 'Use get_page_job to read a proposal in full before the customer decides.' It does not enumerate exclusions for other siblings, but the main alternative is named and the context for choosing one over the other is 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?

Annotations already declare the tool as readOnly, idempotent, and non-destructive. The description adds valuable context beyond those annotations by noting the authentication requirement (OAuth or API key with read scope) and clarifying that the listing includes crawl and finding status. This is useful behavioral context without contradicting 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?

Two sentences, no filler, and the core action and scope are front-loaded. Every sentence adds meaningful information. This is an appropriately sized description for a zero-parameter tool.

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 no-parameter list operation, the description is complete: it states the resource, the account ownership, the included status fields, and the authentication requirement. The annotations cover safety and idempotence, and an output schema is present, so return-value details do not need to be repeated in the description.

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 schema description coverage is 100%. The description correctly does not invent parameter-level details. With no parameters to document, a baseline of 4 is appropriate because the description does not need to compensate for any paramter gap.

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') with a concrete resource ('sites owned by the authenticated Foliora account') and adds the distinguishing detail that crawl and finding status are included. This clearly separates it from sibling tools like get_snapshot or get_site_brief.

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 implies when to use it: whenever the agent needs to enumerate the account's sites along with their statuses. However, it does not explicitly name alternatives or state when not to use it, so the usage guidance is implied rather than 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?

Beyond the idempotentHint annotation, the description adds the prerequisite of OAuth or API key with the approve scope and clarifies the post-condition, enhancing transparency without contradicting 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 brief and to the point, with three succinct sentences covering purpose, usage condition, effect, and requirement. No unnecessary words 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?

It includes the prerequisite, effect, and usage condition, which is sufficient for a simple rejection operation. Output details are not covered, but since an output schema exists (as indicated in context signals), this is acceptable.

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 only parameter, changeSetId, is not described in either the schema (which provides only type and format, no description) or the tool description. The name is self-explanatory, but the description does not explicitly compensate for the lack of schema description, leaving some ambiguity.

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 function: 'Close one drafted change set without approving it.' This is specific and distinguishes it from sibling tools like approve_change.

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 a usage condition ('Call this only when the customer says so') and explains the effect ('The job stays proposed and can be drafted again later'), but does not explicitly compare with alternative tools like approve_change.

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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds valuable context: it discloses that the report is not taken on faith (a subsequent read confirms or reopens), and that it requires execute access. It also mentions the 'fix_reported' status. This goes beyond the annotations by explaining the post-condition and verification workflow, which is critical for the agent to understand the asynchronous 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 three sentences: first states the action and purpose, second explains the downstream effect, third clarifies the verification and permission. It's well-structured, front-loads the verb 'mark it fix_reported', and every sentence adds distinct meaning. No fluff, efficient use of words.

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 moderate complexity (2 params, no enums) and the absence of a detailed output schema (there is one but not shown, the description doesn't need to explain return values). The description explains the workflow, the expected effect, and the verification process experimental. It covers the essential points: when to use, what happens after, and that it requires execute access. The only minor missing piece is explicit parameter names, but that's covered by the schema itself (which has names and types). So it's complete enough for an agent to call 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?

The schema has 0% description coverage, so the description must compensate. The description mentions 'findingId' implicitly but does not explain the 'note' parameter at all. It says 'with a short note' which maps to the 'note' parameter, but doesn't specify max length or optionality. It could have explained that 'findingId' is the UUID of the finding to mark, and 'note' is optional text. Given that there are only 2 params usable via description, the coverage is slightly better than low, but it's still not explicit enough for an agent to know exactly what to pass. However, because the note is described, it gets 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 action ('mark it fix_reported'), the resource ('a finding'), and the context (after fixing meta description, robots rule, or llms.txt). It distinguishes itself from siblings like 'report_publication' which is about publication, not findings. The phrase 'Report a finding as fixed' is not a pure tautology because it clarifies which domain (finding) and action (fixing).

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 tells when to use it: 'After the agent fixes a finding on the site'. It explains the post-condition (shows as done on the customer's Fixes list) and that the system will later confirm or reopen. It doesn't explicitly name alternative tools or when not to use it, but the context implies it's the right tool for marking a fix; 'Requires execute access' hints that not all agents will have this tool, but doesn't list alternatives. Could have explicitly said 'Use this only after fixing a finding, not for reporting publications (use report_publication) '.

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 mark this as a non-read, idempotent, non-destructive mutation. The description adds beyond that: Foliora independently verifies the live page, the change shows as 'done' on the dashboard, and receipt values must exactly match stored operations. No contradiction with 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?

Three sentences, each adding value: purpose, post-effect, and the critical rule about receipt matching. It is front-loaded and free of padding.

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 complex mutation with 4 required parameters, a nested receipt object, and an output schema, the description covers the key behavioral caveats (no approval, Foliora-side verification, exact match requirement). It does not explain the surrounding verification flow in more depth, but combined with the schema and annotations it is adequate.

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 gives meaning to expectedHash ('already-approved canonical hash') and receipt (must exactly match stored operation), but it does not explain idempotencyKey or the changeSetId in any depth, and its coverage of the nested receipt fields is partial.

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 action: 'Record proof that the customer's agent applied every operation from an already-approved canonical hash.' Distinguishes itself from the approval flow by explicitly noting 'This does not approve a change,' which disambiguates it from sibling tools like approve_change.

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 a clear condition of use: when the agent has applied every operation from an already-approved hash. It also provides an exclusion ('This does not approve a change') that separates it from approve/reject siblings, though it does not explicitly name alternative tools.

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