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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it is safe to call repeatedly and does not write data or contact remote services, which supplements but does not contradict. No contradictions.

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: the first states purpose and output, the second provides usage guidelines and behavioral traits. Every sentence adds value, no 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?

Given zero input parameters and the existence of an output schema, the description fully informs about the return value (record-count metrics) and the tool's role. No gaps remain.

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 describes zero parameters with 100% coverage, so baseline is 4. Description does not need to add parameter details but mentions 'optional sync totals' which relates to output, not input. No missing information.

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 checks SQLite readiness and returns record-count metrics for specific entities (requests, correspondence, optional sync totals). It distinguishes from siblings by naming alternatives like sync_monitor and list_requests.

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?

Explicitly advises use as a first health probe or liveness check, and provides clear alternatives: prefer sync_monitor for queue/offline depth and list_requests for request content. No usage ambiguity.

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?

Disclosures go beyond annotations: 'Read-only and idempotent; pure calculation with no database or network access' and mentions return type. 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?

Three sentences: purpose, usage, behavior/return. No redundant information, well-structured.

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?

Complete for a simple tool with output schema: covers purpose, usage, behavior, and return type adequately.

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 description adds little param detail beyond implicit mention of start date and day count, but adequate given high 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?

Description clearly states the tool computes statutory FOI/OIA deadlines from start date and day count, and explicitly differentiates from siblings list_requests and sync_monitor.

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?

Explicitly states when to use (local working-day or calendar-day deadline math) and when not to use, listing sibling tools as 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 (readOnlyHint=false, idempotentHint=false), description adds 'Mutating and not idempotent: each call allocates a new ID. Does not submit to a remote authority, send email, or require network access.' No contradiction.

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 well-structured sentences. First sentence states purpose and scope; second gives usage constraints and behavioral notes. No wasted 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?

Covers core behavior, exclusions, side effects, and sibling references. Output schema exists so return values need not be described. Complete for a tool with 6 params and 2 required.

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 baseline is 3. Description only mentions that title and body are required, which is already in schema. No additional parameter guidance beyond 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?

Description explicitly states 'Create a new local FYI/Alaveteli request row (draft or tracked) in SQLite', with verb, resource, and scope. Also names siblings update_request and delete_request to distinguish.

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?

Clearly says 'Use only when starting a new request; use update_request to change an existing ID and delete_request to remove one.' Provides explicit when-to-use, when-not-to-use, and 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?

Reinforces annotations' destructiveHint: true and adds scope limitation: 'does not delete anything on remote FYI/Alaveteli sites.' Provides context beyond annotations, though could mention error handling or side effects.

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 concise sentences, no redundancy. Important information front-loaded. Every sentence contributes value.

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?

Covers purpose, scope, usage guidelines, and alternatives. Simple one-parameter delete tool—description is thorough enough for correct tool selection and 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?

Single parameter with 100% schema coverage. Description does not add extra meaning beyond schema's 'Stable local request ID to delete permanently.' Baseline score of 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?

Clearly states 'Permanently delete a local request and all of its stored correspondence from SQLite' with specific verb and resource. Distinguishes from sibling tools by naming update_request for edits and list_requests/retrieve_request for 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?

Explicitly instructs to use only after confirming ID should be discarded, and provides clear alternatives (update_request for edits, list/retrieve for inspection). Notes destructive and irreversible nature.

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, destructiveHint=false. The description adds 'fail-closed' and 'never enables a route or contacts a remote service', which are valuable behavioral specifics 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?

Two sentences, front-loaded with the main action, no filler. Every word adds value. Ideal conciseness.

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?

