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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the mutation profile is covered. The description adds no further behavioral detail – no mention of what is changed, whether existing notes are preserved, auth requirements, or error conditions – it essentially paraphrases the tool name.

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

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

The description is a single concise sentence with no redundancy or filler. It front-loads the only necessary action and is appropriately sized for the tool's simplicity.

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

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

The tool is simple (2 scalar params, output schema exists) and the description captures the core operation, so it is minimally complete. However, it does not explain how the note relates to the document's existing notes or when this should be used over update_document/get_document_notes, leaving some 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 0%, so the description must compensate. It only confirms document_id identifies the document and note is the text to append, which is marginally more than the parameter names. No constraints, formatting, or examples are provided, leaving the agent to infer note length or content rules.

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

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

The description uses a specific verb ('Append') and resource ('note to a document'), making the action immediately clear. However, it does not explicitly differentiate itself from sibling tools like get_document_notes or delete_document_note, though the verb choice helps.

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

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

The description gives no guidance on when to use this tool instead of alternatives such as update_document, get_document_notes, or delete_document_note. No prerequisites, exclusions, or alternative conditions are mentioned.

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

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

Annotations already mark this as destructive and non-idempotent, but the description adds no behavioral context such as consequences, scope of changes, or whether the operation is reversible. The open-world hint and free-form 'parameters' object suggest unknowns, but the description does not warn or clarify them.

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

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

The description is a single sentence with no filler, so it is brief and readable. However, the brevity results from under-specification rather than efficient communication, since it omits operation vocabulary and parameter semantics.

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 bulk operation with an open-world parameter object, no enum values, and zero schema description coverage, this description is severely inadequate. An agent cannot determine valid operations, expected parameter shapes, or the scope of side effects, making successful invocation mostly guesswork.

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

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

Schema description coverage is 0%, so the description needed to explain 'operation', 'ids', and 'parameters'. It provides none of that: 'operation' has no documented values, 'parameters' is an unconstrained object, and the description does not compensate for any of the schema's omissions.

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 identifies a resource ('correspondents') and a general verb ('apply a bulk operation'), but 'bulk operation' is vague and essentially restates the title. It does not say what operations are possible or how this differs from sibling bulk_edit_* tools beyond the noun in the name.

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 is given about when to use this tool versus single-resource alternatives like update_correspondent or delete_correspondent, or versus sibling bulk_edit_* tools. The intended usage must be inferred 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?

The description adds substantial behavioral detail beyond the annotations: writes happen before the OK response, search-index rebuild is queued in the background, there is an eventual-consistency window for search, and metadata operations create a bulk_update task with a task_id. This goes well beyond the boolean annotations provided.

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

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

The description is compact and front-loaded with the primary purpose, then efficiently explains the async behavior and how to trace the background task. Every sentence adds operational value with no redundancy or 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 destructive, complex bulk tool, the description covers side effects, consistency, and task tracking well; the output schema exists and the input schema enumerates operations. It is slightly incomplete in that parameter semantics are left entirely to the schema, but the agent has enough information to invoke the tool correctly in most cases.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters, but it does not explain operation values, the ids array, or the parameters object. It only generically references 'metadata operations,' leaving the agent to infer semantics from the raw schema. This is a notable gap given the large operation enum.

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

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

The description opens with 'Apply a bulk operation to a set of documents,' which clearly identifies the verb, resource, and scope. It does not explicitly differentiate from sibling bulk_edit_tags/correspondents/document_types tools, but the document resource target makes the purpose sufficiently distinct.

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 actionable usage context: it warns that a following search_documents call may miss edits for seconds to minutes, while list_documents and get_document reflect changes immediately. It also tells the agent how to track completed work via list_tasks and wait_for_task. It stops short of explicitly stating when not to use this tool versus single-document alternatives.

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

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

Annotations already mark the tool as destructive and not read-only, and the description adds no behavioral detail beyond that. It does not state what the bulk operation does to the selected document types, whether it is reversible, or what side effects might occur.

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

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

The description is short and free of fluff, but it is under-specified rather than efficiently informative. It essentially restates the tool name without adding operational detail, so it does not earn its place as a helpful definition.

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 three parameters, an unconstrained operation string, no enum guidance, and a destructive annotation, the description is too incomplete for an agent to invoke the tool correctly. The presence of an output schema covers return values, but the core operation and parameter semantics remain undefined.

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

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

Schema description coverage is 0% and the description provides no parameter guidance. The 'operation' string is unconstrained, and 'parameters' is an open object, yet the description does not clarify acceptable values or how ids map to the 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?

The description names the resource ('document types') and indicates a bulk action, but the verb 'apply' and the phrase 'bulk operation' are generic. It does not say whether the operation deletes, updates, or otherwise changes the document types, so the agent cannot tell what the tool actually accomplishes.

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 tool versus alternatives like update_document_type, delete_document_type, or the sibling bulk_edit_* tools. The agent is left to infer usage from the name and resource type.

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

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

The annotations already indicate a destructive, non-idempotent, non-read-only operation, but the description adds no behavioral context beyond that. It does not explain whether removal deletes tags or merely detaches them, whether effects are reversible, or what the bulk operation actually does to the tags.

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

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

The description is a single short sentence with no fluff, so it is easy to parse. However, it is under-specified rather than economically complete for a tool with an opaque three-field schema.

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

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

Even with annotations and an output schema present, an agent cannot reliably construct a valid request because `operation` has no documented values and the `parameters` object is unexplained. The description is too thin for a mutating bulk tool with three required 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 input schema has 0% description coverage, so the description must explain the parameters, but it only loosely ties the operation to a set of tags. It never states the accepted values for `operation`, the meaning of `ids`, or what can be placed in the `parameters` 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?

The description identifies the resource (tags) and that the tool applies a bulk operation, so it is not a tautology. However, "bulk operation" is vague and does not name the add/remove behavior that the title implies, leaving the core action underspecified.

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 about when to use this tool instead of single-tag operations like create_tag, update_tag, or delete_tag, or instead of sibling bulk_edit_* tools. No use-case context, prerequisites, or exclusions are 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?

Annotations already indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description adds no behavioral insight beyond what is structured. It does not mention uniqueness constraints, side effects of creating a correspondent, defaults for optional fields, or any failure/response behavior. There is no contradiction with annotations, but there is also no added transparency.

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

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

The text is short and free of fluff, but it does not earn its place: it restates the title and contributes no usable information. This is under-specification rather than effective conciseness.

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

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

