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

Goes well beyond the destructiveHint/readOnlyHint/openWorldHint annotations by disclosing that nothing is deleted, all data is retained, the action is reversible via restore-document, and that an already-archived document is a precondition failure. This reconciliation of 'destructive' annotation with a reversible operation is exactly the kind of context annotations cannot convey.

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

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

Front-loaded single-sentence definition, then compact bulleted triggers, then a short behavioral clause. Every sentence earns its place with no repetition of the schema or annotations.

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

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

For a one-parameter state-change tool with an output schema (so return values need no explanation), the description supplies preconditions, alternatives, reversibility, and data-retention behavior. Nothing material for correct invocation is missing.

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

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

Schema description coverage is 100% and the single parameter's schema description already explains what the UUID is and points to list-documents for discovery. The body text adds no further parameter detail, so the baseline 3 applies.

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

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

States a specific verb (archives) and resource (document) plus the observable effect (hiding it from the account's default document lists), which lets an agent distinguish it from siblings like move-document-to-done-stage and restore-document without opening a schema.

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

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

Explicitly enumerates when to use it ('no longer actively worked with', 'user asks to archive, hide, or clean up'), names the inverse operation (restore-document), and states the precondition that the document must not already be archived.

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 the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=false), so the description's burden is lower. It adds genuine behavioral context beyond the annotations: existing members are preserved (additive, not replacing) and where the UUID inputs originate. It does not state permission requirements or behavior on duplicate/invalid UUIDs.

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

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

Front-loaded with the core action, then a short bulleted when-to-use block, then preservation and source-of-input detail. Every sentence earns its place, though the single-bullet 'Use this tool when' block is slightly heavier formatting than the content warrants.

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 and annotations cover the safety profile, so return values and reversibility need not be spelled out. The description covers the mutation semantics and input provenance; only failure modes (duplicate membership, invalid/foreign UUIDs, permission errors) are unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by telling the agent where to obtain account_user_uuids (list-account-users, list-account-team-members for copying between teams, or user-referenced UUIDs). That is real value beyond the schema's plain type definitions.

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

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

States a specific verb (add/attach) and resource (account users as team members) with clear scope: one or more users, added to a team. It also distinguishes itself from detach-account-users-from-team and from team-level update tools by clarifying that existing members are preserved.

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

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

Provides an explicit trigger ('Use this tool when: The user asks to add people to a team') and names the inverse sibling (detach-account-users-from-team) for removal. It does not discuss edge cases such as users already being members or when to prefer update-account-team, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the safety profile is already known; the description adds real behavioral context beyond that, notably that relevant_metadata_uuids are made relevant for the new type *alongside* the types they already have (an account-wide side effect), and that system types already exist on every account. It stops short of describing reversibility or duplicate-name failure 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?

Front-loaded with the one-line purpose, then when-to-use, then the prerequisite, then per-parameter guidance — a good structure for a 4-parameter creation tool. It is verbose though, with illustrative quotes for both description and prompt, and the closing clause about list-account-metadata reporting relevance borders on extraneous.

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 values need no explanation. For a creation tool with rich free-text parameters, the description covers naming conventions, AI-selection semantics, cross-tool prereqs, and the downstream relevance effect — nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is already 100%, yet the description still adds substantial meaning: Title Case naming conventions with worked examples ('a type for supplier framework contracts' → 'Supplier Framework Agreement'), the selection-criterion phrasing expected for prompt, and the semantics and constraints of relevant_metadata_uuids (only account-owned and system_reference fields, sourced from list-account-metadata).

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

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

States a specific verb and resource ('Create a new custom document type for the account') and immediately separates itself from siblings by naming list-account-document-types and describing the pre-existing system types. An agent can distinguish this from update- or delete-account-document-type without opening any schema.

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

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

Provides explicit when-to-use bullets, names the prerequisite call ('Call list-account-document-types first'), and gives an exclusion rule ('Create a new type only when none of the existing ones fits'). It also routes to list-account-metadata for candidate metadata fields, which is unambiguous 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 only declare readOnlyHint=false/destructiveHint=false/openWorldHint=false, but the description adds substantial behavioural context: `name` and `value_type` are immutable after creation, system metadata fields cannot be re-created under the same name, and `keywords` have no effect without a `prompt`. It also explains that select_values are rejected for other types and that AI analysis is on by default.

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

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

Front-loaded with purpose and trigger conditions, and each paragraph carries real guidance. However, it is long and repeats schema content almost verbatim (the select_values rule, the Title Case rule, the immutability of name/value_type), so not 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?

An output schema exists, so return values need not be explained. For a 9-parameter creation tool with AI-prompt semantics, the description covers creation constraints, naming conventions, sibling routing, select_values coupling, and prompt/keywords interaction — everything an agent needs to call 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 coverage is 100% so the schema already documents all nine parameters, but the description adds meaning beyond it: a worked naming example (a 'product colour' request should yield `product_colour` / "Product Colour"), the Title Case convention, and the instruction to confirm unspecified details rather than guess. Some of this (Title Case, select_values requirement) restates the schema, so it is not purely additive.

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?

Opens with a specific verb+resource: 'Create a new account-level metadata field definition.' This clearly distinguishes it from siblings like create-account-document-type, create-account-tag, and update-account-metadata. An agent can identify both the action and the target object 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?

Explicit 'Use this tool when' bullets cover the two real triggers, and it names two concrete alternatives/prerequisites: call list-account-metadata first to avoid duplicates and system fields, and use update-document-metadata-values afterwards to write values. Both when-to-use and when-not-to-use are covered.

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=false, destructiveHint=false, openWorldHint=false), so the description carries a lower burden. It adds a little scope context about where the tag lives and what it is later attached to, but says nothing about duplicate-name behavior, required permissions, or failure modes for a creation tool.

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

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

The imperative action is front-loaded in sentence one, followed by a short scannable usage list and a brief parameter note. Nothing is padded, though the trailing parameter sentence is largely redundant with the schema.

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

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

An output schema exists, so return values need not be described, and annotations cover the mutation semantics for this simple two-parameter creation tool. The only real gap is the absence of guidance on uniqueness/duplicates, which is minor at this complexity level.

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

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

