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

No annotations are provided, so the description carries the full burden. It implies a privileged mutation ('admin action') but does not disclose consequences, reversibility, permission requirements, or the multi-step confirmation flow beyond what the confirm/confirmation_data schema fields already state. It adds some context (admin-level, bulk-targeted) but falls short of what an unannotated mutation tool needs.

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 waste; the core action is front-loaded and the prerequisite discovery step follows immediately. Every sentence earns its place.

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

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

For an unannotated mutation tool with a nested confirmation_data object and no output schema, the description is only minimally sufficient. The two-step discover-then-execute pattern is hinted at but the confirmation retry behavior (requires_confirmation) is left entirely to the schema, so an agent gets an incomplete operational picture from the description alone.

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 ids, action, confirm, and confirmation_data. The description only confirms the tool targets 'selected instances' and adds no syntax, format, or naming details beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Execute an admin action on selected Article instances'), and explicitly contrasts itself with the sibling actions_article, which is described as the discovery tool. An agent can distinguish this executor from the discovery and bulk siblings without opening a schema.

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

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

Gives clear workflow context by directing the agent to actions_article to discover valid actions before calling this tool. However, it offers no guidance on when to prefer this over bulk_article or how it relates to update/delete_article, so the routing is partial rather than complete.

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?

No annotations are provided, so the description carries the full burden. The phrase 'admin action' hints at elevated privilege, but nothing states that actions may be destructive or irreversible, that some actions require a confirmation round-trip, or what permissions are needed — the confirm/confirmation_data mechanics are only discoverable from 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 short sentences, the core action front-loaded, with the routing hint second. Every word earns its place and there is 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 mutation-capable dispatcher with no annotations and no output schema, the description covers the routing story but omits the confirmation workflow, permission expectations, and failure modes. The 100% schema coverage closes some of the gap, so this is adequate but incomplete.

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% (all four parameters documented, including the two-step confirm/confirmation_data flow), so the baseline is 3. The description adds nothing about parameter meaning, valid action names, or ID semantics beyond what the schema already provides.

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 ('Execute') plus a specific resource ('admin action on selected Author instances'), and explicitly names the sibling tool (actions_author) that serves a different purpose. An agent can distinguish it from actions_author without opening either schema.

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

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

Names the discovery alternative and the condition that routes an agent there ('Use actions_author to discover available actions'), which effectively establishes the discover-then-execute workflow. It does not, however, state when this tool should not be used (e.g., for a single delete, where delete_author/bulk_author exist).

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?

No annotations are provided, so the description carries the full burden. It says 'Execute an admin action' (implying mutation) but never discloses that actions may be destructive, that a requires_confirmation handshake exists, or what permissions are needed
9 all of that lives only in the parameter descriptions.

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, front-loaded with purpose and followed immediately by the discovery pointer. No filler or 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 generic, potentially destructive action executor with no annotations and no output schema, the description should at least flag the confirmation workflow across calls. The schema covers the parameters, but the description leaves notable behavioral gaps.

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

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

Schema description coverage is 100%, documenting ids, action, confirm, and confirmation_data, so the schema does the heavy lifting. The description adds no syntax, format, or example detail beyond it, making the baseline of 3 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 (Execute), resource (MCP Token instances), and scope (admin action), and explicitly names the sibling actions_mcptoken as the discovery counterpart. An agent can tell it apart from delete_mcptoken, update_mcptoken, and bulk_mcptoken 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?

It routes the agent to actions_mcptoken for discovery, which is real workflow guidance, but it gives no condition for choosing this generic executor over delete_mcptoken, update_mcptoken, or bulk_mcptoken. 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?

No annotations are provided, so the description carries the full disclosure burden. It does state the return content ('action names and descriptions'), which is the key behavioral trait for a discovery tool, but it says nothing about permissions required for 'admin' actions, whether results are static, or any rate/side-effect profile. Adequate but incomplete for an unannotated tool.

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

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

Two compact sentences with the core purpose front-loaded and the routing hint immediately after; nothing is redundant or padded.

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 or annotation block, and the description compensates by naming what is returned (action names and descriptions). For a zero-param listing tool the remaining gaps are minor (permission/scope context, whether other resource families have equivalent tools).

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 per the baseline there is nothing for the description to disambiguate. No parameter explanation is needed or missing.

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: 'List available admin actions for Article.' It also contrasts cleanly with the sibling action_article, which executes the actions this tool enumerates, so an agent can distinguish the discovery tool from the execution tool without opening either schema.

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

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

The description names the alternative explicitly ('can be executed via action_article'), giving a clear discovery-then-execute workflow. It stops short of stating an explicit condition or exclusion (e.g. 'use action_article directly when you already know the action name'), so it is clear context rather than a full routing rule.

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?

No annotations are provided, so the description carries the burden, and it does disclose the shape of the result ('action names and descriptions') even though no output schema exists. It is silent on permissions or rate limits, but for a zero-parameter read-only listing the remaining behavioral surface is small.

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 zero filler; the purpose is front-loaded and the cross-reference to action_author immediately follows. Nothing could be trimmed 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?

With no output schema and no annotations, the description must cover returns and routing, and it does both in brief. It is complete enough to call correctly, though a note on when the action list changes or requires admin privileges would close the last gap.

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 no parameters (empty schema, 100% coverage), so per the baseline this scores 4. The description correctly adds no parameter detail because there is none to add.

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 available admin actions for Author') and immediately distinguishes itself from the executor sibling by noting the results are 'executed via action_author.' An agent can tell this is the discovery tool and action_author is the execution tool without opening either schema.

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

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