Despite having a nested input schema and output schema, the description leaves out essential context: what fields are required versus optional, what match/matching_algorithm are for, and what a successful create does. The bare 'Create a new correspondent.' is only minimally enough to identify the operation, not to invoke it correctly.

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

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

Schema description coverage is 0%, so the description should compensate by explaining what body, name, match, is_insensitive, and matching_algorithm mean. It mentions none of the parameters. An agent cannot determine the semantics of this nested body schema from the description alone.

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

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

The description 'Create a new correspondent.' merely restates the tool name and title ('Create Correspondent') with the word 'new' added. It gives no additional semantic information about what a correspondent is, what creation entails, or how it differs from update_correspondent or other sibling create 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?

There is no guidance about when to use this tool versus update_correspondent, bulk_edit_correspondents, or other alternatives. No preconditions, exclusions, or context are provided; the only implicit signal is that 'create' contrasts with 'update'.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so no contradiction exists. The description adds valuable behavioral context beyond annotations: extra_data is conditionally required based on data_type, Paperless assigns stable option ids on creation, and invalid shapes result in a 400 error.

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

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

The description is appropriately sized and front-loaded with the core action, then uses a compact bulleted list to cover the complex conditional parameter behavior. Every sentence and bullet contributes necessary information with no fluff or repetition.

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

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

For a create operation with a nested body and data-type-dependent behavior, the description covers the essential validation rules and the error response for invalid shapes. The output schema is available to explain return values, and annotations cover idempotency and read-only hints, so nothing critical is missing.

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

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

The schema has 0% description coverage, so the description carries the burden for parameter meaning. It thoroughly explains the extra_data parameter across all data_type variants, including requiredness and exact shape for select and monetary. It does not explicitly describe name, but that parameter is self-evident and the schema marks it required.

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

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

The description states a specific verb and resource: "Create a new custom field." It clearly distinguishes this from sibling tools like update_custom_field and delete_custom_field through the "create" verb and "new" qualifier, and from other resource create tools through the resource name.

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 about when to use this tool versus alternatives, such as update_custom_field or list_custom_fields. The only usage signal is the word "Create," which implies intent but does not provide context, prerequisites, or exclusions.

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

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

The description merely restates the operation and adds no behavioral context beyond the annotations. It does not disclose uniqueness constraints, default-applied behavior, side effects, or what happens on duplicate names. There is no contradiction with the annotations, but the description contributes little.

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

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

The description is one short, front-loaded sentence with no redundant wording. It is concise, though this conciseness comes at the cost of under-specification that is penalized in other dimensions.

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 a nested body and meaningful optional fields, this description is too thin. It does not explain the purpose of matching-related parameters, defaults, or how this tool relates to document type management, despite having an 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 description coverage is 0%, and the description does not compensate by explaining the `body` object or any of its fields (`name`, `match`, `is_insensitive`, `matching_algorithm`). An agent gets no added meaning from the description about how to configure a document type.

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

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

The description states a clear verb and resource: 'Create a new document type.' It is unambiguous about the operation and distinguishes it from update/delete/list siblings, though it does not explicitly name any alternative.

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 is provided about when to create a new document type versus updating or reusing an existing one. There are no prerequisites, exclusions, or alternative tool mentions, leaving usage entirely to the agent's inference.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description adds no extra behavioral context. It does not disclose side effects, permission requirements, or error conditions (e.g., duplicate names). The description is silent on anything beyond the act of creation.

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

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

The description is extremely concise at five words, which is efficient, but it is under-specified. It lacks the substance needed to be useful, so while there is no verbosity, the brevity works against its effectiveness. It is not well-structured for comprehension beyond stating the obvious.

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

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

With a complex nested input schema and an output schema present, the description is highly incomplete. It fails to explain how to construct the request, what the response contains, or any constraints. For a tool with such a detailed schema, this level of description is inadequate.

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 input schema has a nested body object with multiple optional fields (color, match, is_inbox_tag, etc.), and schema description coverage is 0%. The description does not explain the body parameter, its structure, or the meaning of any of these fields, leaving the agent without semantic guidance beyond raw schema types.

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 the verb 'create' and resource 'tag', which clearly distinguishes it from sibling operations like list, get, update, and delete. It is specific enough for an agent to know the tool's function, though it does not elaborate on scope or nuances.

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 is provided on when to use this tool versus alternatives. There is no mention of prerequisites, such as needing an existing tag or when to prefer create_tag over update_tag or bulk_edit_tags. The description is purely functional with no contextual direction.

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

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

Annotations already provide destructiveHint, idempotentHint, and readOnlyHint false, but the description adds no extra behavioral context such as whether the deletion cascades to associated documents or is reversible. There is no annotation contradiction.

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

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

The description is a single short sentence with no wasted words, but it is under-specified rather than efficiently informative. It is concise in length but does not use the available space to clarify selection or side effects.

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

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

This is a simple one-parameter delete and annotations plus output schema fill in some context. However, the definition omits whether deletion has cascading effects, how it differs from bulk deletion, and any relevant prerequisites, leaving notable gaps for an agent deciding whether to invoke it.

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

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

Schema description coverage is 0%, and the description never references correspondent_id or explains that the parameter identifies the specific correspondent to delete. The property name is suggestive, but the text adds no semantic value 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 'Delete a correspondent.' restates the tool name and title almost word-for-word, adding no scope or differentiation. It does not mention that this targets a single correspondent by ID or contrast with bulk_edit_correspondents.

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 tool versus alternatives such as bulk_edit_correspondents, nor any mention of prerequisites, side effects, or expected context for deletion.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known; however, the description itself adds zero behavioral context beyond that, such as whether deletion is permanent, whether it cascades to documents using the field, or whether it can be undone. With no added disclosure, the description falls below the bar set by the HIGH calibration example (which at least added scoping context).

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

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

The description is maximally efficient: a single short sentence with no wasted words. For a one-parameter delete operation, this brevity is acceptable, though it borders on under-specification rather than earning its place with added value.

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

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

The tool is simple and has an output schema, so return values need no explanation, but the description still omits the meaning of field_id and the consequences of a destructive delete. For an irreversible operation on a metadata entity, agents would need at least a hint about affected documents or how to look up the field.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining field_id, but it never mentions the parameter. 'field_id' is a reasonably self-explanatory integer identifier, but the description does nothing to clarify how to find or supply it, so it fails to compensate for the coverage gap.

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

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

The description 'Delete a custom field.' names a specific verb and resource, and the resource type 'custom field' is enough to distinguish it from sibling delete tools like delete_document, delete_tag, and delete_correspondent. It is clear but adds no detail beyond the name/title, so it does not fully earn 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?