Schema coverage is 100% and both parameters are required and documented in the schema. The description merely restates the same constraints (max 40 chars, hex format), adding no syntax or semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The first sentence states a specific verb and resource (create a tag) plus scope ('in the current account'). It implicitly contrasts with the update-account-tag and delete-account-tag siblings, but never names an alternative or explicitly clarifies which operation this is versus 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?

An explicit 'Use this tool when' list gives two concrete triggers, including the otherwise non-obvious prerequisite case of needing a tag to exist before attaching it to documents or templates. It lacks any when-not guidance (e.g., check list-account-tags first to avoid duplicates) or named 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 this is a non-read-only, non-destructive, closed-world mutation, so the safety profile is covered. The description adds behavior those annotations cannot convey: the team receives a default icon and the agent should not ask the user about it, and the created UUID should not be surfaced to the user. No mention of duplicate-name handling or error behavior, but the added context is genuinely useful.

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

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

Front-loads the core action in one sentence, then uses a short bullet list for trigger conditions and two terse directives for edge behaviors. Slight redundancy between the lead sentence and the first bullet, but nothing is padding.

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

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

With an output schema present, return values need not be explained, and the description covers the trigger conditions, the required parameter, and the two behavioral quirks an agent would otherwise guess wrong. It does not address failure modes such as duplicate team names, which is the only remaining gap for a simple two-parameter creation tool.

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

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

Schema coverage is 100%, so the schema baseline is 3. The description goes beyond it by stating that only `name` is required, pre-empting a question about an icon parameter that does not exist, and framing `account_user_uuids` as 'initial members' at creation time, which clarifies intent versus the separate attach-account-users-to-team 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?

States a specific verb and resource with scope: 'Create a new team in the current account.' The resource (team) is unambiguous against the many create-* siblings, so an agent can differentiate it from create-template-from-scratch or create-account-tag without reading further.

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

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

Explicit 'Use this tool when' bullets cover the trigger conditions, and one bullet supplies the sequencing rationale (a team must exist before being attached to documents or templates), which maps to sibling tools like update-document-teams. It stops short of naming a when-not case or an alternative tool, so it is clear context rather than full routing guidance.

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

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

Annotations establish this is a non-read, non-destructive create. The description adds real context beyond that: the two-step prerequisite workflow, that template_uuid may be required per account settings, that auto_apply_ai_analysis falls back to an account default from get-account-info, and that initial_stage must be prompted from the user. It stops short of describing side effects or the resulting document state.

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

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

Purpose is front-loaded, followed by a bulleted when-to-use block and then the prerequisite/parameter guidance. The longer length is justified by the 9-parameter workflow, and each sentence carries actionable 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 9-parameter creation tool with an output schema (so returns need not be explained), the description covers purpose, when to use it, prerequisites, conditional requirements, and defaults. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so each parameter is already documented, and the description mostly restates that (UUID discovery via list-account-teams/tags/parties, initial_stage values, auto_apply_ai_analysis default). It adds the workflow framing around file_upload_uuid but little semantic detail the schema lacks, so baseline 3 is appropriate.

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

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

The description states a specific verb (Create) and resource (a new document) and identifies the source as a PDF previously uploaded, immediately distinguishing it from create-document-from-scratch and create-document-from-template. The two usage bullets further sharpen what the tool is for.

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

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

It gives explicit when-to-use conditions (import an existing PDF as a draft, or record an already-signed PDF by setting initial_stage to "done") and names the prerequisite tool create-document-pdf-upload-url with the ordering and upload step required before this call. Conditional requirements for template_uuid and auto_apply_ai_analysis are also flagged.

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 safety profile is covered. The description adds genuine behavioral context beyond that: the document is created in the draft stage with no content, and the optional arguments expect UUIDs. It does not describe permissions or side effects of team assignment, but it exceeds the annotation 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?

Front-loaded with the core action and well organized into condition, state, alternative, and parameter notes. Slightly verbose for a single-bullet 'Use this tool when' list, but every sentence carries information.

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

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

With an output schema present, return values need not be explained. The description covers the creation stage, the template alternative, and the discovery tools for the optional UUIDs, leaving nothing an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including their UUID sourcing. The description largely repeats the same discovery-tool mapping without adding format, constraint, or default details beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource (create a new empty document) and explicitly distinguishes itself from create-document-from-template by contrasting blank vs. template-based creation. An agent can route between the two siblings without opening either schema.

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

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

Contains an explicit 'Use this tool when' condition (user wants a blank document not based on a template) and names the alternative tool (create-document-from-template) with the condition that selects it. Nothing is 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 declare destructiveHint=true and openWorldHint=true, but the description adds material context beyond them: start_signing=true moves the document into the signing stage and invites signatories, and the call 'fails if any required information (party data, mandatory dynamic field values, signature blocks) is missing.' This is exactly the kind of side-effect and failure-mode disclosure an agent needs before invoking.

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

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

Front-loaded with the purpose, then usage, then the field-value rules, then the start_signing caveat - a sensible ordering with no filler sentences. The type-by-type rule list is long, but it is dense, referenceable content rather than padding, so only mild deduction for overall length.

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 6-parameter mutation tool with a nested-heavy schema, annotations, and an output schema present, the description covers purpose, usage, prerequisite discovery, value encoding, and failure conditions. Return values need not be explained because an output schema exists, and nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is already 100%, so the baseline would be 3, but the description goes well beyond the schema by prescribing the exact value-construction rules per dynamic field type (currency -> "EUR;1000.10", currency_duration -> "EUR;1000.10;monthly", bool -> "true"/"false", duration -> "P6D", multi_select -> values array). That is meaning the schema does not carry.

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

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

The opening sentence gives a specific verb and resource ('Create a new document from a template') plus the optional pre-fill scope, which implicitly separates it from create-document-from-scratch and create-document-from-pdf-upload. It never names those siblings explicitly, so differentiation is by inference rather than by explicit contrast.

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

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

Provides an explicit 'Use this tool when' condition ('The user wants to generate a document based on an existing template') and a concrete prerequisite workflow: call get-template-info with include=["parties", "signatories", "dynamic_fields"] before populating the arguments. Nothing about when to reach for this tool is 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 declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that - no mention of required permissions, whether an existing party is replaced, or side effects - so it provides minimal added 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 first sentence is efficient, but the 'Use this tool when' bullet is pure tautological filler that consumes space without adding information. Under-specification dressed as structure rather than genuine 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?

