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

Annotations cover the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), and the description adds genuine value beyond them: it discloses the raw JSON return shape and the read-only-mode write restriction. It does not explain auth, rate limits, or why destructiveHint=false despite DELETE being available, but with annotations carrying the safety burden this is solid.

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 tight sentences, front-loaded with the core action, then scope examples, return format, and constraint. No wasted wording.

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 generic 7-parameter REST pass-through, the description is nearly complete: it states scope, examples, return format, and the read-only constraint, and the schema supplies the rest. Minor omissions (auth expectations, pagination/error behavior for arbitrary endpoints) keep it just short of full.

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 86%, so the schema already documents body, path, query, confirm, project and if_match with examples and defaults. The description adds nothing parameter-specific (e.g. how method interacts with confirm, or path formats), so the baseline 3 for high-coverage schemas applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Call') and resource ('any LegendKeeper REST v3 endpoint of this project directly'), and the parenthetical examples (boards, calendars, block-level edits, properties, invites, restores) hint at the advanced/raw-escape-hatch role no sibling fills. It is clear what the tool does, though the differentiation from the many specific CRUD siblings is left implicit rather than stated.

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 'advanced:' framing implies this is for operations not covered by the specific tools, and 'Writes are disabled in read-only mode' gives one situational constraint. However, it never explicitly says when to prefer api_request over siblings like create_document or update_map_feature, leaving routing to inference.

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 and openWorldHint=true, so the safety profile is covered. The description adds the return shape and framing as an entry point, but says nothing beyond the schema about the 60-second cache, traversal cost of depth, or result size for large worlds.

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 action and output shape and closed with the orienting purpose. No filler and nothing repeated from annotations or the schema.

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?