There is no guidance about when to use this tool versus alternatives, no mention of how to obtain a field_id (e.g., via list_custom_fields or get_custom_field), and no exclusions. The single-sentence description leaves all usage context to the agent's 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?

The description adds no behavioral context beyond the annotations: it doesn't state that deletion is permanent/irreversible, what associated data (notes, history, metadata) is affected, or any authorization requirements. The destructiveHint and idempotentHint annotations already carry the safety information, and the description contributes nothing extra.

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

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

The description is short, but brevity here is under-specification rather than conciseness: the single sentence merely repeats the verb and object already present in the tool name and title. It doesn't earn its place by adding any new 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 destructive operation, the description omits key context such as permanence, cascading effects, and when deletion is appropriate. Although annotations and the presence of an output schema fill in some details, the description alone leaves an agent under-informed about the consequences and preconditions of calling this 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?

With schema description coverage at 0%, the description was responsible for explaining document_id, but it doesn't mention the parameter at all. The schema only shows an integer ID; no guidance is given on how to obtain it, what values are valid, or what the ID refers to, so the description adds no semantic value 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 'Delete a document.' merely restates the tool name and title without adding specificity. It does not mention 'permanently' from the title, and it doesn't distinguish this deletion from sibling actions like delete_document_type or delete_document_note except through the bare resource noun.

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 tool versus alternatives such as update_document, bulk_edit_documents, or the sibling deletion tools. The description gives no conditions, prerequisites, or warnings, leaving the agent to guess the appropriate context.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering the safety profile. The description adds no extra behavioral context beyond 'remove', which is consistent with the annotations. It does not disclose side effects like permanence or cascading effects, but given the annotations, the minimal statement is adequate.

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 that gets straight to the point with zero filler. The core action is front-loaded and there is no redundant phrasing.

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 deletion tool, the description is minimal but workable. However, it lacks usage context and parameter elaboration, and does not mention expected behavior when the note does not exist or whether deletion is permanent. The output schema (though not shown) and annotations cover some gaps, but the description alone leaves an agent guessing about edge cases.

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

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

Schema description coverage is 0%, so the description must compensate. It only says 'a note from a document' without elaborating on the two parameters (document_id, note_id) or their relationships. The parameter names are self-explanatory, but the description adds no semantic value beyond what the schema already conveys.

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 'Remove a note from a document' clearly identifies the action (remove) and the resource (a note within a document). It is specific enough to distinguish from sibling tools like delete_document (whole document) and delete_document_type (type), though it does not explicitly name them.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or situations where a different delete operation would be more appropriate. An agent must infer usage from the name alone.

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

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

The annotations already convey destructive, non-read-only, and idempotent behavior, and the description simply restates 'Delete' without adding any behavioral context. It does not disclose downstream effects on documents, permanence, or authorization requirements, though it does not contradict the annotations.

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

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

The description is a single focused sentence with no filler, and the action is front-loaded. It is appropriately concise for a one-parameter CRUD operation, though it errs on the side of being too sparse to be genuinely helpful.

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 operation, the description omits the most important operational context: what deletion means for documents assigned to the type, whether the type can be deleted while in use, and what the response indicates. The annotations and schema cover mechanics but not the impact of the deletion.

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 document_type_id is self-explanatory and required, but with 0% schema description coverage the description was expected to clarify its role and constraints. It says only 'Delete a document type' and provides no additional meaning about how the ID is used or validated.

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

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

The description uses a specific verb-resource pair ('Delete' + 'document type') that clearly states the operation and target. It is readily distinguished from sibling tools such as update_document_type, get_document_type, and create_document_type, even without reading their schemas.

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 is provided about when to use this tool versus alternatives, nor are prerequisites or exclusions mentioned. The description does not say, for example, whether a document type must be unused before deletion or what happens to documents assigned to it.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, and the description adds no behavioral context beyond the title. It does not disclose consequences, reversibility, permissions, or possible side effects on associated documents, so the description carries no extra transparency value.

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

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

The description is extremely concise and front-loaded with zero filler. However, it carries no information beyond the title, so the terseness borders on under-specification; it is acceptable for such a simple tool but not a model of helpful structure.

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

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

For a one-parameter delete operation with annotations and an output schema present, the minimal invocation is inferable. The main gap is the lack of any statement about side effects or cascading behavior, which is relevant for a destructive tool like this.

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

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

Schema description coverage is 0%, and the description never mentions tag_id or what value should be supplied. The parameter name and integer type in the schema are somewhat self-explanatory, but the description itself adds no semantic meaning to compensate for the missing parameter documentation.

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

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

The description uses a specific verb ('Delete') and a clear resource ('tag'), which distinguishes it from sibling tools like delete_document or delete_correspondent. However, it is essentially a restatement of the title and adds no scope or qualifier, so it is clear but not exceptional.

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 is given about when to use delete_tag versus related tools such as update_tag, bulk_edit_tags, or delete_document_type. The agent must infer usage solely from the name and siblings, with no exclusions or alternative conditions 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?

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds the basic 'by ID' scope but does not disclose behavior like not-found handling or authentication requirements, though the annotations lower the bar.

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

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

A single sentence with no filler, directly stating the action and resource. It is appropriately front-loaded and every word 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 idempotent read operation with one self-explanatory parameter, strong annotations, and an output schema, the description is nearly sufficient. It lacks minor context like error behavior or sibling routing, but those are not essential for a basic get-by-ID call.

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

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

Schema description coverage is 0%, but the single parameter correspondent_id and its integer type are largely self-explanatory. The description reinforces 'by ID' but adds no additional meaning such as ID format, source, or lookup semantics 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 ('Fetch'), a resource ('correspondent'), and the retrieval key ('by ID'). This clearly distinguishes it from siblings like list_correspondents and create/update/delete_correspondent.

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

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

The description gives no guidance on when to use this tool versus alternatives, such as using list_correspondents to find an ID first or when not to use it. 'By ID' only implies a prerequisite, not explicit usage criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no behavioral context beyond restating the fetch action, so it provides no extra transparency beyond what annotations already offer.

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 7-word sentence contains exactly the necessary information, front-loading the action and object. No wasted words.

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

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

For a one-parameter read tool with output schema and safety annotations, the description is largely sufficient. However, it does not explicitly state that the field must already exist or how it relates to list_custom_fields, leaving minor completeness 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?