An output schema exists, so return values need not be explained, and annotations cover the mutation safety profile. However, for a create operation with several close siblings, the description leaves the agent without guidance on prerequisites or alternative tools, so it is 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 100%, so the schema already documents all six parameters including the enum and mutual-exclusion rules. The description adds no parameter meaning at all, making the baseline 3 correct.

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

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

The opening sentence gives a clear verb+resource ('Adds a new party to a document'), which an agent can act on. However, it does not differentiate from close siblings like create-template-party, update-document-party, or create-document-signatory, so it falls short of a 5.

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

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

The 'Use this tool when' section is circular: 'You need to add a new party to a document' simply restates the purpose. No alternative tool is named, no exclusions, and no condition that would route the agent between this and create-template-party or update-document-party.

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?

Goes well beyond the annotations by disclosing the two-step upload workflow, the fact that the URL expires (expires_at), and the required POST mechanics (fields sent as form fields before the file itself). This is rich operational context the annotations do not 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?

Front-loaded purpose, a clean usage bullet, and a returns paragraph. The returns detail partially duplicates the output schema, but it earns its place by explaining ordering and downstream usage. Minor redundancy keeps it from a 5.

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 an output schema already exists, the description need not explain returns, yet it does so usefully. Combined with the workflow tie-in to create-document-from-pdf-upload, nothing an agent needs to call this correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description instead front-loads return-value semantics (uuid, url, fields, expires_at), which is extra but not param-focused.

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

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

States a specific verb and resource ('Create a signed URL that a single PDF can be POST-uploaded to') and explicitly ties it to the follow-up tool create-document-from-pdf-upload. An agent can immediately distinguish this from create-document-from-scratch or create-document-from-template.

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

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

Provides an explicit 'Use this tool when' condition ('The user wants to create a document from an existing PDF file and you need somewhere to upload it to first') and names the downstream sibling. It lacks a 'when not to use' clause, but the routing context is clear.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds a genuinely useful, non-obvious behavior: when the email matches an existing account user, optional arguments are ignored and the profile populates the signatory data.

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

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

Front-loads the verb+resource in the first sentence, then usage and the caveat. A single-bullet list is mildly awkward but every sentence carries information; nothing is wasted.

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

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

With an output schema present, return values need not be explained, and all 7 parameters are documented. The description covers the usage context and the key behavioral caveat, leaving little an agent needs that is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining why the optional fields may be silently ignored (email matching an existing user), which helps an agent understand argument precedence.

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

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

States a specific verb and resource: 'Adds a signatory to a document.' This clearly distinguishes it from the delete/update signatory siblings in intent, though it does not explicitly name the alternatives to route against.

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 'Use this tool when' block gives a concrete precondition: a document with one or more parties configured, adding a signatory for one of the parties. Clear context, but no explicit when-not or pointer to update-document-signatory.

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 only declare the generic write profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description goes well beyond that by disclosing the critical non-obvious behavior: creating the field does not render it, and the returned ref_uuid must be referenced in the body before the placeholder appears. It also states the same two-step pattern applies to signature blocks.

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 long but well front-loaded (purpose first, then when-to-use, then the two-step warning, then type formatting). The signature-block and party-rendering asides are somewhat tangential to creating a dynamic field, but they do serve sibling routing, so they mostly earn their 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 9-parameter mutation tool with an output schema and full schema coverage, this description covers everything an agent needs: creation semantics, the rendering requirement, sibling boundaries, and per-type value formats. Return values are handled by the output schema and the reference to ref_uuid.

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

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

Schema coverage is already 100%, but the description adds substantial semantics beyond the schema, notably the exact string construction for `value` per `type` (currency 'EUR;1000.10', currency_duration with monthly/yearly suffix, PHP duration 'P6D', date format), the `values` array for multi_select, and the fact that select/multi_select require select_values. This is meaning the schema alone does not convey.

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

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

The opening sentence names a specific verb and resource ('Create a new dynamic field on a template'), and the body explicitly differentiates the tool from siblings such as create-template-party, create-template-signature-block, and update-template-dynamic-field. An agent can tell exactly which entity this tool creates 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 description gives explicit 'Use this tool when' conditions (adding a variable/fill-in field while building a template) and explicitly routes agents away from it for party names/addresses, naming the correct alternatives instead. It also names replace-template-content as the required follow-up call, leaving no ambiguity about sequencing.

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 only tell us this writes and is non-destructive. The description adds substantial behavioral context: the template is created empty with content authored later, ref_uuid references must pre-exist, and the key warning that authoring content first forces a destructive rewrite. This is exactly the extra context the annotations cannot carry.

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

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

Front-loaded with the core purpose and trigger, then uses a numbered list for the workflow, so it is easy to scan. It is long for a two-parameter tool and the dynamic-field/party explanation borders on didactic, but nearly every sentence carries decision-relevant guidance.

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 values need no explanation. The description covers purpose, when-to-use, sibling sequencing, reference prerequisites, the destructive-rewrite pitfall, and locale inference/fallback—more than enough for an agent to call 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 coverage is 100%, so both parameters are already documented, and the description's locale guidance largely restates the schema's own text. The ordering instructions don't map to any input parameter. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ("Create a new empty template with editable ProseMirror content") and immediately scopes it against siblings: "not from an existing PDF or template." An agent can distinguish it from create-document-from-scratch or duplicate-template without reading any schema.

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

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

Provides an explicit "Use this tool when" trigger plus a full when-not clause. It goes further and prescribes the correct sibling call order (party, signature block, dynamic field, then replace-template-content), which is actionable routing guidance.

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

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

Annotations only declare the safety profile (not read-only, not destructive, closed-world); the description adds materially more: the internal-vs-external field exclusivity rules, that adding a party grants no signing ability, and the downstream steps required before a document is affected. It does not cover permissions/auth requirements or what happens on duplicate references, so it falls short of a 5.

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

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