The pairing with action_author gives clear implied context: call this first to learn which actions exist, then invoke one via action_author. There is no explicit when-not or prerequisite guidance (e.g., caching, permissions), but the discovery-vs-execution routing is unambiguous.

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?

No annotations are provided, so the description carries the disclosure burden. It does state what is returned (action names and descriptions), which is meaningful since no output schema exists, but it never says this is a read-only/no-side-effect operation, nor does it mention pagination or auth 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 tightly-written sentence with the purpose front-loaded and the follow-up tool named second. No filler or 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 zero-parameter discovery tool with no annotations and no output schema, the description covers both what it does and what it returns, which is the essential information. It falls short only on stating that the call is safe/read-only and how the returned action names map onto action_mcptoken inputs.

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 there is nothing to document and the schema is trivially complete. Baseline 4 applies; there is no parameter behavior the description could add.

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 resource (available admin actions for MCP Token), and explicitly names the sibling 'action_mcptoken' as the consumer of what it returns. An agent can immediately distinguish this discovery tool from the execution tool 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?

The phrase 'can be executed via action_mcptoken' establishes the workflow context: call this to discover action names, then invoke action_mcptoken with them. It's clear implied usage with the follow-up tool named, but there is no explicit when-not or exclusion 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?

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only search, but says nothing about matching semantics (prefix vs substring vs fuzzy), ordering, or what a suggestion contains (id/label/pk?), all of which matter for FK/M2M widget use.

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 and resource, with no redundant or filler text. Nothing could be cut without losing information.

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

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

For a simple 2-param read tool with no output schema and no annotations, the description covers purpose and rough use case but leaves the return shape and match behavior undefined. Adequate but with a clear gap for an autocomplete tool whose output format is the whole point.

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% with only 2 params, so the schema already documents both `term` and `limit` fully. The description adds no syntax, format, or matching guidance beyond that, making 3 the correct 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 (search) and resource (Article instances) plus the intent — autocomplete suggestions. It's clearly distinguishable from sibling entity autocompletes by name, but it doesn't differentiate itself from list_article or find_models, which also return collections.

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?

"Useful for populating FK/M2M field widgets" gives an implied usage context, but never states when to choose this over list_article or find_models, nor any prerequisites. Usage is inferable rather than explicit.

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

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

No annotations exist, so the description carries the behavioral burden. 'Search' implies a non-destructive read, but nothing is said about authentication, result ordering, or behavior when 'term' is omitted. Adequate but thin for a tool with zero annotation coverage.

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 core purpose front-loaded before the usage hint. Every sentence earns its place.

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

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

For a simple two-parameter, zero-required autocomplete read with full schema coverage and no output schema, the description covers purpose and intended use. It could still note behavior on empty 'term', but nothing essential to 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 'term' and 'limit' (including the default of 10) are already fully documented. The description adds no matching semantics, case sensitivity, or result-ordering detail beyond what the schema provides, 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 ('Search Author instances for autocomplete suggestions'), which distinguishes it from autocomplete_article/autocomplete_mcptoken by resource name. It does not explicitly call out the sibling distinction, but the resource qualifier 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?

Gives a clear usage context: 'Useful for populating FK/M2M field widgets,' which tells the agent this is a suggestion-lookup helper rather than a general search. It offers no exclusions or named alternatives for when this is the wrong choice, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only lookup but never states read-only semantics, matching behavior (prefix vs. substring), ranking/ordering of suggestions, or what happens when term is omitted.

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 the purpose front-loaded and the use case second. Nothing is redundant or padded.

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 two-parameter read-only autocomplete with full schema coverage and no output schema, purpose and use case are adequately covered. Only the behavioral details (matching, ordering, empty-term behavior) are missing, which is a minor gap here.

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 term and limit are already documented in the schema. The description adds no syntax or format detail beyond that, making the baseline 3 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+resource ('Search MCP Token instances') and names the outcome ('autocomplete suggestions'), which clearly separates it from list_mcptoken/get_mcptoken. It does not explicitly name those siblings, so it falls short of a 5.

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 a concrete use context: 'useful for populating FK/M2M field widgets.' That tells the agent when this tool is the right pick, but offers no exclusions or comparison against list_mcptoken or the sibling autocomplete_* 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the operation-dependent shape of `items`, but says nothing about atomicity, partial-failure behavior, whether 'delete' is permanent, permission requirements, or batch size 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?

Front-loads the capability and then breaks the operation-dependent input format into three compact lines, each of which earns its place. Slightly telegraphic phrasing, but no filler.

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

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

For a batch mutation tool with no annotations and no output schema, key facts are missing: whether operations are atomic or partially applied, what happens on mixed success, what identifiers come back, and whether deletes are recoverable.

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, and the description genuinely exceeds it: it spells out the conditional shape of `items` for each operation (data objects, {id, data} pairs, or IDs), which the schema only gestures at with 'format depends on operation'.

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?

Names a specific resource (Article) and a specific capability (bulk create/update/delete of multiple items), plus enumerates the three supported operations. The word 'bulk' plus 'multiple items' implicitly separates it from the single-item siblings create_article/update_article/delete_article, though it never names them.

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

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