The schema has a single integer field_id with no description (0% coverage). The description's 'by ID' clarifies that field_id is the unique identifier of the custom field, adding essential meaning the schema lacks.

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 'Fetch a custom field by ID' uses a specific verb, resource, and identifier, clearly distinguishing it from sibling CRUD tools like list_custom_fields, create_custom_field, etc.

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 explicit guidance on when to use this tool versus list_custom_fields or other alternatives. The usage is implied by the name and 'by ID', but there is no mention of when to prefer this over enumeration or other getters.

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

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

Annotations already cover safety: readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds a useful behavioral detail beyond annotations: OCR content is stripped to keep responses small. It does not go into error handling or authorization, so 3 is appropriate.

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

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

Three short sentences with no filler. The core action is front-loaded, and the following two sentences add only targeted routing details that an agent genuinely needs.

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

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

With one required integer parameter, an output schema present, and annotations covering read-only/idempotent behavior, nothing critical is missing. The content-related alternatives are explicitly named, so an agent can decide correctly without guessing.

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

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

The only parameter is document_id, an integer with no schema description (0% coverage). The phrase 'by ID' directly links the parameter to the fetch operationcars; for a single self-explanatory parameter, this is sufficient meaning beyond the raw 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 clear action and resource: 'Fetch one document by ID.' It also distinguishes the tool from content-focused siblings by noting 'OCR content is stripped' and pointing to get_document_content, so an agent can tell this apart from related get_document_* 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?

Explicitly routes alternative usage: 'Call get_document_content for a bounded preview, or use create_download_link with the content variant when available.' This tells the agent when to prefer a different tool instead of get_document.

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

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

Annotations already mark the operation read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: the 20,000-character cap, the truncation marker containing character range and full length, and the offset continuation mechanism. It also clearly states when no marker appears, leaving no surprise about response 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?

The description is compact yet information-dense: the first sentence states the core purpose, and the second paragraph explains the only non-obvious behavior. Every sentence earns its place, and the structure front-loads the most important 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 read-only content-fetching tool, the description fully covers the pagination edge case that could confuse an agent, while the output schema handles return-value details. Given the 100% schema coverage and rich annotations, nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the parameters document_id, offset, and max_chars are already well explained. The description adds a little contextual meaning by tying offset to the truncation marker, but this mostly repeats what the schema already says. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Return the OCR'd text content of a document.' This clearly distinguishes the tool from siblings like get_document, get_document_metadata, and get_document_thumbnail, which serve different purposes. No ambiguity remains about what the tool produces.

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

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

The description provides clear context by explaining that long documents require pagination and how the caller should continue reading via the returned offset. It does not name sibling alternatives or explicitly state when not to use this tool, but the scenario is obvious enough that an agent can determine appropriate use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description neither contradicts these nor adds behavioral context such as event ordering, included fields, or access requirements, so it adds no value beyond what annotations already provide.

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

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

The description is a single sentence with no filler. For a one-parameter read-only tool, this is appropriately concise and well-structured.

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

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

An output schema exists, so return value structure is not the description's responsibility. The tool is simple, well-annotated, and the description covers the basic operation. It lacks detail on what audit history includes or error behavior, but for this low-complexity tool, the coverage is adequate.

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

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

Schema description coverage is 0%, but there is only one parameter, document_id, whose name is self-explanatory. The description's 'for a document' reinforces that the ID targets a document, but it does not add format, constraints, or requiredness 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?

'Return the audit history for a document' is a clear verb+resource statement. It names the specific resource (audit history) that distinguishes it from siblings like get_document_metadata or get_document_content, though it does not elaborate on what audit history contains.

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

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

The description provides no guidance on when to choose this tool over similar get_* tools or any exclusions/alternatives. The only implied usage is the tautological 'when you need audit history,' with no context on prerequisites or edge cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only the 'technical metadata' scope; it does not describe pagination, error behavior, or result shape, but the output schema reduces the need.

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 concrete examples and no filler. Every word 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 one-parameter read-only tool with an output schema, the definition is mostly sufficient. The main gap is that the description does not situate it among the many get_document_* siblings, leaving some ambiguity about which 'details' are meant.

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

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

The schema has 0% description coverage, but there is only one parameter, document_id, whose name and integer type are self-explanatory. The description's phrase 'for a document' loosely ties the parameter to the resource, though it never explicitly states how document_id is used.

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

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

The description names a specific action ('Return technical metadata') and a concrete resource (a document), with examples 'checksums, filenames' that hint at file-level details. It is clear enough to distinguish from get_document_content or get_document_notes, though it never explicitly contrasts with 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?

No guidance is given about when to choose this tool over sibling getters such as get_document, get_document_content, or get_document_notes. The examples imply 'technical metadata', but there is no explicit condition, exclusion, or alternative.

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

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

The description adds no behavioral context beyond what annotations already provide. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's 'Return notes' does not disclose any additional traits such as ordering, pagination, or error behavior. It is safe but not transparent about anything not covered by annotations.

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

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

A single sentence that is front-loaded with the verb and resource, with no redundant words. Every word contributes to the purpose, making it appropriately concise.

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

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

For a low-complexity read operation with a single required parameter, strong safety annotations, and an output schema (present but not shown), the description is nearly complete. It lacks explicit mention of possible empty results or ordering, but these are minor given the output schema likely covers the return shape.

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

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

With 0% schema description coverage, the description must compensate for the undocumented document_id parameter. It does so minimally by indicating that notes are 'attached to a document', implying document_id identifies that document. This adds some meaning beyond a bare integer, but it does not elaborate on constraints, format, or relationships with other parameters.

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 action ('Return') on a specific resource ('notes attached to a document'), clearly distinguishing it from sibling tools like get_document, add_document_note, and delete_document_note. The purpose is unambiguous and matches the title.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention that adding or deleting notes should use add_document_note or delete_document_note, nor does it clarify when this tool is preferable over get_document or search_documents. Usage is only implied by the name.

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

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

Annotations already carry readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds classifier context but no extra behavioral detail, such as whether suggestions may be empty or that no changes are applied. It matches the annotations, so there is no contradiction.

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

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

A single eight-word sentence with no filler. It front-loads the verb and object and omits redundant restatement of the title.

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 one-parameter, read-only tool, the description plus annotations and output schema cover most of what an agent needs. The main gap is the missing explicit parameter mapping and usage context, but the required integer document_id is self-explanatory from the schema.

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

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

Schema description coverage is 0%, and the description never names document_id or explains that the required integer identifies the target document. The phrase 'for a document' is only a weak pointer, leaving parameter semantics almost entirely to the schema field name.

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

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