There is no output schema, so the description carries the burden of describing returns – and it does, listing ids, icons, tags and child counts from an indented outline. Complete enough for an agent to call it correctly, with only minor gaps around default depth behaviour and output size on large worlds.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-level meaning beyond the schema (it does not explain default depth of 2, the effect of parent scope, or the refresh cache behaviour) – it only describes the visible output fields.

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 ('Show') and resource ('the resource tree / the world's wiki hierarchy') and additionally describes the output form: an indented outline with ids, icons, tags and child counts. That is far more informative than a tautology, though it does not explicitly name a sibling it differs from (e.g. get_resource or search).

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?

'Start here to see how a world is organized' positions the tool as an orientation/entry point, which is implied usage guidance. However, no alternative is named and no condition for choosing browse_tree over get_resource or search is given, so the agent must infer when this is preferable.

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=false, idempotent=false, openWorld=true, so the safety profile is covered. The description still earns credit for disclosing a hard non-obvious capacity constraint ('A resource holds at most 5'), which materially affects invocation ordering. It does not say what happens at the limit or what permissions are required.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, and the essential information (what is created and where) is front-loaded ahead of the capacity limit.

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 7-parameter create tool with strong schema coverage and no output schema, the description plus schema give an agent enough to invoke correctly, and the sibling references list_projects/list_calendars live in the schema. It omits failure behavior at the 5-document cap and permission requirements, which would round it out.

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 86%, so the schema already documents resource, project, is_hidden, calendar_id, map_image_asset_id and the type enum. The description's list of types largely duplicates the enum description ('page (wiki text), map, time (timeline) or board') and adds no syntax or format detail beyond it. Baseline 3 is appropriate when the schema does the heavy lifting.

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 and clarifies what a 'document' actually is (a tab) plus the parent it attaches to ('a resource: a page, a map, a timeline or a board'), which the bare name does not convey. It stops short of naming a sibling (create_resource, update_document, create_from_template), so the agent gets a clear purpose but no explicit differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the verb 'Add ... to a resource' rather than stated: no when-to-use conditions, no guidance on choosing this over create_resource, create_from_template or update_document, and no prerequisites. The 'at most 5' note is a constraint, not routing 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 cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower. The description still adds real behavioral value by disclosing what gets copied (documents, properties, icon, tags), which goes beyond the annotations. It omits conflict/permission behavior and any warning that this is a non-idempotent write.

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?

A single front-loaded sentence with zero filler; the parenthetical efficiently enumerates the copied content. Every element earns its place with 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?

For a write tool with no output schema, the description plus fully-described schema gives an agent enough to invoke correctly: what is created and from what. It is only marginally short of complete because it does not signal that this is a non-idempotent creation that can produce duplicates on retry.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters (including name default, parent, project, template, include_children) are already documented in the schema. The description adds nothing beyond it, which meets the baseline 3 when schema does the heavy lifting.

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 ('Create a resource from a template') and clarifies what the operation copies. It is distinguishable from create_resource/create_resources by the template-driven nature, but it never names those siblings explicitly, leaving the differentiation to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: use this when creating a resource from an existing template rather than from scratch. There is no explicit when-to-use vs create_resource, no prerequisites, and no mention of the required template/listing step beyond the schema's reference to list_templates.

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 this is a non-read-only, non-idempotent, non-destructive, open-world write, so the safety profile is covered. The description usefully adds that coordinates are interpreted in the map's frame unless pixel mode is on, which is behavioral context beyond the annotations, but it says nothing about permission requirements, whether repeated calls duplicate features, or how resource/document resolution behaves when names are ambiguous.

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 most important fact (what can be added, and to what) is front-loaded ahead of the coordinate-mode caveat. Every clause 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?

For a 16-parameter creation tool with no output schema, the description omits the parameter-to-type mapping that an agent most needs: that pins/labels require `position`, and regions/paths require `points`, while `name` and `resource` are the only required fields. Annotations do cover mutability, so the gap is not fatal, but the schema alone does not force the agent to supply geometry for the non-pin types.

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 already 88%, so the schema carries most of the burden; the baseline is 3. The description still adds value by explaining that coordinates are relative to the map's frame and by naming read_document as the way to learn the bounds, knowledge that is not present in any individual property 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 opens with a specific verb+resource ('Add a pin, label, region, path or folder to a map document') and enumerates exactly the feature types in the `type` enum, so the agent immediately knows the scope. It is clearly distinguishable from siblings like update_map_feature and delete_map_feature, which operate on existing features.

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 second sentence gives real usage context for coordinates ([lat, lng] in the map's frame, or pixels with pixel_coordinates=true) and points the agent at read_document to discover the map bounds. However, it never says when to prefer this tool over update_map_feature, nor what preconditions exist (e.g. the resource/document must already exist, folder nesting must reference an existing folder feature).

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 a non-readonly, non-idempotent, open-world write, so safety is covered elsewhere. The description's useful addition is the return contract ('Returns the new id and its documents'), valuable since no output schema exists, but it says nothing about permissions, side effects on the tree, or ordering 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?

Two tight sentences, core purpose front-loaded and follow-up hints trailing. No filler, though the second sentence mixes tagging and icon advice somewhat loosely.

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 14-parameter tool with no output schema, the description covers the common create flow but omits the richer document modes (map/time/board via document_type, calendar_id, document_name) that the schema exposes. Adequate but with clear gaps for an agent needing the full capability surface.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 64% schema description coverage, the schema already documents most of the nuanced parameters (after, parent, content, is_hidden, document_type). The description reinforces 'content in Markdown' and icons but adds little syntax beyond that, 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?

Specific verb+resource with a clarifying gloss ('wiki article, location, character…') that tells an agent what a resource actually is. However, it doesn't distinguish itself from the sibling create_resources (bulk) or create_from_template, which is a real ambiguity in a crowded creation family.

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 hints 'Reuse existing tags (list_tags)' and 'give it an icon' point at related tools and imply a workflow, but there is no explicit when-to-use/when-not guidance versus the sibling creators. Usage 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?

Annotations cover readOnly=false, destructive=false, idempotent=false and openWorld=true, so the safety profile is already known. The description adds a trait the annotations do not encode: the request is 'atomic', implying all-or-nothing semantics. It does not state the failure/rollback behavior explicitly or any auth/rate-limit constraints.

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, zero filler. The batch scope and atomicity are front-loaded, and the key/parent_key workflow follows as a practical second sentence.

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 batch mutation tool with annotations present and no output schema, the description covers the essentials: scale limit, atomicity, ordering, and the parent/child nesting pattern. It omits what a caller gets back (e.g., whether created IDs are returned) and what happens to the batch if one item fails validation, both of which matter for a 100-item call.

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% – key, parent_key, parent, content and the rest are all documented in the schema itself. The sentence 'Give items a `key` and nest later items under them with `parent_key`' describes the hierarchy-building pattern, adding modest value, but largely restates what the per-field schema text already says. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource with explicit scope: 'Create up to 100 resources in one atomic request.' The batch scope and atomicity distinguish it from the singular create_resource sibling without the agent needing to open either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete usage contexts ('scaffolding a region, a cast of NPCs or a whole hierarchy'), which tells the agent when bulk creation is appropriate. It never explicitly names the alternative (create_resource for single items) or states exclusions, so it stops short of full when/when-not guidance.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive write. The description adds nothing beyond that profile — no mention of permissions, side effects (e.g., that a missing lane name causes a new lane to be created), or the open-world resource resolution behavior. The 'full story' link sentence is the only behavioral flavor, and it maps to a parameter.

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 short sentences, front-loaded with the action, with no filler. It is efficient but arguably under-specified for a 15-parameter mutation tool, which is a completeness problem rather than a verbosity one.

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 15-parameter, non-idempotent, open-world creation tool with no output schema, the description is far too thin. It does not explain the two required parameters' roles, the optional link relationship, or what the caller gets back, leaving the agent to rely entirely on the schema.

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 67%, so the schema already documents most parameters (start/end calendar formats, lane creation, resource resolution, project/document defaults). The description reinforces only the `link` parameter's intent ('page that tells the full story') and adds nothing for the undocumented color, is_hidden, icon_glyph, end_minutes, and show_on_calendar fields.

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 verb and resource ('Add an event to a timeline document'), which clearly separates it from update_timeline_event and delete_timeline_event. However, it does not distinguish itself from other creation tools beyond the obvious verb, relying on the noun to carry differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus alternatives, no preconditions, and no mention of update_timeline_event for modifying an existing event. The only hint ('Link it to the page that tells the full story') describes a parameter rather than tool selection.

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 mutation profile (readOnly=false, destructive=false, idempotent=false, openWorld=true). The description adds a useful ordering fact — the lane is appended after existing lanes — but says nothing about name uniqueness, limits on lane count, or permissions.

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?

A single sentence that front-loads the action and includes the one behavioral detail worth stating. Nothing is wasted.

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 mutation tool with no output schema, the description doesn't say what is returned (e.g., a lane id) or what happens on duplicate names. Adequate but leaves real gaps given 6 parameters and no return documentation.

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 67%, and the description adds no parameter meaning beyond the schema (name, size, color, project, document, resource). Baseline 3 is appropriate since the schema does most of the work.

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?

Clear specific verb+resource ('Add a lane (row) to a timeline') with a scope detail (placed after existing lanes). An agent can distinguish it from create_timeline_event, though the description never names that sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to create a lane versus a timeline event, no prerequisites, and no alternatives mentioned. The only usage-adjacent information is the placement behavior (appended after existing lanes).

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 destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description earns credit for adding reversibility context the annotations cannot express: the deleted document can be restored via POST /resources/{id}/docs/{docId}/restore. It still does not say what downstream references break or whether the operation is immediate.

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, zero filler, with the scope constraint (one document/tab) front-loaded and the recovery endpoint compactly parenthesized.

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 destructive mutation with no output schema, the description plus annotations cover the essentials: what it deletes, that it is reversible, and how to reverse it, while confirm semantics live in the schema. Minor gap: no statement of permission requirements or side effects on resources referencing the deleted document.

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 schema itself documents all four parameters including the required confirm=true with a user-consent instruction. The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource, and immediately narrows scope to "one document (tab) of a resource," which distinguishes it from delete_resource. However, it never names the sibling it is adjacent to (delete_resource, update_document) so the differentiation is implicit rather than explicit.

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 when deletion is appropriate by framing it as a per-document (tab) operation, and it points to a recovery route via api_request restore. It gives no explicit when-not guidance (e.g., use update_document to clear content instead of deleting) and names no alternative tool.

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 destructiveHint=true, idempotentHint=true, openWorldHint=true and readOnlyHint=false, so the safety profile is fully carried by structured data. The description adds no behavioral context of its own—nothing about what gets destroyed, whether deletion is recoverable, or the confirm gate.

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?

A single front-loaded sentence with zero waste that puts the action and target first. It is efficient, though it offers nothing in the way of additional structure or emphasis.

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 destructive 5-parameter delete tool, the description is thin: it never mentions the required confirm flag or the project/document scoping that the schema exposes. Annotations cover safety and there is no output schema, but the definition is only minimally 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 80%, so the schema already documents resource, project, document, and confirm (including 'Must be true'). The description adds no parameter meaning beyond what the schema provides, so the 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?

States a specific verb ('Delete') and resource ('a feature ... from a map') and enumerates the feature types (pin, label, region, path, folder), which is more precise than the bare name. An agent can identify the action unambiguously, though it doesn't explicitly contrast with siblings like update_map_feature or delete_resource.

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?

No guidance on when to use this tool versus alternatives such as update_map_feature, delete_document, or delete_resource. No prerequisites or conditions are mentioned; the agent must infer all routing decisions.

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 destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-redundant behavior: deletion is a move-to-trash (recoverable), cascade=true also removes child resources, and an id is returned for restoration — none of which the annotations convey.

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 short sentences, zero filler, with the scope of the operation (documents, cascade children) front-loaded and the recovery path second. Every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully tells the agent that the call returns an id consumed by restore_resource, and the annotations plus fully-documented schema cover the remaining safety and parameter needs. Nothing required to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (including the mandatory confirm and the project defaulting rule) are already documented. The description restates the cascade effect but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Move a resource ... to the trash') and clarifies the semantics of the operation — it is a soft delete, not a permanent removal. It also names the inverse sibling (restore_resource), letting an agent distinguish this from delete_document or delete_map_feature without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description routes the agent to restore_resource for undoing the action and implies reversibility, which is useful context. However, it never states when to prefer delete_resource over the many other delete_* siblings, nor any preconditions beyond what the schema's confirm field already carries.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not state that the deletion is irreversible, that confirm must be true to proceed, or what happens to associated data.

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?

A single, front-loaded sentence with zero filler. It is efficient, though the brevity shades into under-specification rather than disciplined 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?

For a destructive, confirm-gated mutation with no output schema, the description omits the two things an agent most needs: that the action cannot be undone and that the confirm flag must be set to true. The annotations carry the destructiveness hint, but the operational gate is left entirely to the schema.

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 80% and the schema itself documents project, document, resource, and even the confirm gate ('Must be true.'). The description contributes no parameter meaning, so the baseline 3 applies when the schema does the heavy lifting.

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 verb and resource are stated ('Delete an event from a timeline'), so the purpose is not misleading, but the sentence is a near-restatement of the tool name delete_timeline_event and adds no distinguishing detail versus siblings like delete_document, delete_resource, or delete_map_feature.

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?

There is no when-to-use guidance, no mention of prerequisites (e.g., the confirm flag), and no reference to alternatives such as update_timeline_event or deleting the parent lane. The agent must infer everything from the name.

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, openWorldHint, and destructiveHint=false, so safety is covered. The description adds a real behavioral fact beyond that: the call returns document references/metadata rather than document content, which the agent must fetch separately via read_document. It does not cover error behavior for missing resources, but the annotations lower the bar.

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 filler; the return-field enumeration comes first and the sibling routing second. Every clause carries information the agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description carries the return-value burden, and it does so by enumerating the fields returned. Combined with rich annotations and a fully documented two-parameter schema, nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both 'project' (project name, omit for default, see list_projects) and 'resource' (id or exact name/alias, case-insensitive) are fully documented in the schema. The description adds no syntax or lookup guidance for either parameter, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (get) and resource (one resource's details) and then enumerates exactly what is returned: path, tags, aliases, icon, banner, documents, sidebar facts, and children. It also separates itself from the read_document sibling, so an agent can tell it apart without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description routes the agent explicitly: use this to fetch resource metadata, and 'Use read_document to read a document's content.' That names an alternative and the condition selecting it, but it does not say when to prefer this over browse_tree or search for locating a resource.

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 the safety profile is covered. The description adds useful behavioral context by disclosing that entries come back with ids and URLs and that URLs are consumable by pages, banners, maps and events. It says nothing about pagination or the 1000-item ceiling implied by the limit parameter.

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 short sentences, front-loaded with the core action and the payload contents. The second sentence is tangent-adjacent but earns its place by telling the agent why the returned URLs matter, sparing it a follow-up lookup.

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?

There is no output schema, so the description is the only source of return-value information; it partially fills that void with 'ids and URLs' but omits pagination, folder nesting, and result ordering. For a read-only listing tool with annotations covering safety, this is adequate but leaves real 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 67%, with project and folder_id documented in the schema (including a list_projects cross-reference) and only limit undocumented. The description adds no parameter meaning of its own and does not clarify limit's default/range behavior, so it hovers at the minimum-viable baseline.

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 (List) and a precise resource (the world's asset library), and enumerates what that library contains (uploaded images, maps, folders). An agent can tell this apart from create_resource, upload_image, or browse_tree without opening schemas, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description never says when to call this instead of search, browse_tree, or list_projects. The closing note that image URLs can be used in pages/banners/maps implies a downstream workflow but gives no selection criteria or prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is fully covered without the description. The description adds no further behavioral context such as auth/permission needs, scoping by project, or whether custom calendars are user-created. It does hint at the returned content, which is mildly useful.

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?

A single sentence with a front-loaded verb-resource phrase and the return fields appended; every clause carries information and nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description helpfully discloses the returned fields (id, name, months, eras), which is the main gap it needs to fill. Annotations cover safety, and the sole parameter is covered by the schema. Only the lack of any guidance on when to call it versus other list_* tools keeps it from a 5.

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%: the single optional `project` parameter is documented in the schema, including the cross-reference to list_projects. The description adds nothing about the parameter, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("List the calendars timelines can use") and enumerates the domain with concrete examples (gregorian, harptos, exandria, plus custom). It also names the returned fields. It does not explicitly route against a sibling (e.g. list_projects or get_resource), but the resource is 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 phrase "calendars timelines can use" implies this is a prerequisite lookup before creating timeline events or lanes, but there is no explicit when-to-use statement, no preconditions, and no named alternative. Usage must be inferred from the sibling set.

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

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

Annotations already establish the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, and the description adds genuine context beyond them: email fields are conditionally redacted based on ADMIN key privileges. That conditional-disclosure detail is exactly the kind of non-obvious behavior an agent needs before promising a caller email data.

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?

A single sentence with the core action front-loaded and the privilege caveat tucked into a parenthetical. Nothing is wasted and nothing important is buried.

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-optional-parameter read tool with no output schema, the description covers what is returned (members and roles) and the one surprising behavior (email redaction). It stops short of noting pagination or result-size behavior, but nothing essential to calling it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter, and the schema documents it fully at 100% coverage (including the 'omit to use default; see list_projects' hint). The description adds nothing about the project argument, so the baseline 3 for schema-carried semantics applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the members of the world') plus what is returned ('their roles'), so the agent knows exactly what this does. No sibling is a plausible substitute (the other list_* tools cover projects, tags, templates, calendars, assets), but the description never names that distinction explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus alternatives, and no prerequisites for the caller. The ADMIN-key note is about data visibility rather than invocation guidance, so the agent must infer the use case from the name alone.

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 the safety profile is covered. The description adds real context beyond that: it discloses the shape of the response (default project, write-enabled flag) and the tenancy constraint that each API key maps to exactly one project - information an agent needs when reasoning about writes elsewhere.

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, zero filler, with the core resource identified in the first clause and the scoping/tenancy fact placed last as supporting context. Nothing repeats the tool name as a tautology.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters, no output schema, and annotations covering safety, the description is nearly self-sufficient because it explicitly states what is returned (configured projects, default project, write-enabled status). Only a note on how project identity is used by subsequent tools would make it fully complete for an orientation call.

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 takes zero parameters, so the baseline is 4. There is nothing parameter-related the description could usefully add, and it correctly adds none.

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 the LegendKeeper projects (worlds)') and immediately scopes it to 'this server is configured for', plus clarifies the parenthetical synonym 'worlds'. No sibling does anything comparable (the other list_* tools enumerate tags, templates, calendars, members, assets), so an agent can identify it unambiguously.

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 mention of 'the default project and whether writes are enabled' implies this is an orientation/discovery call, but there is no explicit when-to-use statement such as 'call this before any write tool to learn which project an API key targets'. Usage must be inferred from the returned-content hint 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds value beyond that by disclosing the return content (each tag plus its resource count) and the recommended workflow position (pre-tagging lookup), though it does not discuss pagination or scale limits on the listing.

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, zero waste. The capability statement is front-loaded and the usage guidance follows immediately; every clause 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?

No output schema exists, but the description communicates what is returned (tag names with usage counts), which is the key missing piece. Project scoping is handled by the schema, so the definition is nearly complete; only pagination or result-size behavior is unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single 'project' parameter is fully documented in the schema, including the default behavior and a pointer to list_projects. The description adds nothing about the parameter, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List every tag') plus the exact payload ('with how many resources carry it') and the scope ('in the world'). No sibling tool deals with tags, so there is no ambiguity to resolve, and the agent knows precisely what it will get back.

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 the condition for calling it: 'Check this before tagging so you reuse existing tags with the exact same spelling.' It both tells the agent when to use it and why (avoiding duplicate/typo'd tags), leaving nothing to inference.

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, openWorldHint and destructiveHint=false, so the safety profile is fully covered. With no output schema, the description's listing of returned fields (id, name, parent) adds genuine value, but it says nothing about scoping, ordering, or whether templates come from a fixed catalog vs the project.

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, zero waste. The core action and returned fields are front-loaded and the related tool is named second.

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 no-required-param read tool, the description plus annotations plus the fully documented schema cover everything necessary to invoke it. It could note how many templates are expected or whether the project argument filters the listing, but nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% – the single 'project' parameter is fully documented, including its default and a cross-reference to list_projects. The description contributes no additional parameter meaning, which is the expected baseline when the schema does the work.

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 gives a specific verb and resource ('List resource templates') and even names the returned fields (id, name, parent), so the agent knows exactly what comes back. It partially differentiates from create_from_template by framing that tool as the instantiation step, but it doesn't distinguish itself from other list_* siblings.

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 second sentence points to create_from_template as the follow-on action, which implies the tool's role in a workflow. However, it offers no when-to-use/when-not guidance relative to siblings like browse_tree or get_resource, and no prerequisites.

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=false, idempotentHint=true, and destructiveHint=false, so much of the safety profile is covered. The description still adds real value beyond them by disclosing that children move with the resource and that the operation can be a pure reorder, which tells the agent about the cascading effect of the call.

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?

A single front-loaded sentence naming the action, target, and the two things it changes. Every clause earns its place, and the parenthetical about children is the most important detail delivered inline.

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 five-parameter mutation tool with fully documented schema and annotations covering safety and idempotency, the description supplies what structured fields cannot: the subtree cascade and the reorder capability. Minor gaps remain (behavior when 'before' and 'after' conflict, ordering relative to a new parent), but 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 100%, so 'new_parent', 'before'/'after', and 'project' are all documented in the schema itself. The description's phrase 'to another parent and/or position among its siblings' usefully frames how those parameters combine (parent optional, position optional), but adds no syntax or format detail beyond the schema, so the baseline 3 is right.

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 ('Move') and resource, plus the two distinct effects: reparenting and sibling reordering. It implicitly separates itself from update_resource by focusing on location rather than content, but it never names an alternative, so sibling differentiation is only inferred.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the description ('move ... to another parent and/or position'), but there is no explicit when-to-use guidance and no statement of when to prefer this over update_resource, which a reader might assume could also change parents. Callers must infer the boundary themselves.

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=false, and openWorldHint, so the safety profile is covered. With no output schema, the description earns credit by describing the actual return shape per document type (Markdown pages with lk:// links, map coordinates, timeline lanes, board text), which the agent could not otherwise anticipate.

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 information-dense sentences with the core purpose front-loaded and no filler. The semicolon-separated enumeration of per-type outputs is efficient, though slightly list-heavy for the 10% weight.

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 read-only tool whose annotations cover the safety profile, the description supplies the one thing structured fields lack: what content is returned for each document type. Missing only error/edge behavior (e.g., resource not found, empty document) and the format/opaque_blocks interplay, which keeps it short of a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter is already documented, making 3 the baseline. The description adds only marginal value beyond the schema, mainly reinforcing the omitted-'document' fallback chain that the schema already states as 'Omit to pick the resource's main document.'

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: 'Read a document of a resource,' then enumerates what each document type returns (pages as Markdown, maps as pins/regions/paths, timelines as lanes/events, boards as text). It clearly separates this from write_page/create_document siblings, though it never explicitly contrasts with get_resource or browse_tree, which also fetch content.

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 documents the fallback behavior when 'document' is omitted ('the first page is used, else the first map, timeline or board'), which is useful selection context. However, there is no guidance on when to use read_document versus get_resource, browse_tree, or search, and no exclusions or prerequisites are 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?

Annotations already declare destructiveHint=false, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds a genuine behavioral precondition not present in structured data: the parent resource must not itself be deleted for the restore to be valid. It stops short of describing failure behavior or permission requirements.

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?

A single front-loaded sentence with the core action first and the precondition second. No filler, 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?

For a low-complexity two-parameter mutation with full schema coverage and annotations covering safety and idempotency, the description supplies the one non-obvious constraint. It lacks any mention of return values or how partial/precondition failure surfaces, but no output schema exists and nothing essential to invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (project and resource_id) are already documented, including the "Omit to use the default project" guidance. The description adds no format or syntax detail beyond what the schema provides, making the baseline 3 correct.

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 precise verb and resource ("Restore a deleted resource from the trash") plus the scope constraint. No sibling offers restore semantics, so the operation is unambiguous, though it does not explicitly contrast itself with siblings like delete_resource or update_resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the word "restore" — it applies to previously deleted resources — and a precondition is given (parent must not be deleted). However, there is no explicit when-to-use guidance, no statement of what to do instead if the parent is deleted, and no reference to any alternative tool.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds real value beyond them by disclosing relevance ordering ('best match first') and the return payload (ids, paths, tags, matching passage), which matters since there is no output 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?

Two sentences, zero filler, with the search scope and ordering front-loaded and the return shape following. Every clause 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?

With no output schema, the description helpfully covers the return fields and the ranking order. The remaining gap is the limit parameter, which is undocumented in both the schema and description, leaving result-count behavior unstated.

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 67%, in the middle band. The description's 'names, aliases and document content' loosely mirrors the query parameter's schema text ('names, aliases and page text') but adds nothing about limit's default/cap or the project scoping beyond what the schema already says. 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?

States a specific verb ('Full-text search') and the exact fields searched (names, aliases, document content), which distinguishes it from retrieval siblings like get_resource and browse_tree. It stops short of naming an alternative tool explicitly, so it is clear but not fully sibling-differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the scope statement (find things when you don't know the id), and the project parameter description routes to list_projects for project discovery. However, it never states when to prefer search over browse_tree, get_resource, or read_document, nor any when-not conditions.

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

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

Annotations already cover the safety profile: not read-only, idempotent, non-destructive, and open-world. The description adds useful behavioral context by stating that it creates the infobox or property group when it does not exist yet, but it omits permissions, side effects beyond creation, and removal behavior noted only in the 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?

Two tight sentences with no filler. The core action and location are front-loaded, followed immediately by the creation behavior.

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 a rich six-parameter schema, nested facts object, and annotations covering mutation safety, the description is largely complete for calling the tool. It could be stronger with usage guidance or explicit side-effect expectations, but no output schema exists and return values need not be explained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all six parameters, including fact name/value semantics, null removal, case-insensitive updates, and target options. The description's examples slightly enrich understanding of facts but do not add 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 ('Set'), resource ('facts'), and location ('infobox or resource sidebar'), with examples like Race, Age, Ruler, and Population. It is clearly not a generic page-writing tool, but it does not explicitly differentiate itself from siblings such as write_page or update_document.

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 no explicit when-to-use guidance or alternatives. It explains what the tool does and that it creates the infobox/property group when missing, but an agent gets no instruction on when to prefer this over write_page, update_document, or other sibling tools.

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=false, idempotentHint=true, and destructiveHint=false, so the mutation and idempotency profile is covered. The description adds little beyond that: it does not state whether omitted/nullable fields are left unchanged (partial vs full update), nor any auth or return behavior. Baseline 3 is appropriate.

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?

A single front-loaded sentence with the primary verb first and no filler. It is dense but every clause maps to a capability; the trailing 'set a timeline's calendar or a map's image' is slightly run-on but still compact and useful.

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 mutating tool with an annotations safety profile and no output schema, the main missing element is partial-update semantics: since most fields are nullable with null defaults, an agent cannot tell whether passing null clears or preserves a value. Safety and return-format gaps are covered by annotations and the absence of an output schema, but the update semantics gap is a real one.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage at 63%, the description compensates well by mapping natural-language actions onto the terse parameters: rename→name, hide/show→is_hidden, full width→is_full_width, timeline calendar→calendar_id, map image→map_image_asset_id. The remaining params (document, resource, project) are already documented in the schema, so the description adds genuine meaning.

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+resource combination (updates to a document) and enumerates the exact mutable facets: rename, hidden state, full width, timeline calendar, map image. It implicitly distinguishes from create_document/read_document/delete_document, though the phrasing 'a timeline's calendar or a map's image' slightly blurs whether it edits a timeline/map or the document's properties.

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 lists what can be changed but gives no when-to-use guidance, no alternatives, and no exclusions. There is no hint about when to prefer this over update_resource, update_timeline_event, update_map_feature, or update_timeline_lane, nor any prerequisite information.

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=false, destructiveHint=false, idempotentHint=true and openWorldHint=true, so safety and idempotency are covered. The description adds nothing beyond that: it never says whether omitted parameters leave fields untouched or whether passing null clears them, nor how errors or non-existent feature_ids are surfaced. For a 15-parameter mutation tool this leaves real behavioral questions unanswered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One compact sentence, front-loaded with the verb and resource, and the operation list is terse. No filler, no repetition of the tool 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?

A single short sentence is inadequate for a 15-parameter mutation tool with 33% schema coverage, no output schema, and several undocumented fields (feature_id, pixel_coordinates, extra, project, document) plus the unresolved position-vs-points distinction. Critical semantics such as partial-update behavior and pixel vs geographic coordinate modes are simply absent.

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 only 33% across 15 parameters, so the description is expected to compensate and must map operations to fields. It is not an operation list; it is a single sentence naming no parameter, so it contributes nothing that the schema does not.

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?

Specific verb ('Change') plus resource ('map feature'), with an enumeration of the six operation families (rename, move, reshape, relink, restyle, hide). This lets an agent distinguish it from create_map_feature / delete_map_feature even though those siblings are not named. It stops short of a 5 only because sibling differentiation is left implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the verb list: the agent can infer this is the tool for modifying an existing feature rather than creating or deleting one. But there is no explicit when-to-use statement, no when-not-to-use, and no mention of prerequisites (e.g. that the feature must already exist, or that you need its feature_id from browse_tree/search).

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 non-read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds a useful scope boundary (this tool does not touch content, facts, or tree position), but for a 16-parameter partial-update mutation it never states whether omitted fields are left unchanged, what happens on conflicting tag params, or the admin requirement for visibility.

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, zero filler: the capability is front-loaded and the routing alternatives follow immediately. Nothing could be removed without losing routing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-param mutation with 1 required param, no output schema and only 63% schema coverage, the definition is adequate but leaves real gaps: partial-update semantics and the interaction between tags/tags+add_tags/remove_tags are unaddressed. Annotations do carry the safety profile, so the omission is not fatal.

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 63%, above the baseline threshold, and the schema already documents replace semantics for tags/aliases and the add/remove variants. The description's value is mostly vocabulary mapping (icon -> glyph/color/shape, visibility -> is_hidden, lock -> is_locked), with no added meaning for the replace-vs-add/remove distinction or the unmentioned project parameter.

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 (Change) plus the exact resource and enumerates the mutable attribute set (name, tags, aliases, icon, visibility, lock, banner). It also names three siblings it is not (write_page, set_facts, move_resource), so an agent can separate it from the adjacent update tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit routing map: content edits go to write_page, facts to set_facts, tree position to move_resource, everything else to this tool. That is exactly the when-to-use-something-else guidance the dimension asks for, delivered compactly.

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=false, destructiveHint=false, idempotentHint=true and openWorldHint=true, so the safety/idempotency profile is covered. The description adds only the partial list of updatable fields and says nothing about partial-update semantics or behavior when event_id/resource is not found.

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?

A single front-loaded sentence with no filler; the scope is stated immediately. It is appropriately tight, though its brevity borders on under-specification for a 15-param 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 15-parameter mutation tool with no output schema and 40% parameter coverage, the description is too thin: it omits update semantics, most mutable fields, and return behavior. It does not give the agent enough to call the tool confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 15 parameters and only 40% schema description coverage, the description must carry weight, but it enumerates barely half the mutable fields (name, dates, lane, link, style) and is silent on is_hidden, show_on_calendar, icon_glyph, start/end minutes, project, and document. It does not compensate for the coverage 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?

States a specific verb ('Change') and resource ('a timeline event'), and names the fields it touches, so an agent can tell it apart from create_timeline_event and delete_timeline_event. It is clear but does not explicitly differentiate itself from those siblings in prose.

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?

There is no guidance on when to use this versus create_timeline_event, delete_timeline_event, or the lane tools, and no mention of prerequisites (e.g., that the event must already exist). Usage is only implied by the verb.

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 disclose the operational profile (readOnly=false, openWorld=true, idempotent=false, destructive=false). The description adds the return contract (asset id + URL), which is useful, but it does not warn that non-idempotency means repeat uploads create duplicate assets, nor mention permissions or size/rate limits.

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, zero filler, and the core action is front-loaded before the integration details. Every clause carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description steps in by naming the returned fields (asset id and URL), and the schema covers accepted formats. Minor gaps remain around failure modes and duplicate handling, but the essentials for calling correctly are present.

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 80%, so the schema already documents name, source, project, and folder_id. The description contributes nothing beyond that for parameters (it only mentions the URL output), so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ('Upload an image to the world's asset library') and states the return value ('asset id and URL'). No sibling tool performs uploads, so the distinction from list_assets/create_resource etc. is implicit but clear from the verb.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete downstream usage context: the returned URL goes into a page image, a resource banner_url, or a map_image_asset_id. This tells the agent what the tool feeds into, but it does not state when *not* to use it or name an alternative upload path.

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 declare a non-readonly, non-destructive, non-idempotent, open-world write; the description goes beyond them by disclosing atomicity and the optimistic-concurrency safeguard against overwriting app-side edits. It stops short of describing what is returned or how failures surface.

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 tight sentences, front-loaded with the action, then content semantics, then the safety guarantee. Every sentence carries information an agent needs before calling.

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 7-parameter mutation tool with no output schema, the description covers content format, concurrency safety, and mode semantics delegated to a well-documented schema. Missing only return-value information and explicit sibling differentiation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for the markdown parameter by explaining mention/link syntax resolution and supported block types (callouts, secrets, tables, task lists, images). The expected_version rationale is also clarified even though the schema already touches it.

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 concrete verb+resource ('Write Markdown to a page document') and enumerates the Markdown features handled, so the agent knows exactly what content form is accepted. It does not, however, distinguish itself from the sibling update_document, which an agent might plausibly confuse it with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational guidance: pass expected_version (from read_document) so concurrent edits are not overwritten, and the schema elaborates mode-specific behavior. There is no explicit 'use this instead of X' routing against the sibling update_document tool.

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