While the description covers the tool's core behavior and safety profile, it fails to explain what parameters mean despite low schema coverage. The output schema exists, reducing burden for return values, but parameter semantics are 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%, meaning the schema only provides type info. The description does not explain the meaning or usage of any of the 5 parameters (scopes, client_id, now_epoch, bulk_export, capabilities). This is a critical gap for an agent to correctly invoke the tool.

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 evaluates an operator-published endorsed-client capability document locally. It specifies it's read-only and fail-closed, giving a precise action. However, it does not explicitly differentiate from siblings like check_status, which could be similar in spirit.

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 implies usage for local evaluation and says it never enables a route or contacts remote services. This provides implicit guidance (don't use if you need to enable routes or contact remotes), but lacks explicit when-to-use or when-not-to-use statements or alternative tool suggestions.

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 idempotentHint=true and destructiveHint=false. The description adds context beyond annotations: explains the upsert mechanics ('same slug re-import updates name/url without creating duplicates') and states 'does not contact remote authority directories', which is not captured 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?

Three sentences: first states purpose, second gives usage guideline, third explains behavioral traits. No filler; every sentence adds distinct value. The description is front-loaded with the core action.

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 tool has one parameter (array) fully described in schema, annotations present, and output schema exists (handles return value documentation). The description covers the upsert semantics, idempotency, and relation to sibling tools, making it fully informative for correct usage.

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 baseline is 3. The description adds value by explaining that slug is the import key (primary key for upsert) and that the operation is idempotent and non-destructive, which clarifies the behavior of the 'authorities' parameter beyond its schema definition.

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 'Upsert local public authority reference records by slug for request routing and discovery', specifying the verb (upsert) and resource (authority records by slug). It also distinguishes from siblings by explicitly saying 'do not use for FOI request CRUD (create_request/update_request)' and recommends usage 'after list_authorities'.

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 ('after list_authorities when seeding or refreshing the catalog') and when not to use ('do not use for FOI request CRUD'). Also names alternative tools (list_authorities, create_request, update_request), offering clear 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 readOnlyHint, idempotentHint, destructiveHint. The description adds that the tool is read-only, idempotent, and returns the full local authority table without pagination, providing behavioral context beyond 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: the first states purpose and return value, the second gives usage guidelines. No superfluous 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?

The description covers purpose, usage, return behavior (full table, no pagination), and distinguishes from siblings. With an output schema present, no further details on return format are needed.

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?

There are zero parameters, and schema coverage is 100%. The description adds no param-specific info because none are needed; baseline for 0 params is 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 lists imported public authority records for FOI/OIA routing, using the verb 'List' and specifying the resource. It distinguishes itself from sibling tools like import_authorities and list_requests.

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?

Explicitly states when to use ('browse existing slugs/names before drafting') and when not to, naming alternative tools (import_authorities for adding/upserting, list_requests for request data).

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, ensuring the agent knows it's safe and non-mutating. The description adds that it 'does not contact remote authorities', providing extra behavioral clarity 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?

Two compact sentences deliver full purpose, usage guidelines, and safety info. Front-loaded with the primary action and ordering. Every clause earns its place; no 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?

Given the tool's simplicity (1 parameter, no required fields, output schema exists), the description covers all necessary aspects: what it does, when to use it, parameter behavior, and safety guarantees. No gaps remain for an AI agent to handle this 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 covers the single parameter 'limit' with 100% description coverage. The description adds context: 'raise only when the agent needs a broader scan', which helps the agent decide when to increase the default. This adds value beyond the schema's own 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?

Description clearly states 'List locally tracked FYI/Alaveteli official information requests, ordered newest first'. It specifies the data source and ordering, and distinguishes from siblings by mentioning not to use for known ID (retrieve_request) or health metrics (check_status).

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?

Explicitly provides use cases ('dashboards, triage, or finding an ID before retrieve_request') and exclusions ('do not use when you already know the ID... or only need health metrics'), naming specific alternative tools. This leaves no ambiguity for an AI agent.

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, idempotentHint, and destructiveHint. Description adds 'fails if the ID is missing' and 'never contacts remote sites', which are useful beyond annotations. However, the core behavioral traits (read-only, idempotent) are redundant with annotations, preventing 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?

Three concise sentences, front-loaded with the core purpose, no wasted words. Every sentence adds distinct value: purpose, usage guidance, and behavioral transparency.

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 retrieval tool with one parameter and an existing output schema, the description covers all necessary aspects: what it does, when to use, failure behavior, and safety profile. No gaps.

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 parameter description in the schema is already clear ('Stable local request ID to load...'). The tool description does not add new parameter-level information beyond reinforcing the ID usage context. 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 clearly states the verb 'Retrieve' and resource 'one locally tracked FYI/Alaveteli request and its stored correspondence by request ID'. It explicitly distinguishes from sibling tools like list_requests and check_status, meeting the high standard for purpose 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?

Explicitly states when to use ('after list_requests when you need full text/history for a single request'), when not to use ('do not use for bulk listing or database health'), and names alternatives (list_requests, check_status). This is exemplary 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 read-only, idempotent, and non-destructive. The description adds significant context beyond annotations: it specifies the tool does not query the database or network, and it describes the return format (ranked hits with id, score, title). This enhances 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?

Three sentences, front-loaded with purpose, no filler. Every sentence adds value: purpose, usage guidance, and behavioral details. Highly efficient.

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 search tool with an output schema, the description covers all necessary context: experimental nature, read-only, idempotent, no DB/network, return fields. With annotations providing safety guarantees, this is 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 coverage is 100%, so the schema already documents both parameters. The description adds minimal parameter meaning beyond the schema. It mentions the query is tokenized into alphanumeric terms, which is already in the schema. 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 clearly states the tool searches a built-in sample FOI document corpus using an experimental in-memory index. It distinguishes itself from related tools like list_requests/retrieve_request by specifying it's for full-text search over sample data, not real database queries.

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 provides guidance: 'Use for experimental full-text search over sample titles/bodies; prefer list_requests/retrieve_request for real local SQLite requests.' This tells the agent when to use this tool and when to use 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it does not resolve conflicts or start network sync, confirming and supplementing annotations. It also clarifies it deals with locally tracked requests, adding context beyond 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 three sentences: purpose, usage context with alternatives, and behavioral notes. No redundant or unnecessary words; every sentence 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 the simple single-parameter input, full annotations, and presence of an output schema, the description sufficiently explains the tool's role in a workflow (after sync_monitor, before sync_resolve_conflict). It mentions the data source (locally tracked) and explicitly states what it does and does not do.

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 single parameter 'limit' has full schema coverage (100%) with detailed description. The tool description does not add additional parameter information beyond what's 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?

The description clearly states the tool lists locally tracked requests with offline sync metadata marked as conflict. It uses specific verbs and resources, and distinguishes from sibling tools like list_requests and sync_resolve_conflict.

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 guidance: use after sync_monitor shows conflict>0 to obtain IDs, and offers alternatives (sync_resolve_conflict to clear, list_requests for all requests). This gives clear when-to-use and when-not-to-use 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 provide readOnlyHint, idempotentHint, destructiveHint=false. Description adds 'does not start a sync job' and reinforces read-only, idempotent nature, providing context beyond annotations without contradiction.

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, front-loaded with key information (purpose, output list), followed by usage guidance. Every sentence is essential and concise.

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 zero parameters, a rich output schema, and 13 siblings, the description covers purpose, usage, behavioral traits, and sibling differentiation completely. No gaps remain.

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?

No parameters exist, so the description correctly omits parameter details. The schema covers 100% with no properties. The description adds value by listing the output fields, which is 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 clearly states the tool summarizes offline synchronization health with specific metrics (clean/dirty/conflict counts, queue depth, latest sync time, degradation indicators). It distinguishes from siblings sync_status, sync_conflicts, and check_status.

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?

Explicitly states when to use ('operations overview') and when not to, recommending alternatives for different tasks (sync_status for one request, sync_conflicts for conflicts, check_status for connectivity/totals).

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 (idempotentHint=true, destructiveHint=false), the description discloses that only local SQLite metadata is affected, no automatic merge, no remote API calls, no deletion, and idempotency for the same mark_clean value. This adds significant behavioral context.

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, well-structured, and front-loaded with the core action. Every sentence provides necessary information 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?

Given the complexity of sync conflict resolution, the description covers prerequisites, side effects, and differentiators. Output schema exists, so return values are handled. Complete and actionable.

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 descriptions, but the description adds behavioral context for mark_clean (e.g., effect on status and later push). This adds value beyond the schema alone.

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 resolves a local offline-sync conflict by updating sync metadata (mark_clean). It uses specific verbs and resources, and distinguishes from sibling tools like update_request, sync_conflicts, and sync_status.

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?

Explicitly states prerequisites (request must appear in sync_conflicts), when to use (for conflict resolution), and when not to use (ordinary field edits). It also guides the agent to prefer sync_conflicts for listing and sync_status for timestamps.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds 'does not mutate state or trigger network sync', providing extra behavioral context beyond 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 concise sentences, no wasted words. Purpose is front-loaded, and every sentence adds value.

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 annotations and output schema, description fully covers the tool's behavior, usage modes, safety profile, and ties to sibling tools. Nothing 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?

Only one parameter (request_id) with 100% schema coverage. Description adds critical semantics: omit for aggregate counts, provide for per-request details including specific fields (sync_status, last_synced_at, conflict_version).

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 specifies verb 'Read', resource 'offline-sync metadata', and two modes (aggregate or per-request). It clearly distinguishes from sibling tools like sync_monitor, sync_conflicts, and check_status.

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?

Explicitly states when to use ('Use when you need clean/dirty/pending/conflict numbers or per-request last_synced timestamps') and provides specific alternatives for related tasks, leaving no ambiguity.

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 idempotentHint=true and destructiveHint=false. The description adds context: 'mark the record dirty for offline sync', 'mutating but non-destructive', and 'does not call remote APIs', which enriches understanding beyond annotations. No contradiction.

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 with efficient front-loading: first sentence states action, then usage guidelines, parameter semantics, and behavioral notes. Every sentence adds 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?

Given 7 parameters, 3 required, and an output schema, the description covers purpose, usage, parameter behaviors, and side effects (dirty marking, no remote calls). It is complete for an AI agent to use 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?

Despite 100% schema coverage, the description adds crucial semantics: 'full replacement for those fields, not a sparse patch' for title/body, 'not appended to existing tags' for tags, and 'changing status does not submit or withdraw a remote request' for status. This goes well 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 specifies 'Replace editable fields on an existing local FYI/Alaveteli request by ID and mark the record dirty for offline sync', which clearly states the verb, resource, and scope. It also distinguishes from siblings by mentioning create_request for new ID and delete_request for removal.

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?

Explicitly states when to use: 'Use when the request already exists and fields changed', and provides alternatives: 'use create_request for a new ID and delete_request to remove'. Also notes it is safe to re-run with same values.

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