Description uses a specific verb-resource pair: 'Return Paperless's classifier suggestions for a document.' The title clarifies exactly which suggestions are involved (Tags, Correspondent and Type), and this operation is distinct from any other sibling tool. It stops short of explicitly contrasting itself with get_document or get_document_metadata, so not 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?

The description gives no explicit guidance on when to use this tool versus alternatives; the only hint is the word 'suggestions' versus the more concrete metadata/history tools. There are no exclusion criteria or alternative-tool routing, leaving the agent to infer usage context.

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

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

The description adds the return format 'inline image content' beyond what annotations declare (read-only, idempotent, non-destructive). However, it does not disclose details like image size, resolution, or potential error handling. Given annotations cover safety, the description provides minimal additional behavioral context.

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

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

The description is a single, efficient sentence with no wasted words. It is front-loaded with the core purpose. However, it is so brief that it omits useful context, which slightly detracts from its effectiveness.

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 no output schema and only a basic description, the return value is under-specified. 'Inline image content' is vague and does not explain format (e.g., base64, URL) or any limitations. The description does not cover potential errors or usage context, leaving the agent with incomplete information.

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 description provides no explanation of the document_id parameter. Schema description coverage is 0%, so the description should compensate, but it remains silent on parameter meaning or constraints. The only parameter is obvious from its name, but the description does not clarify its role or format.

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

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

The description clearly states the verb 'Return' and the resource 'document's thumbnail', and specifies the output as 'inline image content'. This distinguishes it from sibling tools like get_document_content (full content) or get_document_metadata (metadata). The purpose 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 is provided on when to use this tool versus alternatives such as get_document_content or get_document. The description only states what it does, not when to select it. No exclusions or alternative references are mentioned.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is already covered. The description 'Fetch a document type by ID' is consistent with those annotations but adds no behavioral context beyond what the schema already shows. It does not contradict the annotations.

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

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

One short sentence, directly front-loaded with the verb and resource. No filler, no repetition, and the structure is appropriate for the simplicity of the operation.

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 get-by-id tool with an output schema, safe annotations, and a single required parameter, the description is nearly sufficient. The main gap is the lack of any usage context or not-found/error behavior, but these are minor for such a straightforward lookup.

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

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

Schema description coverage is 0%, and the description fails to compensate. It only repeats the word 'by ID' without explaining the meaning, format, or expectations for the document_type_id parameter. The parameter name already conveys this, so the description adds no value 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 uses a specific verb ('Fetch'), identifies the exact resource ('a document type'), and scopes it 'by ID', which clearly distinguishes it from list_document_types and the mutation siblings. It is unambiguous, though it stops short of explicitly naming the alternative.

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 is given on when to use this tool versus list_document_types or other document-type tools. The use case (fetching a single document type by ID) is implied by the description and schema, but not stated explicitly, and there is no mention of prerequisites or alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds valuable behavioral nuance beyond those hints: it checks upstream rather than the installed instance, and explains that the two only coincide when the instance is current. Missing details like network failure handling or rate limits are secondary given the openness implied by openWorldHint.

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

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

The description is three sentences with no filler. The primary action is front-loaded, the critical distinction from get_server_info is stated immediately, and the caveat about coincidence is compact and relevant. 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?

With no parameters, an output schema present, and annotations covering behavioral safety, the description fills the remaining gap by explaining what the output means ('newest release published on GitHub' vs. 'installed version') and how it relates to the connected instance. It also routes the agent to the complementary tool for the installed version, making the call context 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?

The tool has zero parameters and schema coverage is 100%, so the schema carries no burden. Per the baseline for 0-parameter tools, a score of 4 is appropriate because there is nothing for the description to add about parameters, and it does not attempt to pad that space with irrelevant detail.

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 ('Check') and resource ('newer release of Paperless-NGX upstream'), and clearly distinguishes it from related tools by explicitly noting it does not report the installed version. It names the sibling get_server_info for that purpose, making the differentiation concrete even without comparing schemas.

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

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

The description explicitly tells the agent when to use this tool (to check for a newer upstream release) and directs it to get_server_info for the installed version. It also clarifies the relationship between the two values, which prevents common misuse where an agent might expect the installed version.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds a specific behavioral nuance about visibility flags being null when payload v10 omits those preferences, which is context beyond the annotations. No contradiction detected.

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. The primary purpose is front-loaded, and the second sentence adds a targeted behavioral detail. No unnecessary elaboration.

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 get-by-ID tool with an output schema and comprehensive safety annotations, the description covers the key nuance (null visibility flags). No critical missing information; mentioning the sibling list_saved_views would be nice but is not essential for correctness.

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

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

Schema description coverage is 0%, so the description must compensate. It only says 'by ID', which does not clarify what a saved view is, any constraints, or the meaning of view_id beyond the schema's integer type. The description adds minimal value to parameter understanding.

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 ('Fetch'), a resource ('saved view'), and identifies the parameter as ID. It clearly distinguishes from sibling list_saved_views by focusing on retrieving a single view by identifier. The purpose is unambiguous.

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

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

The description implies usage when a view_id is available but does not explicitly state when to use this versus alternatives like list_saved_views, nor does it mention exclusions or prerequisites. Guidance is minimal and left 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?

The annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the useful conditional detail that the upstream version block appears only 'when configured', but it otherwise provides no deeper behavioral context such as failure modes or configuration prerequisites.

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

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

The description is two crisp sentences: purpose is front-loaded, return fields are named, and the use case is stated. Every sentence earns its place with 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 read-only tool with an output schema, the description covers purpose, return fields, a conditional behavior, and a use case. The only notable gap is the lack of an explicit contrast with the version-related sibling get_remote_version, which would make the selection decision more robust.

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 input schema has zero parameters, so there is nothing to explain and the description correctly avoids inventing parameter details. This matches the baseline for a zero-parameter tool.

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

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

The description uses a specific verb ('Report') and a clear resource ('wrapper and upstream version info for paperless-mcp'), then lists the exact returned fields. This makes the tool's purpose very clear, but it does not explicitly differentiate it from the similarly named sibling get_remote_version.

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 statement 'Useful for verifying a deployment matches the expected build' provides a concrete, explicit context for when to call this tool. It does not exclude alternatives or mention get_remote_version, but for a simple read-only info endpoint this is sufficient guidance.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is established. The description adds no additional behavioral context, but it also does not contradict the annotations.

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

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