Front-loaded with the action and the when-to-use list, then organized into clearly labeled subsections (two ways to add, the two names, rendering, follow-up note). It is long for a create tool and repeats some schema-level constraints, keeping it just short of a 5, but every section carries operational 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?

An output schema exists, so return values need not be described, and the description still supplies the missing workflow context: how to render the party inline via ref_uuid in replace-template-content, the valid data-format values, and the signature-block follow-up. For a 6-parameter, 2-mode mutation tool this is complete enough to call correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics the schema does not: the conceptual difference between reference (role label, stable across documents) and entity_name (legal entity, usually omitted for counterparties), plus the rule that entity_name/address 'cannot be sent' with account_party_uuid. That goes beyond a restatement of field docs.

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

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

States a specific verb+resource ('Add a party to a template') and immediately disambiguates from siblings like update-template-party, create-document-party and delete-template-party by scoping the operation to templates and to creation. An agent can identify what this does 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?

Explicit 'Use this tool when' bullets name the triggering user intent and the workflow position (parties must exist before signatories/signature blocks). It names list-account-parties as the source of account_party_uuid and create-template-signature-block as the required follow-up, so alternatives and sequencing are spelled out rather than implied.

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

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

Annotations declare a non-read-only, non-destructive, non-open-world mutation, and the description adds real context beyond that: the block is created but not rendered until referenced in template content, exactly one of party_uuid/document_user_uuid must be supplied, and a user-bound block requires a signatory that belongs to a party. It does not mention auth/permission requirements or idempotency, but the two-step lifecycle disclosure is unusually valuable.

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

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

Front-loads the core action, then structures usage, constraints, and the two-step requirement clearly, with the HTML snippet earning its place. It is long and the dynamic-field analogy is arguably extra, but no sentence is filler and the ordering is logical.

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 values need no explanation, and annotations cover the safety profile. The description still supplies everything an agent needs to call this correctly: prerequisites, parameter exclusivity, discovery path, and the mandatory follow-up step.

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

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

Schema coverage is 100%, so the schema already documents each parameter; the baseline would be 3. The description adds meaning beyond it by contrasting party-bound (signed by every signatory of that party, whoever they turn out to be) with user-bound (signed only by the named signatory), plus the mutual-exclusion rule and the default values for style/scale.

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

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

States a specific verb and resource (add a signature block to a template) and immediately distinguishes the two binding modes, which is the key differentiator from siblings like create-template-party and create-template-dynamic-field. An agent can identify this tool 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?

Provides an explicit 'Use this tool when' list with three concrete scenarios, names the discovery alternative (get-template-info with include=["parties", "signatories"]), and points to replace-template-content as the required follow-up step. Both when-to-use and the downstream alternative are spelled out.

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 only say destructiveHint=true; the description goes far beyond by explaining that account-owned types are hard-deleted while fynk-provided types are merely deactivated and can be restored via update-account-document-type with reactivate:true. It also warns that customised types lose customisation and that in-use types are refused with a usage count.

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

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

Front-loads the action and then organizes the rest into a usage trigger, parameter provenance, behavioral consequences, and a failure mode. Slightly long with an awkward single-item bullet list, but almost every sentence carries distinct 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?

An output schema exists, so return values need not be explained. The description covers prerequisites, the delete-vs-deactivate distinction, the customisation caveat, and the in-use refusal, which is everything an agent needs to call this correctly and set user expectations.

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

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

Schema coverage is 100% and already documents the single uuid parameter's source, so the baseline is 3. The description adds value by tying the parameter to a required disambiguation step ('the user must have made clear which type they mean') and restating the provenance from list-account-document-types, which shapes how the agent must gather the value.

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

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

States a specific verb and resource ('Remove a document type from the account') and immediately scopes it to both account-owned types and fynk system types. An agent can distinguish this from update-account-document-type and list-account-document-types without opening any schema.

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

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

Gives an explicit trigger ('The user explicitly asks to delete or remove a document type') and adds disambiguation rules: the user must have made clear which type, and if not, ask and offer candidates by name. This is real when-to-use and how-to-proceed guidance rather than vague 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?

Beyond the destructiveHint=true annotation, the description discloses the cascade (all values on every document and template are removed irreversibly), the confirmation-refusal protocol gating confirmed_deleting_values_in_use, and the refusal while a bulk metadata operation is running. This is exactly the extra behavioral context annotations cannot carry.

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

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

Front-loaded with the core action and organized with bullets/logical paragraphs that earn their place for a destructive tool, though the confirmation flow is restated across two paragraphs, adding some redundancy.

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

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

With an output schema present the description need not describe return values, and it covers the destructive, irreversible, and refusal semantics plus alternatives. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented; the description nonetheless adds protocol-level meaning for confirmed_deleting_values_in_use (send only in answer to a refusal, never as a matter of course) and clarifies provenance of metadata_uuid, exceeding the schema baseline.

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

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

The opening sentence states a precise verb+resource+scope: 'Delete one of the account's own metadata field definitions.' It immediately demarcates the boundary against siblings by noting system fields (including system_reference) cannot be deleted and routing those cases to update-account-metadata.

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 when-to-use ('user explicitly asks to delete a metadata field'), a required precondition (metadata_uuid comes from list-account-metadata and the field must be unambiguous), and a named alternative for the adjacent intent (clear 'prompt' via update-account-metadata to stop a field being filled without losing values).

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 safety profile is known. The description adds a useful behavioral detail beyond annotations: the tag is automatically detached from documents and templates when deleted, clarifying the side effect. It does not discuss irreversibility or permission requirements, but the added context is meaningful.

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

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

Front-loaded with the purpose, then a short usage bullet, then the side effect. Three sentences with no wasted words, and the most important information is stated first.

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

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

Given the available output schema, annotations, and 100% schema description coverage, the description supplies purpose, trigger condition, and the key side effect of automatic detachment. It omits reversibility details and prerequisites, which are largely covered by destructiveHint=true, leaving only minor gaps.

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

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

Schema coverage is 100% and the single parameter tag_uuid is fully documented in the schema. The description does not add format, syntax, or lookup guidance for the UUID, so it meets the baseline of 3 when the schema carries parameter 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 a specific verb and resource: 'Delete an existing tag.' This distinguishes it from sibling tools like create-account-tag, update-account-tag, list-account-tags, and delete-account-document-type by both action and resource. The side-effect sentence further confirms the account-level tag scope by mentioning detachment from documents and templates.

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

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