Usage is implied by 'bulk' and 'multiple items' — an agent can infer this is for batch work rather than single-record edits. However, it gives no explicit when-to-use/when-not guidance and never points at the single-item siblings as the alternative for one record.

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?

No annotations are provided, so the description carries the full burden. It discloses what each operation does and the shape of the input, but never warns that 'delete' is destructive/irreversible, whether bulk operations are atomic or partially applied on failure, or what permissions/rate limits apply.

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?

Short, front-loaded, and organized as a header sentence followed by three operation-specific lines. Efficient with little waste, though the per-operation formatting could be slightly tighter.

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 annotations and no output schema, the definition covers inputs well but omits key behavioral context: error/partial-failure handling, result format, and whether deletes are recoverable. Adequate but with clear gaps for a bulk write tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes beyond it: the schema only says items format 'depends on operation', while the description spells out the exact payload per operation (data objects / {id, data} / IDs). That is genuine added meaning over the structured field.

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 (bulk operations on Author) and enumerates the three supported operations, so the agent knows exactly what it does. It does not explicitly name the singular siblings (create_author, update_author, delete_author) it competes with, but the 'bulk' framing strongly implies the distinction.

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

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

Usage context is implied: this is the multi-item counterpart to the singular create/update/delete_author tools. However, there is no explicit 'use this instead of create_author when processing many records' guidance, and no exclusions or prerequisites (e.g., max batch size, auth needs) 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?

With no annotations, the description carries the full behavioral burden, yet it discloses nothing about the destructive nature of 'delete', permission requirements, atomicity, or partial-failure behavior for a multi-item operation. It only adds input-format detail, so the safety-relevant traits remain invisible.

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?

Purpose is front-loaded in the first sentence, followed by a compact, necessary per-operation breakdown. No filler, though the three format lines are slightly dense.

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 bulk mutation tool with no annotations and no output schema, the input formats are covered but return values, error handling and partial-failure semantics are absent. Adequate but with clear gaps for this complexity level.

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% (baseline 3), but the schema's items description is vague ('format depends on operation'), and the description supplies the exact shape per operation — data objects for create, {id, data} for update, IDs for delete — adding real 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 (bulk create/update/delete) and the resource (MCP Token items), and the 'multiple items' framing cleanly distinguishes it from single-item siblings like create_mcptoken, update_mcptoken and delete_mcptoken without needing the 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 explains the input shape for each operation, which implicitly guides operation selection, but never states when to prefer bulk over the single-item siblings or any prerequisites. 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?

With no annotations, the description carries the full burden and does meaningful work: it discloses format conventions (ISO 8601, FK by ID, M2M by ID list) and the rejection semantics for unknown/read-only/non-editable fields. Gaps remain around authentication requirements and side effects, so it is strong but not complete.

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

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

Front-loaded with the purpose, followed by format rules and then the field list. Every section earns its place and there is no filler; the field enumeration is dense but informative.

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?

Input-side behavior is well covered, but with no annotations and no output schema, nothing anywhere states what a successful call returns or what permissions are needed. For a mutation tool with nested objects and inlines, those omissions leave the picture incomplete.

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%, but the top-level 'data' param is a free-form object that the schema labels only as 'The data for the new Article'. The description adds real value by enumerating the fields with types and required markers, plus format rules that the schema does not express.

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 first sentence states a specific verb and resource ('Create a new Article') and adds scope ('optionally with inline rows'). It does not, however, differentiate itself from close siblings like update_article, which the agent must distinguish by name alone.

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 explicit when-to-use guidance, no prerequisites, and no named alternatives (e.g. update_article for existing records). Format guidance for dates and foreign keys is present, but that is parameter semantics rather than usage 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?

With no annotations provided, the description carries the full burden. It does add genuine behavioral detail: unknown/read-only/non-editable fields are 'rejected with an error, never ignored'. But for a mutation tool it omits what happens on success (returned object/nested structure), permission requirements, and how FK/m2m side effects are applied.

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

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

The purpose is front-loaded and the format rules follow logically from general to specific. The field enumeration is long but each entry carries distinct information; only slight redundancy exists between the inline-rows mention and the schema's inline description.

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 create tool with no output schema, the description adequately covers data shape, field formats, required fields, inline all-or-nothing semantics, and rejection behavior. It falls short only on success response shape and permission/authentication expectations.

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, but the description substantially exceeds that by enumerating all six fields with types and required markers, and by specifying ISO 8601 formats for date/datetime and ID-based conventions for FK and m2m fields. These are semantics the schema's bare 'data' object does not supply, though some fields (e.g. articles) lack clarity on whether they are writable.

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 opening sentence states a specific verb+resource combination ('Create a new Author'), which is unambiguously distinct from the surrounding CRUD siblings (get_author, update_author, delete_author, list_author). An agent can select this without opening the 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 phrase 'optionally with inline rows' implies the create-with-nested-records use case, and the field-validation sentence tells the agent what input is accepted. However, there is no explicit when-to-use guidance, no direction to update_author for modifications, and no mention of prerequisites such as authentication or permissions.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses the atomicity guarantee ('any inline error rejects the whole call and nothing is saved') and the rejection behavior for non-editable fields ('rejected with an error, never ignored'). It falls short of stating auth requirements or the response format, but the mutation semantics are notably well covered.

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

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