The description is a single six-word sentence with no filler, front-loading the action and resource. It is appropriately sized for a one-parameter read operation.

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 get-by-ID operation with an output schema and safety annotations already provided, the definition contains everything an agent needs to invoke the tool correctly. Nothing material 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 0%, so the description carries the burden of explaining the parameter. The phrase 'by ID' merely restates the parameter name share_link_id rather than clarifying what a share link ID is or how it behaves, failing to compensate for the missing schema documentation.

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 the verb 'Fetch' and the resource 'share link' along with the lookup key 'ID'. This clearly distinguishes it from sibling tools like list_share_links and the document-oriented get_* operations.

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

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

No when-to-use guidance or explicit alternatives are provided. The only implicit hint is 'by ID' versus list_share_links, but the description never states that this tool is for retrieving a single known share link or when it should not be used.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only 'collection-level' scope and no additional behavioral detail such as freshness, performance, or output caveats; it does not contradict the annotations.

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

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

One short declarative sentence with no filler, and the scope qualifier 'collection-level' is front-loaded. Every word earns its place.

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

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

With no parameters, read-only and idempotent annotations, and an output schema present, the description contains all the operational information an agent needs to invoke the tool correctly. Return-value details are intentionally delegated to the 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?

The input schema has zero properties, so there are no parameters to document. Per the baseline for zero-parameter tools, the description does not need to provide parameter-level semantics.

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 the operation and resource directly ('Fetch collection-level statistics'), and the phrase 'collection-level' signals aggregate scope, distinguishing it from the many document/item-specific sibling tools. This is a specific and unambiguous action statement.

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

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

The description implies use when aggregate collection-wide statistics are needed, but it never states when not to use it, names an alternative such as get_server_info, or gives any conditions. An agent must infer usage from the tool name and title.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior; the description's 'Fetch' aligns with those and adds no extra behavioral caveats. For a simple getter this is sufficient, though the description contributes no behavioral detail beyond the annotations.

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

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

One compact sentence that delivers the core action and parameter relationship with no filler. Everything present 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 one-parameter, read-only, idempotent getter with an output schema and rich annotations, this description is complete. An agent has everything needed to select and invoke it correctly.

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

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

With 0% schema description coverage, the description compensates by identifying the single parameter's role as the lookup key ('by ID'). The parameter's name and integer type make the remaining semantics self-explanatory.

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?

'Fetch a storage path by ID' names a specific action, resource, and lookup mechanism. The singular 'by ID' distinguishes it from list_storage_paths and other sibling getters, so an agent can select it 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 by-ID lookup makes the appropriate context clear: use when you already have a storage_path_id and need that single resource. It does not explicitly name list_storage_paths as the alternative when an ID is not known, so it falls just short of full alternative routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'Fetch' is consistent with those traits. It adds no extra behavioral context such as not-found behavior, but the annotation coverage makes this an acceptable baseline.

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

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

The description is four words with no filler or redundancy. It front-loads the action, resource, and the key identifying parameter, so every word 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 one-parameter getter with an output schema and annotations covering the safety profile, the description is functionally complete enough for an agent to call it correctly. It omits missing-tag behavior, but the low complexity and rich annotations prevent this from being a significant 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?

Schema description coverage is 0%, but there is only one parameter, tag_id, and the phrase 'by ID' directly maps to it. The description adds minimal meaning beyond the schema and does not clarify where a valid ID comes from or what constraints apply.

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

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

The description clearly states a specific action, 'Fetch', and a specific resource, 'a tag', with an ID qualifier. This makes it clear the tool retrieves a single tag rather than listing all tags, though it does not explicitly contrast with sibling tools like list_tags or create_tag.

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 intended use case is implied: call this when you have a tag_id and need a single tag. However, the description gives no explicit guidance about when to prefer get_tag over list_tags, nor does it address edge cases such as a nonexistent ID.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds a valuable behavioral detail beyond those: it returns None when no such task exists. There is no contradiction with the annotations.

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

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

Two concise sentences with no filler. The primary action is front-loaded, and the return behavior is stated immediately after.

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 one-parameter, read-only fetch with an output schema and safety-related annotations, the description is nearly complete. The only real gap is not cross-referencing sibling tools, which is already reflected in the usage_guidelines score.

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

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

With 0% schema description coverage, the description must clarify the parameter, and 'by UUID' does add some meaning to task_uuid. However, it never explicitly describes the parameter format, source, or constraints beyond what the property name already implies.

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

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

The description uses a specific verb ('Fetch'), a clear resource ('a task'), and the identifying key ('by UUID'). It also states the not-found behavior, which distinguishes it from list_tasks and wait_for_task without ambiguity.

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

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

The description implies this tool is for retrieving an individual background task when its UUID is known, but it does not explicitly say when to choose it over list_tasks or wait_for_task. There is no when-not guidance or mention of alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful behavior: the meaning of `last_correspondence` (null when no documents) and that `ordering` accepts it. Still, it does not disclose return details beyond one field, and pagination behavior is left implicit.

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

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

The description is short and front-loaded, with the core action stated first and one additional field-semantics sentence. Every sentence earns its place, and there is no boilerplate. The formatting with backticks is slightly awkward but does not hurt readability.

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 list endpoint, the main gap is the undocumented `name__icontains` filter, which an agent would need for name-based lookups, and the lack of allowed ordering fields beyond `last_correspondence`. The output schema and annotations reduce some burden, but the description does not equip an agent to use both the pagination and filtering parameters confidently.

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

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

Schema description coverage is 0%, so the description must compensate, but it only clarifies `ordering` (as accepting `last_correspondence`). The non-obvious `name__icontains` filter is left unexplained, and `page`/`page_size` are only inferable by convention. This is insufficient compensation for four undocumented parameters.

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

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

The description states a specific verb and resource: 'List correspondents.' It is clearly distinct from singular siblings like get_correspondent and mutating ones like create_correspondent. However, it does not explicitly contrast with any sibling, so it stops 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?

No guidance is given on when to use this tool versus alternatives. The description implies usage through the verb 'List' but never states exclusions or references get_correspondent or list_documents. A tool that merely names its action without selection criteria provides no real usage direction.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so there is no contradiction. However, the description adds no behavioral detail beyond 'list'—it does not mention pagination, ordering behavior, or any other runtime characteristic, so it provides no value beyond the annotations.

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

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

The description is genuinely brief and front-loaded, with no filler or redundant sentences. However, it is under-specified rather than appropriately compact—it essentially repeats the title and lacks structure or detail that would help an agent use the tool.

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

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

Given that all parameters are optional, annotations cover the safety profile, and an output schema exists, an agent can call the tool with defaults and understand the return shape. Still, there is no explanation of ordering semantics, pagination defaults, or when to prefer this over get_custom_field, making it only minimally 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 0%, and the description mentions none of the three parameters. An agent cannot learn what page, ordering, or page_size mean semantically, what values ordering accepts, or how pagination behaves, so the description does nothing to compensate for the schema's lack of parameter documentation.

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

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