Provides an explicit usage trigger: 'Use this tool when: - The user explicitly asks to delete a tag.' It lacks when-not guidance and does not name an alternative tool such as update-account-tag, but the context for use is clear.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavior: deletion auto-detaches the team from documents and templates, and it will fail if the team is an approver on any template — a meaningful precondition 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?

Front-loaded with the verb+resource, then a scannable trigger bullet, then the side-effect and failure caveats. No filler sentences; every clause carries information.

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

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

An output schema exists, so return values need not be explained. For a destructive, single-parameter tool the description covers trigger, cascading side effects, and the failure precondition — an agent has everything needed to call 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?

Only one parameter (team_uuid) with 100% schema description coverage, so the schema fully documents the input. The description adds no format or syntax detail beyond what the schema provides, making 3 the correct baseline.

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

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

"Delete an existing team" states a specific verb and resource, and the delete verb clearly separates it from the create-account-team and update-account-team siblings. It stops short of explicitly naming an alternative, but an agent will not confuse this with any other sibling.

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

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

The "Use this tool when: the user explicitly asks to delete a team" bullet gives an explicit positive trigger condition, and the last sentence discloses a precondition (fails if team is an approver on a template). No explicit when-not or named alternative, but the context is clear.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing a failure mode: removal may fail if the document's stage no longer permits signatory changes. It does not say whether removal is reversible or how the failure surfaces, keeping it below a 5.

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

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

One lead sentence for purpose, then a tightly scoped when-block and a one-line failure caveat. Zero filler, and the core action is front-loaded before any conditions.

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

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

With an output schema present, return values need not be explained, and annotations carry the safety profile. Purpose, triggering condition, identifiers, and the main failure mode are all covered for a simple two-parameter deletion 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 100%, so both parameters are fully documented in the schema, including the pointer to list-documents for finding the UUID. The description only restates that identification uses document_uuid plus signatory_email, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource: 'Remove a signatory from a document.' An agent can distinguish this from create-document-signatory and update-document-signatory by the verb alone. It stops short of explicitly contrasting with update-document-signatory, which handles the modify case, so it falls short of a 5.

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

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

The 'Use this tool when' block gives a concrete trigger (signatory added in error or should no longer sign) plus a hard precondition (they have not yet signed). This effectively encodes a when-not boundary. It never names an alternative tool or states what to do instead when the signatory has already signed.

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, but the description adds important behavioral context: the deletion is blocked while the field is referenced by a condition or metadata value. This is exactly the kind of dependency constraint an agent needs before invoking a destructive delete.

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 front-loaded with the purpose, then a short when-to-use bullet, then the critical deletion constraint and discovery hint. Every sentence earns its place.

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

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

For a two-parameter destructive delete with an output schema and clear annotations, the description covers purpose, usage condition, prerequisite, and discovery path. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both UUID parameters are already documented in the schema. The description repeats the get-template-info hint for finding a dynamic field UUID but adds no new syntax or semantic detail beyond the schema.

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

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

The description states a specific verb and resource: delete a dynamic field from a template. It clearly distinguishes this operation from sibling create/update/delete tools for other template components.

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

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

It explicitly says when to use the tool (user asks to remove a dynamic field) and gives a key precondition: fields referenced by conditions or metadata values cannot be deleted until references are removed. It also points to get-template-info as the discovery step.

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 mutation/safety profile is covered by structure. The description adds genuinely non-structured context: the referential dependency on signature blocks and the required deletion order. It does not say whether the deletion is permanent or recoverable, which keeps it short of a 5.

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

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

The destructive action and its scope come first, followed by a structured 'Use this tool when' block. The bulleted list holds a single item and the newline-wrapped sentences are a bit verbose, but nothing is misleading or wasted enough to penalize further.

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 delete tool with an output schema, the description covers everything an agent needs: the trigger, the discovery path (get-template-info), and the blocking dependency with its resolution tool. Return values are handled by the output schema, so 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 100%, so both UUIDs are already documented in the schema; the description's pointer to get-template-info largely restates the party_uuid field description. This is the baseline 3 — adequate, but no meaning is added 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 opening sentence states a specific verb and resource ('Delete a party from a template'), scoping it to templates as opposed to documents. An agent can distinguish it from delete-template-signature-block and delete-document-signatory from the text alone.

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

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

Explicitly enumerates the trigger condition ('The user explicitly asks to remove a party from a template') and a hard precondition: parties with bound signature blocks cannot be deleted and must be cleared first. It names the exact alternative (delete-template-signature-block) for that prerequisite.

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 safety profile is covered. The description adds genuinely non-obvious behavior beyond that: the party survives the operation and only the signing slot is removed, which prevents an agent from assuming a cascading delete. It stops short of saying whether the deletion is reversible or needs confirmation.

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 lines, front-loaded with the action, then the condition, then the key semantic caveat. Nothing is padded, and the most decision-relevant facts appear first.

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

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

An output schema exists, so return values need no explanation. With the action, trigger condition, side-effect scope, and UUID discovery path all present, an agent has everything needed to call this destructive tool correctly.

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

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

Schema coverage is 100% with both parameters described, including the discovery hint for signature_block_uuid, so the schema already carries the load. The description repeats the same discovery instruction rather than adding syntax, format, or scoping nuance, so baseline 3 applies.

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

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

The first sentence gives a specific verb+resource ('Delete a signature block from a template') and the follow-up clarifies it deletes a signing slot, not the party — which cleanly separates it from delete-template-party and update-template-signature-block in the sibling list.

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

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