Front-loaded with the core action, then the input-format contract, then a structured field list. The field enumeration is dense but earns its place by documenting the otherwise opaque nested 'data' payload.

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

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

For a 2-param, nested, no-annotation, no-output-schema create tool, the description covers fields, formats, and error/atomicity semantics adequately. Gaps are the response shape and permission requirements, which are minor given no output schema exists to describe.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds substantial value beyond the schema's bare 'data' object: it enumerates each field with its type, marks name and user as required, and defines encoding rules for datetime (ISO 8601 string), foreign keys (ID), and many-to-many (list of IDs). This meaningfully explains what must be packed into the opaque 'data' object.

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 new MCP Token', with the additional scope of optionally creating inline rows. It is clearly distinguishable from the sibling update/get/list/delete_mcptoken tools by the 'Create' verb, though it does not explicitly contrast itself with update_mcptoken or bulk_mcptoken.

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 create verb and the 'optionally with inline rows' phrasing, which hints that inlines are the mechanism for nested creation. However, there is no explicit guidance on when to prefer this over update_mcptoken, bulk_mcptoken, or how to know inlines are needed.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Delete' implies a mutation, but nothing is said about irreversibility, required permissions, cascading effects on related records, or whether the article can be recovered — all of which matter for a destructive tool.

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 short, front-loaded sentence with no filler or repetition of the schema. It is terse to the point of under-specification, but nothing in it 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 destructive mutation with no annotations and no output schema, the description says far too little: no confirmation of permanence, no recovery path, no indication of what happens to dependent records. An agent could invoke it correctly by schema alone but lacks the context to judge whether it should.

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 exists and schema description coverage is 100%, so the schema already documents 'id' fully. The description's 'by ID' adds nothing beyond the schema, which is the expected baseline for a single well-documented 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 and resource ('Delete a Article by ID') so an agent immediately knows the operation and its key. It does not differentiate from siblings such as delete_author or delete_mcptoken beyond the resource noun, but the resource name alone is sufficient to disambiguate in this 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?

No guidance on when to use this tool versus get_article/update_article, no preconditions, and no warning that the deletion is permanent. The agent gets no routing or caution information at all.

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?

No annotations are provided, so the description carries the full disclosure burden for a destructive, irreversible operation. It says nothing about permanence, required permissions, cascading effects on related records, or what happens if the ID does not exist. The only behavioral signal is the word 'Delete' itself.

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 short, front-loaded sentence with no wasted words. Only minor grammatical awkwardness ('a Author') keeps it from being fully polished.

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 trivial one-parameter tool with no output schema and no annotations, the description is minimally adequate. It omits any note on irreversibility or failure behavior, which for a delete operation would be genuinely useful context.

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

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

The single parameter has 100% schema description coverage ('The ID of the Author to delete'), so the schema does the heavy lifting. The description adds no format, type, or example detail beyond what the schema already states, making the baseline 3 appropriate.

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

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

The description names a specific verb (Delete) and resource (Author) plus the lookup key (ID), so the agent knows exactly what the tool does. It does not distinguish itself from siblings like update_author or delete_article, but the verb+resource pairing is unambiguous within the author 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?

There is no guidance on when to use this versus update_author or delete_article, no prerequisites, and no exclusions. The agent must infer usage entirely from the tool 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?

With no annotations, the description carries the full behavioral burden. It says nothing about irreversibility, permissions/scopes required, cascade effects, or whether the token can be recovered, which are critical for a destructive operation. 'By ID' is the only added detail.

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

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

A single short sentence with the action and identifier front-loaded and zero wasted words. It is efficiently structured, though the brevity reflects missing content rather than tight editing.

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 tool with no annotations and no output schema, the description should at minimum disclose irreversibility and expected permissions. It omits all of this, leaving the agent without the context needed to invoke a delete safely.

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% with a single well-documented 'id' parameter, so the schema does the heavy lifting. The description's 'by ID' merely restates what the schema already declares, adding no syntax or format guidance. 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 'Delete' and resource 'MCP Token', and the verb alone differentiates it from siblings like get_mcptoken, create_mcptoken, and update_mcptoken. It stops short of explicitly naming those alternatives, but the action 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?

No guidance on when to use this versus list_mcptoken or get_mcptoken, and no mention that deletion is likely irreversible. The agent gets no context on prerequisites or 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?

No annotations are provided, so the description carries the full disclosure burden. It does name the categories of information returned (field definitions, relationships, admin configuration), which is useful, but it says nothing about read-only safety, permissions required, or the shape/format of the response. Adequate but thin for an unannotated tool.

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 verb, resource, and payload contents all appear before any trailing clause.

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

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

With no output schema and no annotations, the description is relied upon to convey return content, and it summarizes the three main buckets of metadata. It stops short of stating the response structure or any rate/permission constraints, but for a zero-parameter introspection call it is close to sufficient.

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 there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies the target model is fixed (Article) rather than parameterized.

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 ('Get detailed metadata') plus a named resource (the Article model) and an enumeration of what the metadata covers (field definitions, relationships, admin configuration). It is distinguishable from get_article/list_article because it describes the model itself rather than records, though it never explicitly contrasts with the sibling describe_* tools.

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 when-to-use statement, no prerequisites, and no mention of alternatives such as find_models or the record-level get_article. The agent must infer from the name that this is a schema-introspection call to run before constructing Article queries or mutations.

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

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