The description states a clear verb and resource: 'List custom fields' tells an agent this retrieves the collection of custom field objects. It is not differentiated from siblings like get_custom_field or other list tools, but the resource is specific enough to avoid ambiguity.

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 about when to use this tool versus alternatives. The description does not mention get_custom_field for retrieving a single field, nor does it explain when list_custom_fields is appropriate, leaving the agent to infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds behavioral context about response content: OCR content is stripped, notes and custom fields values are stripped but metadata refs retained, and pagination returns one page. This goes beyond annotations and informs the agent about data truncation and how to retrieve full values.

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

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

The description is three concise sentences, front-loaded with the core purpose and pagination, then detailing what is stripped and pointing to alternatives. There is no fluff or redundant information; every sentence adds value.

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

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

The description covers the main behavior, pagination, and content truncation, and the output schema (not shown) likely defines the return structure. However, it lacks parameter-level guidance for the eight optional filters, which could be important for correct invocation. Given the annotations and output schema, the description is adequate but not fully comprehensive for a tool with many optional parameters.

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

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

Schema description coverage is 0%, meaning the schema provides no parameter descriptions. The description only mentions 'optional filters' without explaining the meaning or usage of any of the eight parameters (e.g., tags, custom_field, storage_path). Parameter names are somewhat self-explanatory, but the description does not add semantic value to help the agent choose or format filter values.

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

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

The description clearly states the tool's function: 'List documents with optional filters. Returns one page.' It also distinguishes itself from related tools by noting what is stripped (OCR content, notes, custom fields) and pointing to alternatives like get_document_content, get_document, and get_document_notes. This makes the purpose unambiguous and differentiates it from siblings.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: 'Use get_document_content for a bounded preview' and 'use get_document or get_document_notes to read those values.' It also implies pagination usage by stating 'Returns one page.' However, it does not directly contrast with search_documents or explain when a list vs. a search is appropriate, which is a minor gap.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive, but the description adds no behavioral detail beyond the word 'List'. It does not mention pagination behavior, filtering semantics, or any other runtime traits beyond what structured metadata provides.

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

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

The description is a single sentence with no padding, but it is under-specified rather than usefully concise. It adds essentially no information beyond the tool title and does not earn its place as a meaningful explanation.

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

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

The operation is simple, has zero required parameters, and is backed by rich annotations plus an output schema, so an agent could call it with no arguments. However, it lacks guidance on filtering, pagination, and when listing is the right choice among sibling tools, leaving a clear but minor 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?

Schema description coverage is 0%, so the description needed to explain page, ordering, page_size, and name__icontains, but it does not mention any of them. The parameter names and defaults in the schema hint at meaning, but the description itself fails to compensate for the complete absence of parameter documentation.

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

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

The description uses a specific verb ('List') and a clear resource ('document types'), so the core action is immediately understandable. It does not, however, differentiate this from sibling tools like get_document_type or list_documents.

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 is provided on when to use this tool versus alternatives such as get_document_type, create_document_type, or bulk_edit_document_types. The only hint is the tool name itself, and no exclusions or preconditions are stated.

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

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

Annotations already cover readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds one useful behavioral detail: visibility flags can be null when payload v10 omits them. It does not mention pagination behavior, ordering, or empty-result handling, so it only partially fleshes out the behavior.

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

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

The description is compact at two sentences. The first sentence restates the tool name without new information, but the second sentence adds a meaningful edge case. There is no filler, and the important note is placed clearly.

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

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

This is a simple paginated list endpoint with an output schema and read-only annotations, so the description does not need to explain return values or safety. The visibility-flags note covers a relevant quirk. The main omission is any statement about how pagination parameters affect results, but those are largely inferable from the schema.

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

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

The description adds no explanation for the page or page_size parameters, and schema description coverage is 0%. However, the schema itself includes meaningful defaults, minimums, and maximums that make the pagination parameters reasonably self-explanatory. Still, the description does not compensate for the lack of property descriptions.

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

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

The description states a specific verb and resource: 'List saved views.' This is unambiguous and clearly distinct from the sibling get_saved_view, which retrieves a single item. It is nearly identical to the title, and a more explicit scope statement would earn a 5, but the intent is plain.

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 is given about when to use list_saved_views versus get_saved_view or other list alternatives. The agent is left to infer from the name alone. There are no stated prerequisites, exclusions, or scenarios mentioning the sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that filtering by document is possible, but does not disclose pagination behavior or response format. With annotations covering safety, this is adequate.

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

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

The description is a single sentence, concise and to the point. It front-loads the core purpose and quickly mentions the optional filter. No wasted words.

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

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

The tool is a simple list operation with no required parameters, and an output schema exists (though not shown), so the description needn't detail return values. However, given low schema coverage, the description could expand on parameter roles to achieve complete self-explanatoriness. It's acceptable for a simple tool but leaves some 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 0%, and the description only mentions 'document' filtering but does not explain any parameters in detail. It does not add meaning for 'page', 'page_size', or even clarify that 'document_id' is the filter parameter. Since schema coverage is low, the description fails to compensate.

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 'List share links' which is a specific verb and resource, and notes optional filtering by document. It is clear but does not explicitly differentiate from siblings like get_share_link, though the plural 'list' implies a collection operation.

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

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

The description implies when to use (to list share links, optionally filtered), but provides no explicit guidance on when not to use or alternatives. Since there is a get_share_link sibling, it would be helpful to mention that get_share_link is for a single link, but this is not 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?

The description adds no behavioral context beyond what annotations already provide (readOnly, idempotent, non-destructive). It does not mention pagination behavior, ordering, or return format, leaving the agent uninformed about operational details.

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

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

The description is extremely short, but this is under-specification rather than conciseness. It omits essential information that should be present for a tool with pagination parameters.

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 three parameters and no schema descriptions, the description provides no usage guidance, parameter explanation, or behavioral context. The existence of an output schema does not compensate for the lack of operational information.

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

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

Schema coverage is 0% and the description does not explain any of the three parameters (page, ordering, page_size). The agent receives no semantic guidance beyond the parameter names.

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

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

The description states a clear verb and resource ('List storage paths'), but it is minimal and does not differentiate from siblings like get_storage_path or other list tools. It lacks any context about what storage paths are or how they relate to other resources.

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 tool versus alternatives. No mention of pagination, filtering, or when get_storage_path would be more appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. However, the description adds no behavioral context beyond the bare operation label; it does not mention pagination limits, filtering behavior, or what the returned tag list represents.

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

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