It states an explicit triggering condition ('The user explicitly asks to remove a signature block') and routes the agent to get-template-info with include=["signature_blocks"] for discovery. It does not, however, name the closest alternative (delete-template-party / update-template-signature-block) as a when-not choice, so the exclusion side is implied rather than stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds real behavioral context beyond that: only the listed users are affected, other members remain attached, and a non-member UUID is a no-op (idempotency). It is silent on permission requirements and downstream effects, keeping it out of the top band.

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, front-loaded with the action, followed by a trigger condition and the key scope caveat. Every sentence carries information; the single-item bullet is slightly formal but costs almost nothing.

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, two-parameter operation with full schema coverage, annotations, and an output schema, the description covers scope and no-op semantics well. It omits any note on required permissions or side effects of removing a member, which would be the remaining useful detail.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description merely restates that account_user_uuids holds the users to remove. No format, ordering, or batch-size semantics are added. Baseline 3 is correct when the schema carries the burden.

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

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

The description gives a specific verb and resource ("Remove one or more account users from a team") that is instantly distinguishable from the inverse sibling attach-account-users-to-team. It does not explicitly name a sibling or scope boundary, so it stops just short of the top band.

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?

"Use this tool when: The user asks to remove people from a team" gives a concrete trigger condition, which is more than most definitions offer. It stops at 4 because it names no exclusion conditions or alternatives (e.g., how this differs from deleting a team or updating a team).

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 only declare the non-destructive, non-read-only, non-open-world profile. The description adds substantial context beyond that: it enumerates exactly what is inherited (content, parties, signatories, dynamic field values, metadata, attachments, teams, tags, document type, template link) and discloses the non-obvious stage behavior (always starts in draft; signing/done sources copy pre-signing content). This is the kind of behavioral detail an agent cannot infer from structured fields.

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 core action is front-loaded in the opening sentence, followed by usage triggers, then the inheritance/stage semantics, then remediation pointers. Every sentence earns its place 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?

With an output schema present, return values need no explanation, and the description covers the remaining gaps: when to use it, what gets copied, and the resulting stage. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters (including the name fallback to ' (copy)') are already documented in the schema. The description adds no parameter syntax or format information beyond what the schema provides, so the baseline 3 applies.

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

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

The first sentence states a specific verb ('Create') and resource ('a new draft document as a copy of an existing document'), and the intent is immediately distinguishable from sibling creation tools like create-document-from-scratch or create-document-from-template. An agent knows exactly what operation this performs 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 description gives explicit when-to-use scenarios ('reuse a previous contract as the starting point', 'start from an existing document rather than from a template') and names the follow-up alternative tools (update-document-party, update-document-dynamic-fields). It even draws the boundary against template-based creation, which is the closest sibling ambiguity.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description adds substantial context beyond that: the full list of what is copied (content, parties, signatories, signature blocks, dynamic fields, conditions, metadata, attachments, teams, tags, document type, locale, published state), the important non-destructive fact that existing documents stay linked to the source, and the published-state constraint on replace-template-content.

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

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

Front-loaded with the core action, then well-organized bullets and a compact paragraph on copy semantics followed by the post-duplication edit path. Dense but every sentence carries information; the last sentence on replace-template-content/unpublish is a slightly tangential prerequisite note but still actionable.

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 an output schema exists, return values need not be explained. With annotations plus a full parameter schema plus this description covering copy scope, non-destructive linkage behavior, and the follow-up workflow, an agent has everything needed to invoke and sequence the call correctly.

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

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

Schema description coverage is 100%, so both parameters (name, template_uuid) are already fully documented, including the ' (copy)' default for name and the list-templates pointer. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a new template as a copy of an existing template') and immediately scopes it against siblings like create-template-from-scratch ('rather than from scratch') and implicitly duplicate-document (templates vs documents). An agent can tell exactly what this 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?

Explicit 'Use this tool when' bullets give the trigger conditions (duplicating/copying a template, building a jurisdiction or business-line variant, starting from an existing template). It goes further and routes the agent onward to a named alternative workflow — update-template-party, update-template-dynamic-field, replace-template-content — and flags the prerequisite/unpublish step.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior: case-insensitive matching, most-recently-created-first ordering, and a hard result cap with advice to narrow the query.

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

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

Front-loaded purpose followed by scannable bullets and a returns note; every sentence carries distinct information with no 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?

An output schema exists so return shape need not be explained, and the description still covers ordering and the result cap. It is close to complete for a small filtered-search tool, with only explicit exclusion guidance missing.

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

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

Schema description coverage is 100%, so the query and limit parameters are already documented with min/max and case-sensitivity. The description reinforces name matching and the cap but adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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

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