With no annotations, the description carries the full behavioral burden. 'Get' implies a non-mutating read and it does disclose the content categories returned, but it says nothing about permissions, whether this reflects live vs cached schema, or cost/latency. Adequate but thin for an annotation-free tool.

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 resource and returned content come first. It is efficient, though it could have spent one more clause routing the agent away from the get_/list_ siblings.

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?

Complexity is low (no params, no output schema), and the description does state what comes back (fields, relationships, admin config), so an agent knows the shape of the response. The only meaningful gap is the absence of sibling differentiation against get_author/list_author.

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 for the description to clarify beyond what the empty schema already communicates.

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 ('metadata about the Author model') and enumerates the payload (field definitions, relationships, admin configuration). It is clear on its own, but it never distinguishes itself from sibling metadata tools such as describe_article/describe_mcptoken or from the data-fetching get_author/list_author.

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 only implied: an agent can infer this is for schema/introspection rather than reading records, but there is no explicit when-to-use, when-not-to-use, or reference to alternatives like get_author. No prerequisites or conditions 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?

No annotations exist, so the description carries the burden. 'Get ... metadata' implies a safe, read-only introspection call, and the description usefully enumerates what is returned (field definitions, relationships, admin configuration). It does not state whether any auth/permission level is required or whether the output is static or tenant-specific.

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 that states the verb, resource, and the three categories of content returned. 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?

With no output schema and no annotations, the description is the sole source of information, and it adequately sketches the return contents for a zero-parameter introspection tool. It could add a note on output format or stability, but 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter claims are made or needed.

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

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

The description names a specific verb (Get) and resource (the MCP Token model) plus the exact scope of metadata returned: field definitions, relationships, and admin configuration. It is clearly distinguishable from sibling resource tools like describe_author/describe_article, though it never explicitly contrasts itself with get_mcptoken or list_mcptoken, which sound adjacent.

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 only implied: the tool is for inspecting the model's shape, which an agent would infer is a prerequisite step before building queries. There is no explicit statement of when to prefer this over get_mcptoken/list_mcptoken or any noted 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?

No annotations provided, so the description carries full burden. It says nothing about whether this is read-only, whether the list is scoped or cached, or how results are returned. Only the basic discovery behavior is conveyed.

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, no waste, purpose front-loaded in the first sentence and usage in the 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?

No output schema and no annotations, so the description should carry more weight. For a discovery tool, it should describe the return shape (e.g., model names, available tools) and any required auth. What's there is minimal but adequate for the simple single-optional-param design.

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

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

Schema coverage is 100%, so the schema fully documents the optional 'query' parameter (case-insensitive name filter). Description adds nothing beyond the schema; 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 clear verb (discover) and resource (Django models registered with MCP). Distinguishes from siblings, which are all model-specific CRUD operations (list_author, get_article, etc.) rather than a discovery/meta tool. Not a 5 because it doesn't explicitly name sibling alternatives.

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?

Explicit use case given: 'Use this to find which models have tools available.' That is a clear trigger for when to call it. No exclusions or when-not-to-use guidance, which keeps it from a 5.

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

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

No annotations are provided, so the description carries the full disclosure burden, yet it only restates that inline/related data are optional. It says nothing about not-found behavior, permission requirements, or what the response contains; the admin caveat for inlines lives in the schema, not the description.

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 tight sentence with the core purpose front-loaded ('Get a specific Article by ID') and the optional modifiers trailing. No filler, though it is arguably too terse to be maximally 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 simple read-by-ID tool with a fully documented schema and no output schema, the description is minimally adequate. It leaves gaps a caller may care about: error/not-found semantics, permission notes, and how the inline/related expansion affects payload size.

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 three parameters (id, include_inlines, include_related) are already documented with types and defaults. The description's 'optional inline and related data' phrase maps to those flags but adds no syntax, format, or cost/performance context 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?

States a specific verb (Get) plus resource (Article) and the keying mechanism (by ID), which clearly separates it from list_article and bulk_article. It stops short of distinguishing itself from neighbors like describe_article or related_article, whose scope overlaps with the 'inline and related data' clause.

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: fetch one article when you already have its ID. There is no explicit when-to-use, no exclusion of alternatives (describe_article, related_article, find_models), and no statement that the ID must come from list_article or search first.

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

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

With no annotations, the description carries the full behavioral burden, yet it discloses almost nothing beyond the surface action. It does not mention not-found/error behavior, that include_inlines requires admin privileges (that constraint lives only in the schema), permission requirements, or performance implications of expanding related 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 efficient sentence, front-loaded with the core action and ID, then qualifying the optional expansions. Nothing is wasted, though it is arguably too terse to be richly informative.

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 single-record getter with no output schema, the description covers the essentials an agent needs to invoke it. It is incomplete on error/not-found semantics and the admin privilege requirement for inlines, which are material to calling it correctly.

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

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