The description is brief, but brevity is not effective conciseness when the only sentence is a restatement of the title. It contains no useful structure and wastes the opportunity to communicate behavior.

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

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

The annotations and output schema reduce the burden, but the description still omits filtering, sorting, and pagination semantics. With four optional parameters that all lack schema descriptions, an agent does not have enough context to use them 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 0%, and the description is simply 'List tags.' It makes no mention of page, ordering, page_size, or name__icontains, so the agent must infer semantics solely from parameter names. This is especially insufficient for a non-obvious parameter like name__icontains.

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 is the tautological phrase 'List tags,' which repeats the tool name and title without adding scope, filtering, pagination, or distinction from sibling operations like get_tag. It identifies a verb and resource but adds no differentiating detail.

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 is provided about when to choose list_tags over list_documents, get_tag, or bulk_edit_tags, and no exclusions or prerequisites are stated. The description leaves the decision entirely to the agent.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds substantial detail beyond that: default unacknowledged filtering, one-page newest-first pagination, version 10 field additions, legacy compatibility projections, uppercase status spelling, and the meaning of the bulk_update task_type. No contradiction with annotations.

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

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

The description is dense but well organized: core purpose, default behavior, filtering guidance, and version compatibility notes. It front-loads the most important facts. The version-compatibility paragraph is somewhat long but earns its place given the API's complexity, so this is not a case of fluff.

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

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

Given the output schema and annotations, the description covers defaults, pagination, task_type filtering, and version differences. It leaves minor gaps around the exact semantics of the status filter and page_size, but the tool is still safely callable. For a tool with six parameters and versioned behavior, this is a high level of completeness.

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

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

Schema description coverage is 0%, so the description must compensate for the parameters. It does explain include_acknowledged, acknowledged, and task_type, with a concrete bulk_update example. However, status, page, and page_size are not meaningfully described beyond the phrase 'Returns one page,' leaving some parameter semantics to be inferred from names and schema enums.

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

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

The description opens with a specific verb and resource: 'List Paperless Celery tasks.' It clearly distinguishes itself from sibling list_documents by focusing on background work rather than documents, and it connects to related tools by noting that bulk_update is the indexing rebuild queued by bulk_edit_documents and can be waited on with wait_for_task.

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

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

The description gives explicit context for when to use the tool, such as inspecting unacknowledged tasks by default and passing task_type to filter. It also explains the workflow relationship with bulk_edit_documents and wait_for_task. It does not explicitly list exclusions or say 'use get_task instead for a single task,' but the guidance is strong.

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

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

Annotations already establish the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds genuinely non-obvious behavior on top: per-hit OCR content is stripped, and notes/custom_fields values are 'always' stripped from hits. This is high-value disclosure that annotations cannot express. Minor gaps remain (no mention of result ordering, ranking, or count semantics), but the critical quirks are 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?

Four short, information-dense sentences with zero fluff. Purpose is front-loaded, followed by the OCR-content stripping warning and routing, then the always-stripped field warning. Paragraph breaks group related ideas cleanly and every sentence earns its place.

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

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

Given the output schema documents return values and annotations cover the read-only/idempotent safety profile, the description covers the remaining essentials: purpose, sibling routing, and field-stripping behavior. Pagination behavior and exact matching semantics are minor omissions for a moderately simple 4-parameter tool.

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

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

Schema description coverage is 0%, so the burden is on the description to explain parameters. It adds meaning for more_like ('use for similarity search'), which the schema only types as integer|null. However, query semantics (search syntax, what fields are matched) and page/page_size behavior are left to inference, so compensation is only partial.

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

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

"Full-text search documents" uses a specific verb and resource, clearly distinguishing this from list_documents (listing) and get_document/get_document_content (fetching one record). The description further differentiates by naming get_document_content as the preview alternative and get_document/get_document_notes as the routes for stripped fields, so an agent can pick the right sibling without opening schemas.

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 routing guidance is given: use get_document_content for a bounded preview of one hit, use more_like for similarity search, and fetch stripped notes/custom fields via get_document or get_document_notes. Conditional alternatives are named concretely rather than left to inference.

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

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

Annotations already indicate a write operation (readOnlyHint=false), idempotency, and non-destructiveness. The description adds no behavioral context beyond the word 'patch', such as what happens to unspecified fields, whether the correspondent must exist, or whether patch merges or replaces. It relies entirely on the annotations.

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

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

The description is a single efficient sentence with no wasted words, and the key action is front-loaded. It is concise, though the brevity borders on under-specification, which is reflected in other dimensions.

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 a nested patch object, required correspondent_id, and multiple sibling tools, the description is too thin. It does not explain the relationship between the fields, valid matching_algorithm values, or how patch behaves with defaults. The output schema may cover return values, but callers lack enough context to invoke this 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 0%, so the description bears full responsibility for explaining parameters. It only says 'selected fields' without naming correspondent_id or the patch sub-fields (name, match, is_insensitive, matching_algorithm). This adds little meaning over the schema structure.

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

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

The description uses a specific verb ('Patch') and resource ('correspondent'), and 'selected fields' conveys a partial-update semantics. It is not a tautology, and it clearly distinguishes this tool from create/delete/list operations, though it does not explicitly compare against sibling update 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?

There is no guidance on when to use this tool versus alternatives like create_correspondent, bulk_edit_correspondents, or delete_correspondent. No prerequisites, exclusions, or context are provided; usage is only implied by the resource name.

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

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

Annotations already mark idempotentHint:true, destructiveHint:false, but the description adds crucial behavioral details: it explains the destructive side effect of dropping options in the select list (deletes them and referencing document values) and how renaming (patch without extra_data) preserves options. This goes beyond annotations and is essential for agent decision-making.

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

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

The description is dense with technical detail but efficiently organized with bullet points for the two data types. It is front-loaded with the core action and then provides necessary examples. Slightly long but each sentence earns its place given the complexity.

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

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

With a nested object schema and 0% schema coverage, this description is thorough. It covers the two main extra_data variations, gives examples, and points to create_custom_field for the full table. It doesn't describe return values, but an output schema exists. Minor gap: doesn't mention error conditions or idempotency implications, but the idempotent hint covers that.

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

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

Schema description coverage is 0%, so the description must shoulder the load. It thoroughly explains the semantics of extra_data for two data types, including how to preserve, create, and delete options. It also clarifies that field_id is an identifier and patch is a partial update object. This far exceeds the bare schema.

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