The opening sentence names a specific verb (Search) and resource (the account's automations) with the match dimension (by name). An agent can distinguish this scanning tool from list-documents and the various create/update/delete 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?

Two explicit 'use this tool when' bullets give concrete triggers, including the downstream need for a UUID to filter list-documents. There is no explicit when-not guidance, but no sibling tool competes for the same purpose, so routing risk is low.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: fields searched, the two-word firstname+lastname rule, and the important constraint that results are capped and de-duplicated by name with a recommendation to narrow the query. It stops short of describing pagination or ordering, so a 4 rather than a 5.

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

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

Front-loads the purpose in one sentence, then uses a short bulleted usage block and a final paragraph on search semantics. Every sentence carries information, though the bullet list format is slightly more fragmented than a tight prose description would be.

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 values need no explanation, and the description covers the remaining agent-relevant questions: what is searched, how multi-word queries are interpreted, why results may be missing (capping/de-duplication), and what to do about it. Complete for a read-only lookup tool with full schema coverage.

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% – both 'query' and 'limit' are fully documented in the schema, including the min-3-character rule, case-insensitivity and the 25 cap. The description restates much of the same matching semantics rather than adding new syntax or format guidance, so the baseline 3 applies.

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

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

States a specific verb and resource ('Search the account's document users') and immediately scopes it with a parenthetical definition that separates document users (people with access to documents) from the account users and external parties covered by sibling tools like list-account-users and find-external-parties.

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?

Has an explicit 'Use this tool when:' block naming two concrete triggers (needing a name to filter list-documents by document user, and searching for matching document users), which names the downstream tool the results feed into. Nothing about when to reach for this versus the other find/list siblings is 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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value beyond them: results are capped and de-duplicated by name, and the agent is told to narrow the query or try list-account-parties if nothing is found. It does not discuss failure/empty-result semantics beyond that fallback, keeping it out of the top band.

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

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

Front-loaded with the core action, then disambiguation, then usage bullets, then a fallback note — a logical ordering with no wasted framing. It runs somewhat long and restates the account-party contrast twice, which keeps it from a 5.

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 two-parameter read-only lookup with an output schema and full annotation coverage, the description supplies everything an agent needs: what it searches, what it excludes, the cap on results, and which sibling to try next. No behavioral or routing question is left open.

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% for both parameters (query and limit, including min/max lengths), so the schema already carries the detail. The description only adds that matching is against the underlying entity_name field, which is marginally useful but largely duplicative. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Search the account's external parties ... by name') and immediately contrasts it with the sibling list-account-parties. An agent can tell exactly what this returns and how it differs from the nearest alternative without opening any schema.

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

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

Provides an explicit 'Use this tool when' list (need a party name to filter list-documents; want to find matching parties) plus a when-not rule with a named alternative (phrasing like 'our'/'we' means an account party, use list-account-parties). It even prescribes a fallback order before concluding a party does not exist.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the description is not the sole carrier of safety context. It adds genuine behavior beyond that: result ordering (most recently created first), a hard result cap, and the remediation advice to narrow the query. It stops short of describing auth requirements or pagination, which keeps it out of the top score.

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

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

Front-loads the one-line purpose, then uses scannable bullets for usage and a short paragraph for return behavior. Slightly redundant between the opening line and the second bullet, but there is no filler or repetition of schema fields.

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-shape explanation is not required, yet the description still supplies the ordering and cap semantics that matter for interpreting results. For a two-parameter read-only search, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, with both query (case-insensitive, min 3 chars, max 255) and limit (default/max 25) fully documented in the schema. The description only restates 'matched against import names' at a high level, adding no syntax or semantic detail beyond the schema – the baseline of 3 is correct.

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

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

States a specific verb (Search) and resource (account's imports) with the matching field (by name). It also distinguishes itself from list-documents by explaining the UUID hand-off, so an agent can tell the two apart without reading 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 'use this tool when' bullets name the two concrete triggering scenarios, including the downstream chaining case (getting an import UUID to filter list-documents). When-to-use is unambiguous.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by enumerating what kind of data the account reports (locale, signature settings, industry, company size, department). It does not mention authentication or rate limits, but for a low-risk read-only tool this is a minor gap.

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 first sentence front-loads the purpose, followed by a tightly scoped bullet list of use cases and a final routing note. Every sentence earns its place, with no redundant 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?

An output schema exists, so the description need not explain return values. Combined with the clear purpose, usage conditions, sibling distinction, and zero-parameter schema, the definition gives the agent everything needed to invoke it correctly.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly does not invent parameter semantics, and the empty schema is 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?

The description states a specific verb and resource: retrieving information about the current fynk account. It explicitly distinguishes itself from the sibling tool get-user-info, telling the agent exactly which resource each returns. An agent can select correctly 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?

It provides explicit when-to-use conditions: before tailoring a response with account defaults, or when tailoring guidance using the account's self-reported business details. It also names the alternative (get-user-info) and the condition that selects it, leaving no routing ambiguity.

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

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

Annotations already establish read-only, non-destructive, closed-world behavior. The description adds substantial extra context: the default returned sections, workflow_state semantics and how to relay them, the parties-vs-signatories distinction, and the nuanced meaning of dynamic_field_visibility including inactive-condition fields.

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

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

The purpose is front-loaded, but the description is very long and dense for a three-parameter tool. Several passages, especially the dynamic_field_visibility explanation, are expanded well beyond what is needed to select and invoke 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?

An output schema exists, so the description need not explain return values. It nevertheless provides the cross-tool routing, default-section behavior, and interpretation guidance needed to use this complex single-document tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds meaning by framing include as a cost-control mechanism, listing the default sections, and clarifying that dynamic_field_visibility has no effect unless dynamic_fields is among the returned sections.

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

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

States a specific verb and resource ('Gets information about a document') and immediately distinguishes the single-document scope from the list-documents sibling for multi-document needs. An agent can identify the tool's role 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?

Gives explicit when-to-use conditions (you have a document UUID and need more details) and when-not/alternative guidance (avoid calling once per document; use list-documents with filter_document_uuids and include_metadata for several documents). It also explains how include and dynamic_field_visibility should be applied.

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/destructiveHint=false/openWorldHint=false, and the description adds genuinely non-obvious behavior: the return is a plain-text URL and the URL is short-lived, with the instruction to re-fetch on expiry. That expiry/refresh semantics is real added value not present in structured fields.

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

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

Front-loaded with the core action, then a short bulleted usage block, then return-format and expiry notes. Tight overall; the two bullets partially restate the opening sentence, costing a little density.

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

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

For a single-parameter read tool with no output schema, the description covers what it returns (plain-text URL), the key operational caveat (short-lived, re-fetch), and when to reach for it. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the single document_uuid parameter is fully documented in the schema (including the pointer to list-documents for discovery). The description adds no further parameter meaning, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Get a download URL for the latest revision of a document as a PDF'), and the 'latest revision'/'as a PDF' scoping distinguishes it implicitly from read tools like get-document-info and upload tools like create-document-pdf-upload-url. It never names a sibling explicitly, so it just misses the top band.

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?

A dedicated 'Use this tool when' block gives two concrete triggers (user wants to download the current state as PDF; need a shareable PDF link for review). Clear positive guidance, but there are no exclusions and no named alternatives for adjacent cases such as wanting document metadata.

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 it as a safe, read-only, closed-world operation, and the description adds substantial context beyond them: the data-* attribute vocabulary, read-only clause numbering, empty reference tags (images, dynamic tables, vote blocks) whose contents live outside the HTML and are lost if dropped, legacy signature-block normalization on write-back, and the PDF-template failure mode.

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

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

Purpose and when-to-use are front-loaded, then the node-encoding details follow in a logical order. It is long, but nearly every sentence describes a parsing or write-back rule the agent needs; only the per-node examples edge toward 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?

An output schema exists, yet the description still supplies the interpretive rules an agent needs to manipulate the returned HTML safely (which attributes target nodes, which tags must be copied verbatim, alignment defaults). Nothing required to call it correctly or use its result is missing.

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

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

Schema coverage is 100% for the single template_uuid parameter, so the baseline is 3. The description adds meaningful qualifying semantics for that parameter — the template must have a prosemirror_data content type or the call errors — which the schema does not express.

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

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

States a specific verb and resource: returns a template's content serialised as HTML. It is clearly distinguishable from sibling get-template-info (metadata) and replace-template-content (write), and even cross-references get-template-info for ref_uuid lookups, so an agent can route without opening other 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?

Provides an explicit 'use this tool when' list (read/navigate content, understand structure before editing) plus a hard eligibility rule: only prosemirror_data templates, errors for PDF templates. It lacks an explicit 'do not use this when...' exclusion list and does not name replace-template-content as the write counterpart, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond that: the default set of sections returned when include is omitted, and the selective-fetch cost model that avoids pulling the whole template. This is meaningful beyond structured fields.

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

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

Front-loaded with the core action, then structured 'Use this tool when' bullets and a sentence on include behavior. Slightly verbose, with the include/defaults idea repeated across two paragraphs, but every sentence remains useful and there is no filler.

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

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

An output schema exists, so return-value enumeration is not required in the description. Within that, the description fully covers default vs. selective section retrieval and the identity fields always returned, leaving nothing an agent needs before calling the 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 100%, so both parameters are already documented, and the schema itself explains that include selects exact sections and lists the defaults. The description largely reiterates the schema's include semantics rather than adding new meaning, so the baseline 3 is appropriate.

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

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

States a specific verb (gets information) and resource (a template), and elaborates that the response covers identity, parties, teams, description and signing settings. This sufficiently distinguishes it from siblings like get-template-html (content) and list-templates (enumerate). An agent can identify its role 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?

Provides explicit when-to-use guidance with a concrete example ('when you want to create a document from the template and need to know which parties, dynamic fields... are available'), which is genuinely helpful context. It lacks explicit exclusions or alternatives (e.g. vs get-template-html), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and an output schema exists, so the safety and return-shape burden is largely carried by structured data. The description adds only that the result carries identity fields, with no notes on auth requirements or caching. Adequate but thin given how little it adds 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?

Short and front-loaded: the verb+resource leads, then the when-to-use bullet, then the sibling redirect. The 'who the current user is' bullet mildly restates the opening sentence, a small redundancy that keeps it from a 5.

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 lookup with full annotation coverage and an output schema, nothing material is missing: the agent knows what it returns, when to call it, and which sibling to prefer instead.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; per the rubric this earns the baseline of 4. The description correctly implies a no-argument call by describing identity context rather than inputs.

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

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

States a specific verb and resource ('Get information about the current user') and enumerates the returned fields (email, locale, roles), which makes the scope concrete. It explicitly distinguishes itself from the sibling get-account-info, so an agent can route between the two without opening either schema.

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

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

Provides an explicit 'Use this tool when' trigger (needing to know who the current user is before tailoring a response) and names the alternative (get-account-info) with the condition that selects it. Both when-to-use and when-to-use-something-else are covered.

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=true. The description adds permission-precondition context, which is useful, but it never explains why a join is flagged destructive or what state change/permissions result from joining. With annotations covering the safety profile, a 3 fits.

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

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

Purpose is front-loaded in one sentence, followed by two scannable bullets. Minor redundancy in the repeated 'You need to make changes to a document, but...' phrasing, but no real waste.

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 values need no explanation. The when-to-use preconditions are covered; the only remaining gap is the unexplained destructiveHint flag, which is a minor omission for a single-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 100% and the schema itself routes the agent to list-documents for obtaining the UUID. The description adds no parameter semantics beyond that, so the baseline 3 applies.

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

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

States a specific verb + resource ('Joins a document as a collaborator'), which is clearer than a bare tautology. It does not explicitly distinguish itself from siblings like update-document or create-document-party, but the 'as a collaborator' framing clarifies the effect.

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

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

Provides an explicit "Use this tool when" block with two concrete preconditions (no 'document user' yet, or existing 'document user' lacks change permission). It gives clear triggering context but never names an alternative tool or a when-not-to-use case.

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 readOnly/openWorld/destructive. The description adds real behavioral context beyond them: default returns only active types, and removing a system type deactivates rather than deletes it, with filter_state to surface those. It does not mention auth or rate-limit behavior, so it stops short of a 5.

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

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

Front-loaded with the core purpose, then structured into a bulleted when-to-use block and a return-format/state note. Dense but every sentence carries information; nothing is redundant.

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

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

Although an output schema exists, the description still clarifies the default return shape (uuid and name) and cross-references list-account-metadata for the inverse relationship. An agent has everything needed to call 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 coverage is 100%, so the baseline is 3. The description goes further by explaining what include=["details"] actually yields (description + recognition prompt) and tying filter_state to real scenarios like reactivation, adding meaning beyond the schema enum text.

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

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

States a specific verb and resource ('Get a list of the document types available in the account') and immediately scopes it ('fynk's system-provided types plus any custom types'). This clearly distinguishes it from siblings like create-account-document-type, delete-account-document-type, and list-account-metadata.

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

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

Provides an explicit 'Use this tool when' list with three concrete triggers, including the alternative workflow (needing a UUID to filter list-documents). It also explains the filter_state cases (reactivating a deactivated type), leaving little to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds conceptual context about what the fields represent but does not disclose operational traits such as pagination, rate limits, or whether inactive fields are included.

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, front-loaded with the core action, and uses a clear bulleted 'Use this tool when' structure. Every sentence adds value without repetition 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 zero-parameter, read-only list tool with rich annotations and an output schema, the description supplies everything needed: purpose, usage conditions, and the relationship to downstream tools. No critical information is missing, and return values are appropriately left 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 tool takes no parameters, so the baseline is 4 per the rubric. The description adds no parameter-specific information, which is appropriate since there are no parameters to describe.

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

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

States a specific verb ('Get a list') and resource ('metadata fields available in the account'), and distinguishes its role from get-document-info and list-documents. An agent can tell this tool apart from sibling list tools like list-account-tags or list-account-document-types 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?

Provides an explicit 'Use this tool when:' section with two concrete scenarios, including the need to know metadata names before referencing them in other tools. However, it does not state when not to use this tool or name an alternative to call instead.

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