Schema description coverage is 100%, so all three parameters are already documented, and the baseline is 3. The phrase 'optional inline and related data' loosely maps to include_inlines/include_related but adds no format or behavioral detail beyond what the schema says (e.g., the admin requirement is only in 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?

States a specific verb (Get) and resource (Author) with the identifying key (by ID), which cleanly separates it from list_author, create_author, or related_author. It does not explicitly name or contrast with any sibling, so it falls short of a 5.

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?

'by ID' implies you use it when you already have a specific author identifier, unlike list_author or autocomplete_author. However, there is no explicit when-to-use guidance, no mention of when to prefer related_author/describe_author, and no prerequisites 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?

No annotations are provided, so the description carries the full burden, yet it adds almost nothing beyond the schema: no mention of return shape, not-found behavior, or the admin permission implied by include_inlines. It only echoes the two boolean flags already documented 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?

A single front-loaded sentence with no filler; the resource and the key optional behavior appear first. It is tight, though it is arguably too minimal for a tool with zero annotations.

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 and no annotations, the description should say more about what a successful fetch returns and what a missing ID yields. It covers the surface contract ('get by ID' plus optional expansions) but leaves the agent to discover response behavior empirically.

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 three parameters are already self-documenting, which sets the baseline at 3. The phrase 'optional inline and related data' loosely maps to include_inlines/include_related but adds no format or behavioral detail 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?

States a specific verb and resource ('Get a specific MCP Token by ID'), which cleanly separates it from list_mcptoken and the mutation siblings. It never names an alternative explicitly, but the by-ID framing 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?

Usage is implied by 'by ID' versus the list sibling, but there is no explicit when-to-use, when-not, or prerequisite statement. An agent must infer that this is the single-record fetch and that related_mcptoken/history_mcptoken cover the other read needs.

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?

No annotations are provided, so the description must carry the behavioral burden. It usefully discloses the return type (LogEntry records) and the content shape ('who made what changes and when'), but says nothing about pagination, ordering, or permission requirements for viewing history.

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. The second sentence slightly restates the first by re-expressing 'change history' as 'who made what changes and when', but it does add clarity about the record contents.

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 two-parameter read tool with no output schema, the description conveys enough: what it returns and roughly what those entries contain. It is largely complete, with only ordering/pagination behavior left unspecified.

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 'id' and 'limit' are already documented in the schema. The description adds no syntax or format detail beyond that, 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 (Get), resource (change history / LogEntry records) and target (Article instance), and even names the underlying record type, which is more than a restatement of the name. It does not explicitly differentiate itself from siblings like get_article or related_article, relying on the tool name alone to do that.

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 name and purpose but there is no explicit when-to-use guidance or named alternative. An agent must infer that this retrieves audit history rather than the current record, with no exclusion or routing information provided.

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

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

With no annotations, the description carries the full burden. It usefully discloses the return payload ('LogEntry records') and its semantic content ('who made what changes and when'), but says nothing about ordering, pagination beyond the schema's limit, retention, or read-only safety, leaving real gaps for an audit-style tool.

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 with the core action front-loaded and no filler; the second sentence adds concrete value about what the history contains rather than restating the first.

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 two-parameter read tool with a fully documented schema, the definition is nearly sufficient: it names the resource, the ID requirement is in the schema, and it describes the return content even without an output schema. Minor gaps remain around ordering and result limits.

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 (id, limit) are already fully documented in the schema. The description adds no format or constraint detail beyond it, 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 (get change history for an Author instance) and clarifies the record type (LogEntry). The resource noun 'Author' implicitly distinguishes it from history_article and history_mcptoken siblings, though it never names them 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 use this versus related tools (e.g., get_author, related_author, history_article) and no prerequisites or exclusions stated. Usage is only inferable from the tool 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?

No annotations are supplied, so the description carries the full burden. It does disclose the return content (LogEntry records with actor, change, timestamp) and 'Get' implies a read, but says nothing about ordering, pagination beyond the schema's limit, or required 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?

Two short sentences, front-loaded with the operation and resource, and every clause earns its place by naming the record type and the fields surfaced.

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

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

For a simple read-only lookup with a 100%-covered two-parameter schema and no output schema, the description covers what the tool does and what it returns. Ordering and pagination behavior are the only minor 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 coverage is 100% with only two parameters, both fully described in the schema (id target, limit with default 50). The description adds no parameter 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: 'Get the change history (LogEntry records) for a MCP Token instance', with the second sentence clarifying the content is who/what/when. This cleanly separates it from get_mcptoken (current state) via the resource noun, though it never explicitly contrasts with the sibling set.

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 only implied: an audit/history lookup is self-evident from 'change history' and 'who made what changes and when', but there is no statement of when to prefer this over get_mcptoken or related_mcptoken, nor any 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that invalid filters return an error and that relation-path/custom filters require admin declaration, which is real constraint information beyond the schema. However, it omits any statement about read-only safety, permissions, or side effects for a list operation.

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

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

Purpose is front-loaded in sentence one, followed by clearly delimited blocks for lookups and fields. The dense lookup enumeration is long but each item is functional rather than filler, so the length is largely earned.

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

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

For a complex filtered-list tool this covers filtering, searching, ordering, and pagination constraints thoroughly. The gap is the absence of any output-shape description (no output schema exists), so an agent cannot anticipate the response structure or whether a total count is returned.

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 already 100%, so the baseline is 3, but the description substantially enriches it: it enumerates the full lookup vocabulary (exact, iexact, contains, gt/gte/lt/lte, in, range, isnull, date parts) and lists every available field with type and required status. That materially exceeds what the schema's generic parameter descriptions provide for filters and order_by.

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 opening sentence states a specific verb (List) plus resource (Article instances) and enumerates the four supported capabilities (filtering, searching, ordering, pagination). This cleanly separates it from siblings like get_article (single fetch), create_article, and describe_article (schema/config inspection), and it even cross-references describe_article for filter discovery.

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

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

The description gives clear operational context: relation paths and custom filters only work when declared, and describe_article should be consulted to discover admin_config.filters. That is genuine how/when guidance, but it never explicitly contrasts this tool with alternatives like find_models or autocomplete_article for the same 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?

With no annotations, the description carries the full disclosure burden. It usefully warns that invalid filters return an error and that undeclared relation paths silently fail to work, which is real behavioral value. However, it says nothing about permissions/auth, result-set caps, default return shape, or that this is a non-mutating read — gaps that annotations would normally cover.

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

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

Front-loads the core purpose in the first sentence, then uses a compact lookup list and a bulleted field inventory. It is long, but virtually every token carries syntax the agent needs; the only mild redundancy is re-listing field types the schema could imply.

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 5-parameter, nested-object, no-annotation, no-output-schema list tool, the description covers the hard part (filter/lookup syntax and discovery via describe_author) thoroughly. It leaves return shape and pagination behavior implicit, which is the main remaining gap given there is no output 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 coverage is 100%, so the baseline is 3, but the description goes well beyond the schema by enumerating the complete lookup vocabulary (iexact, contains, gt/gte, in, range, isnull, date parts) and the relation-path rule for the `filters` object. It adds little for limit/offset/search/order_by, which the schema already documents.

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 Author instances') plus the four capabilities it supports (filtering, searching, ordering, pagination), and enumerates the underlying model fields. An agent can immediately distinguish this from get_author, create_author, and delete_author 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?

Gives concrete routing guidance for the tricky part of the tool: relation paths and custom filters only work when declared in list_filter/date_hierarchy, and the agent is told to consult describe_author's admin_config.filters to discover them. It does not explicitly state when to prefer this over get_author or history_author, so it falls short of explicit when/when-not/alternatives.

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

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

With no annotations, the description carries the behavioral burden; it does disclose useful traits such as invalid filters returning an error and relation paths only working when declared in list_filter/date_hierarchy. It omits the read-only safety profile, any auth/permission requirements, and does not describe pagination or return-format behavior beyond the field list.

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

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

The purpose is front-loaded in a single clean sentence, followed by structured reference material. The lookup-suffix enumeration is dense but earns its place given the filter complexity; a slight trim could improve it but it is well-organized.

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 5-parameter list tool with no output schema and no annotations, the description covers filtering, searching, ordering, pagination, the full available field list, and error semantics. It is complete enough for correct invocation, with only the safety/auth profile left 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 100%, so the baseline is 3, but the description genuinely adds meaning beyond the schema: the full set of lookup suffixes, date-field sub-lookups, chained comparisons, and relation-path filtering. This enriches how the filters object is actually used, warranting above 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?

The first sentence states a specific verb (List) and resource (MCP Token instances) plus the four capabilities (filtering, searching, ordering, pagination). It is clearly distinguishable from get_mcptoken/describe_mcptoken, and it even points to describe_mcptoken as the filter-declaration reference, though it does not explicitly contrast itself with the other list-like 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?

It explains how filtering works and that relation paths/custom filters only function when the admin declares them, plus that invalid filters error out. However it never states when to prefer this tool over search/autocomplete siblings or when filters vs the search parameter should be used, leaving usage 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?

No annotations are provided, so the description carries the full burden. It implies a read via 'Fetch' but never states read-only safety, permission requirements, error behavior for invalid relation names, or pagination semantics despite limit/offset existing.

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 zero waste, purpose front-loaded ahead of the discovery hint. Every sentence earns its place.

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

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

Params are fully schema-documented and there is no output schema, but with no annotations the description still leaves the return shape and pagination behavior unexplained for a relation-fetch tool. It is minimally adequate rather than complete.

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

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

Schema description coverage is 100%, so the schema already documents id, relation, limit, and offset, establishing a baseline of 3. The description adds only the describe_article discovery hint for the relation parameter and no syntax or format detail 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?

States a specific verb (Fetch) and resource (related objects for an Article instance), which is clearer than a tautology and scopes it to Article. It is distinguishable from get_article/list_article/history_article, though it relies on the name pattern rather than prose to differentiate from siblings like related_author.

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

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

Gives an explicit prerequisite: use describe_article first to discover valid relation names, which is real actionable guidance for calling this tool. It lacks any when-not-to-use or alternative framing (e.g., vs get_article for a direct fetch), keeping it short of a 5.

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

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

No annotations exist, so the description carries the full behavioral burden. 'Fetch' implies a non-destructive read and the describe_author pointer discloses the relation-discovery workflow, but nothing is said about error behavior for invalid relations, permissions, or result shape.

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, front-loaded sentences with no filler; the core action comes first and the workflow hint second. 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, so the description ideally would hint at what related objects look like, but it only says 'related objects' generically. Pagination is covered by limit/offset params and relation discovery is routed, leaving an adequate but incomplete picture.

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%, including a usage example for 'relation', so the schema does the heavy lifting. The description adds no parameter-level detail beyond what the schema already documents, which is the correct baseline of 3.

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

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

States a specific verb+resource: 'Fetch related objects for a Author instance.' The resource name (author) implicitly separates it from related_article and related_mcptoken, and it explicitly contrasts with describe_author. Clear but not maximally 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?

Provides concrete prerequisite routing: 'Use describe_author to discover available relations,' which tells the agent how to obtain a valid relation value. No explicit when-not-to-use guidance, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Fetch' implies a read, but it says nothing about pagination behavior, permissions needed, or what a related-object result looks like for a relation that doesn't exist.

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 is front-loaded and the prerequisite follows immediately.

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 4-parameter traversal tool with no output schema and no annotations, the description covers the relation-discovery step but omits how results are shaped and how limit/offset behave across relations.

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 baseline is 3, and the description adds genuine value by explaining that valid 'relation' values must be discovered via describe_mcptoken rather than guessed.

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: 'Fetch related objects for a MCP Token instance.' An agent can tell this apart from get_mcptoken or list_mcptoken, though the exact boundary versus list_mcptoken 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?

Gives a concrete prerequisite workflow: use describe_mcptoken first to discover valid relations. It does not state when-not to use it or compare it against list_mcptoken/related_article, so it stops short of full 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?

With no annotations, the description carries the full burden and does substantial work: it discloses partial-update semantics, error behavior for unknown/read-only/non-editable fields ('rejected with an error, never ignored'), and the all-or-nothing atomicity of inline saves. It omits auth/permission requirements, whether existing values are overwritten, and what the response contains — real but secondary gaps.

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

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

Front-loaded: purpose, then update semantics, then format rules, then the field enumeration. The field list is long but justified by the untyped `data` object. Sentences are dense and free of filler, though the format paragraph could be tightened slightly.

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

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

Given no annotations, no output schema, and a nested untyped `data` object, the description covers mutation semantics, rejection behavior, inline atomicity, and value formats — enough to call the tool correctly. The main remaining omission is the return value/payload, which no other structured field supplies.

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?

Top-level schema coverage is high, but the nested `data` object is described only as 'The fields to update,' so the description's field list with types and required markers is a genuine value add. The format conventions (ISO 8601 strings, FK as related object ID, M2M as list of IDs) are exactly the semantic detail the schema lacks. It falls short of 5 because created_at/updated_at are listed without noting they are non-editable.

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

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

States a specific verb+resource ('Update an existing Article') and immediately qualifies the semantics with 'with optional inline updates. Only the fields sent are changed.' This distinguishes it from a full-replace operation, but no sibling tool (create_article, bulk_article, update_author) is named for contrast, so the agent must infer the boundary from naming convention alone.

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?

Partial-update behavior is implied by 'Only the fields sent are changed,' which tells the agent this is a patch-style call. However, there is no explicit when-to-use guidance versus create_article, delete_article, or bulk_article, and no stated prerequisites. Usage must be inferred.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses partial-update behavior, that unknown/read-only/non-editable fields are rejected rather than ignored, and the field-type formatting rules. It still omits permission/auth requirements and any indication of the response or side effects on related records.

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

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

Front-loads the core action, then formatting rules, then the field list — a logical ordering. The enumerated field list is long but earns its place because the schema's 'data' object does not name the fields. Minor verbosity in the format examples.

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 tool with nested inline objects and no annotations or output schema, the description covers partial-update semantics, field formats, validation behavior, and inline all-or-nothing handling. The main gap is the absence of any statement about the return value or auth requirements, which with no output schema would have been helpful.

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, but the description adds real value beyond it: ISO 8601 format for date/datetime, related-object ID for foreign keys, and a list of IDs for many-to-many fields. It also enumerates the updateable Author fields, which the generic 'data' object in 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?

States a specific verb and resource ('Update an existing Author') and clarifies the partial-update semantics ('Only the fields sent are changed'), which distinguishes it from create_author/delete_author without opening a schema. It does not explicitly name a sibling alternative, so it falls just short of the top tier.

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 'existing Author' and the partial-update framing, so an agent can infer it edits rather than creates or fetches. However, there is no explicit when-to-use/when-not guidance or named alternatives (create_author, bulk_author), leaving the choice 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?

With no annotations, the description carries the burden and does a fair job: it documents input formats (ISO 8601 single string for dates, FK as related ID, M2M as a list of IDs) and a validation behavior (unknown/read-only/non-editable fields are rejected, never silently ignored). It omits auth requirements and return behavior, but the disclosed format and rejection semantics are substantive.

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?

Purpose and the format rules are front-loaded, followed by an organized field list. The field enumeration is long but justified for a loosely-typed 'data' parameter. Minimal wasted prose.

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 annotations and no output schema, the description supplies the field surface, input formats, and rejection behavior an agent needs to call it correctly. Gaps remain around return values and permissions, but nothing critical 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 coverage is 100%, so the baseline is 3, but the schema's 'data' object is only described as 'The fields to update'. The description compensates by enumerating every accepted field with its type and defining the date/FK/M2M input conventions, adding real meaning beyond the loose schema. The 'inlines' all-or-nothing rule lives in the schema rather than the description, so it is not double-counted.

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 ('Update') and resource ('an existing MCP Token'), and adds the partial-update semantic ('Only the fields sent are changed'). It doesn't name sibling alternatives like bulk_mcptoken or action_mcptoken, so it is clear but not 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?

The 'Only the fields sent are changed' and 'optional inline updates' phrasing imply this is the tool for partial edits of an existing token, but there is no explicit when-to-use vs create_mcptoken/delete_mcptoken guidance or when-not condition. Usage must be inferred.

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