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

With no annotations provided, the description carries the full behavioral burden. It discloses that the tool acquires an edit lock, returns content/hash/lock_token, and that concurrent callers receive code=locked. It does not disclose TTL expiration, release obligations, or authorization requirements, but the core behavioral traits are clearly communicated.

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

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

The description is compact: two sentences front-load the core action and return values. The note about another agent receiving code=locked is useful but slightly tangential; overall the text is appropriately concise for the behavior it conveys.

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

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

The description covers the main behavior and return contract, and an output schema exists, so return-value documentation is not the primary gap. However, with no annotations and 0% parameter schema coverage, important call-time details such as how ttl_seconds or share_token affect checkout behavior are missing, leaving the definition incomplete for a tool with four parameters.

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

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

Schema description coverage is 0% and the description provides no parameter-level semantics. The four parameters (doc_id, agent_id, share_token, ttl_seconds) are entirely undocumented in the prose, so an agent has no additional guidance about what these values mean or how to supply them correctly.

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

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

The description states a specific action ('Adquire lock de edição') and names the expected return payload (content + hash + lock_token), making the tool's purpose clear. It implicitly distinguishes itself from read-only siblings like doc_read/doc_get by emphasizing the lock acquisition, though it does not name an alternative explicitly.

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

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

The description implies that the tool should be used when an edit lock is needed, and the note about another agent receiving code=locked conveys exclusivity. However, it does not provide explicit when-to-use versus when-not-to-use guidance, nor does it suggest alternatives such as doc_read or doc_get for non-locking reads.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses that the action creates a permanent grant, indicating persistence and mutation, but it does not clarify whether the share_token is consumed, whether the grant is reversible, or what side effects occur beyond the permanent grant.

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

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

The description is a single concise sentence with no filler. It front-loads the core action and states the outcome, though it is terse and could include more detail without becoming verbose.

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

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

For a simple two-parameter tool with an output schema, the description covers the essential action and result. However, it leaves agent_id semantics unclear and offers no context on when claiming is appropriate, which is relevant given the large sibling group of document tools.

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

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

Schema description coverage is 0%, so the description must compensate. It explains share_token as the token being redeemed, but it does not explain agent_id, which has a default of "" and likely refers to the current agent. The phrase 'for this agent' hints at it but does not map cleanly to the parameter.

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

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

The description states a specific action: redeems a share_token and writes a permanent grant for the agent. This clearly distinguishes it from sibling tools like doc_share/doc_unshare, though it does not explicitly name an alternative.

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

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

No guidance is given on when to use this tool versus siblings. The description does not mention prerequisites, such as having received a share token, or when doc_share/doc_unshare might be more appropriate.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does disclose the critical lock-release behavior and the expected_hash requirement, which signal optimistic concurrency. However, it does not state what happens on hash mismatch, whether the write is destructive, or how errors are surfaced.

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, each earning its place: the core action, the required credentials, and the lock-release behavior. It is front-loaded and free of fluff, making it easy for an agent to parse quickly.

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

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

Despite having an output schema, the tool has 8 parameters and zero annotation support. The description is too sparse to fully guide an agent on safe invocation: it omits content encoding options, optional metadata parameters, and the exact relationship to doc_checkout/doc_release. The lock semantics help, but the overall picture remains incomplete.

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

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

Schema description coverage is 0%, so the description must compensate for the 8 parameters. It only explains lock_token, expected_hash, and keep_lock. It leaves doc_id, content, content_base64, message, and agent_id unexplained, especially the important distinction between content and content_base64.

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

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

The description clearly states the operation: 'Grava a edição do checkout' (saves the checkout edit), using a specific verb and resource. It also distinguishes itself from siblings by explaining the lock_token/expected_hash requirement and lock-release behavior, which separates it from doc_checkout, doc_release, and doc_update.

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 prerequisites: lock_token and expected_hash must be present, and it explains the keep_lock behavior. This strongly implies it should be used after a checkout, when the agent holds a lock and wants to persist edits. It does not explicitly name alternatives or exclusions, so it is clear but not fully exhaustive.

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

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

With no annotations, the description carries the behavioral disclosure burden. It usefully reveals that the default doc_id is the hash of the initial content and that the document is editable, adding value beyond a bare 'create' statement. However, it omits other behavioral aspects such as how visibility, tags, or base64 content are handled.

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

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

The description is one tight sentence with no filler. It front-loads the action ('Cria um documento editável') and adds the most important behavioral detail about doc_id afterward.

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 8 parameters, 0% schema coverage, and no annotations, this description is too sparse to fully support correct invocation. It covers the creation intent and doc_id default, but lacks guidance on required inputs, parameter relationships, and usage boundaries among the many document sibling tools.

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

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

Schema description coverage is 0%, so the description needs to compensate. It provides meaningful semantics for doc_id ('default is the hash of the initial content'), but leaves the other seven parameters—title, content, mime, tags, visibility, agent_id, content_base64—unexplained.

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

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

The description states a clear action and resource: 'Cria um documento editável' (creates an editable document), giving a specific verb and object. It is clearly a creation tool, though it does not explicitly distinguish itself from siblings like doc_put or doc_fork.

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

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

There is no guidance on when to use this tool versus alternatives. The hint 'compartilhe esse id' (share this id) implies a follow-up action but does not clarify when doc_create should be preferred over doc_put, doc_update, or other document tools.

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

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

No annotations are provided, so the description carries the full burden. It explains the basic input modes (doc_id or hash) and that the hash is immutable, but it does not disclose whether this creates a draft, whether the forked document is linked to the original, how visibility works, or what side effects occur. It also doesn't clarify behavior when both doc_id and hash are provided or neither.

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

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

The description is one short sentence, which is concise and front-loads the core idea. It earns its place but omits necessary detail; still, conciseness itself is handled well.

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 5 optional-looking parameters, 0% schema coverage, no annotations, and an output schema that is not described in prose, the description is too thin. An agent cannot determine which parameters are mutually exclusive, what the new document's default state is, or what the output schema contains. Sibling tools like doc_create and doc_update suggest related but distinct workflows, and this description does not clarify how fork differs.

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

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

Schema description coverage is 0% and there are 5 parameters with no descriptions. The description only mentions doc_id and hash, and vaguely 'a partir de' implying one or the other. It does not explain title, agent_id, or visibility semantics, and it does not specify precedence between doc_id and hash or required combinations. The description falls well short of compensating for the schema's complete lack of parameter documentation.

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

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

The description states a specific verb ('Cria um documento novo') and a resource (a new document), and it names both input sources (doc_id or hash imutável). This is clear enough to distinguish it from other doc_ siblings like doc_get or doc_create, though it doesn't explicitly contrast with doc_create.

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

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

The description implies a use case: forking an existing document by doc_id or hash. It does not explicitly state when to use fork vs create, nor does it mention that no parameters are required. With 0% schema description coverage and no annotations, an agent gets limited guidance on choosing this over doc_create or doc_copy alternatives.

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

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

With no annotations, the description carries the full behavioral burden. It clearly signals a read operation ('Lê') and adds important semantic context: the snapshot is immutable and the tool does not follow the document pointer. This goes beyond a generic 'get' description.

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

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

Two short sentences, front-loaded with the core purpose and immediately followed by the key behavioral caveat. Every word earns its place with no redundancy.

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

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

With an output schema present and only two parameters, the description covers the essential behavior and distinguishing semantics well. The only notable gap is the undocumented purpose of 'agent_id', but since it is optional and has a default, the tool remains callable.

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

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

Schema description coverage is 0%, so the description must compensate. It adds useful meaning to the required 'hash' parameter by explaining that a unique prefix is acceptable. However, the optional 'agent_id' parameter remains completely unexplained, leaving some ambiguity.

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 (Lê) and resource (snapshot imutável) with a clear addressing method (hash or unique prefix). It also distinguishes itself from sibling document tools by explicitly noting it does not follow the document pointer.

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

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

The description implies the tool should be used when the caller has a hash or unique prefix and wants an immutable snapshot, and it tells the agent this is not for following the current document pointer. However, it does not explicitly name alternatives like doc_read or state when to prefer them.

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

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

With no annotations, the description carries the behavioral burden, but it only reveals the output shape: hash ← parent_hash and the committing agent. It does not disclose whether the chain is ordered newest-first, how limit truncates results, whether agent_id filters the chain, or whether the current version is 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 a single compact sentence with no filler. The core concept is front-loaded, though it is somewhat cryptic and would benefit from a few precise clarifying phrases.

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

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

For a tool with 3 parameters, no annotations, and 0% parameter coverage, this description is too sparse. It identifies the return concept but omits ordering, limit behavior, agent_id filtering semantics, and any usage context. The presence of an output schema helps, but it is not visible here and the description does not stand on its own.

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

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

Schema description coverage is 0%, so the description must compensate. It only hints at the agent-related parameter by mentioning 'o agente que commitou cada uma'. It does not explain doc_id, limit, or agent_id semantics, leaving the agent to infer them from parameter names alone.

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

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

The description states the resource (version chain of a document) and the key content: hash values, parent links, and the committing agent. This distinguishes it from tools like doc_info or doc_get, though it lacks an explicit verb such as 'retrieve' or '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?

There is no guidance about when to prefer doc_history over related tools such as doc_info, doc_read, or doc_commit. The description implies a history retrieval tool, but it does not explain ordering, limits, filtering, or when this data would be more relevant than similar alternatives.

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

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

With no annotations, the description carries the behavioral disclosure burden. It clearly indicates the tool is metadata-only and excludes content, suggesting a read-only operation, but it does not mention authentication needs, side effects, or error behavior.

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

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

The description is a single concise sentence that front-loads the core purpose and key metadata fields. Every word adds value and there is no redundant 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?

The description is enough for selecting the tool, but not for fully invoking it correctly: optional parameters agent_id and share_token are unexplained, and there is no guidance on when to provide them. The output schema helps with return values, but parameter context is missing.

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

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

Schema description coverage is 0%, and the description provides no explanation of doc_id, agent_id, or share_token. The agent must infer their meaning from names and defaults alone, which is insufficient.

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

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

The description clearly states that the tool returns document metadata without the content, listing the specific fields (current hash, version, lock, owner). This is specific and distinguishes it from content-returning siblings like doc_read and doc_get.

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

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

The description implies the tool should be used when metadata is needed and content is not, but it does not explicitly state when to use it over alternatives or mention any exclusions. The guidance is contextual rather than direct.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. The verb 'Lista' and the phrase 'visíveis para este agente' convey a read-only, agent-scoped operation, which is useful. However, it does not mention ordering, pagination behavior, or whether results include full content or metadata, leaving some behavioral ambiguity.

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

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

The description is two short sentences with no wasted words. The main action and scope are front-loaded, and the query filter detail is placed second. 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 described. However, the missing agent_id semantics and the lack of guidance on choosing doc_list over doc_search leave the description only minimally viable for correct tool selection and invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It meaningfully explains query's filtering semantics (title, tags, hash, preview), but it does not explain agent_id, whose purpose is non-obvious, and it adds no value for limit beyond what the parameter name and default imply. This is insufficient coverage for a schema with no descriptions.

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

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

The description states a specific verb and resource: 'Lista documentos' (lists documents) with the scope 'visíveis para este agente' (visible to this agent). It also specifies that query filters titles, tags, hash, and preview, which clarifies the tool's functionality. However, it does not explicitly distinguish doc_list from sibling tools like doc_search or doc_info, so it stops short of a 5.

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

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

No guidance is provided about when to use doc_list versus alternatives such as doc_search, doc_get, or doc_info. The description only explains what the tool does, not the conditions under which it should be preferred. Given the large sibling set, this is a significant gap.

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

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

With no annotations, the description carries the full burden and does reveal key traits: the write action, immutability, SHA-256 output, and deterministic hashing. However, it does not disclose parameter interaction (e.g., content vs content_base64), behavior on duplicate content, permissions, or failure modes.

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

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

Two short sentences with no filler; the primary action and key property are front-loaded. Every word contributes to the core behavior.

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

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

The tool has four optional parameters but zero parameter documentation, and the description does not explain how to invoke it correctly, such as how to supply the blob or what mime and agent_id do. The output schema may describe the return value, but the input side is incomplete for reliable agent use.

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

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

Schema description coverage is 0% and the description adds no meaning to mime, content, agent_id, or content_base64. An agent cannot determine which parameter to populate or whether content and content_base64 are alternatives from the 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?

The description uses a specific verb and resource: it stores an immutable blob and returns its SHA-256 hash. The content-addressable property (same content -> same hash) clearly distinguishes it from mutable document tools like doc_update/doc_create and from ftp_put.

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

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

The description implies a use case for content-addressed immutable blobs but never states when to prefer doc_put over siblings such as doc_create, doc_update, or ftp_put. There are no exclusions or conditions, so an agent has to infer selection from the tool name and vague semantics.

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

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

No annotations are provided, so the description carries the behavioral transparency burden. It clearly signals a read-only operation and adds context about identifying content via doc_id or hash, as well as share_token support. Yet it does not disclose what happens when both doc_id and hash are supplied, or how agent_id and include_content affect behavior.

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

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

The description is one short sentence with no filler. It front-loads the core purpose and then adds the accepted identifier modes. This is concise and well structured.

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

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

While the output schema reduces the need to describe return values, the description is incomplete for choosing and using this tool correctly among many siblings. It omits when to use doc_read versus doc_get, identifier precedence rules, the meaning of agent_id, and the behavior of include_content. For a tool with no annotations and 0% schema parameter coverage, this is a notable gap.

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

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

Schema description coverage is 0%, so the description must compensate by explaining parameters. It adds meaning for doc_id, hash, and share_token, but leaves agent_id and include_content unexplained. The compensation is only partial, hence a mid-range score 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 uses a specific verb and resource: it reads the current version of a document (doc_id) or a blob (hash). It also mentions share_token access, which helps clarify the tool's scope. However, it does not explicitly distinguish itself from sibling tools like doc_get or doc_info.

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

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

The description gives no guidance on when to prefer doc_read over doc_get, doc_info, or other related tools. It implies a read operation but provides no exclusionary or alternative-based usage instructions.

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

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

With no annotations, the description carries the full burden. It does disclose the key behavioral trait: the lock is released without saving changes, which is valuable. However, it does not mention permissions, idempotency, failure behavior, or what happens to uncommitted changes beyond the implied abandonment.

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

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

The description is a single, focused sentence with no filler. It front-loads the core action and adds the key nuance in an efficient parenthetical. Every word contributes meaning.

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

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

The tool is simple and has an output schema, but the description omits important lifecycle context: how the lock_token relates to doc_checkout, whether the release is idempotent, and what happens to edits made during the checkout. It is adequate for a basic understanding but not fully self-contained.

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

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

Schema description coverage is 0%, so the description should compensate by explaining the parameters. It only hints at 'lock' and 'checkout' but does not explain what lock_token is, how to obtain it, or the role of doc_id and agent_id. An agent would need external context to correctly supply these parameters.

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

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

The description names a specific action ('libera o lock') and resource (the document lock), and clarifies the key distinction from a normal commit: it does not save ('sem gravar'). This clearly differentiates it from sibling tools like doc_commit and doc_checkout.

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 parenthetical 'checkout abandonado' implies this tool is for abandoning a checkout and releasing its lock, but it never explicitly states when to use this tool versus doc_commit or when not to use it. The usage context is implied rather than stated.

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

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

With no annotations, the description must disclose behavioral traits, but it only repeats the search purpose. It does not mention read-only behavior, pagination, response structure, authentication, or other operational details.

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

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

The description is a single efficient sentence with no filler, and the key action is front-loaded. It is appropriately concise, though it sacrifices useful detail for brevity.

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

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

For a tool with no annotations, three parameters, and an output schema, the description is too thin. It lacks usage context, alternative tool routing, and parameter semantics for limit and agent_id, making it only minimally sufficient for an agent to select and invoke correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It partially explains the query parameter by listing searchable fields, but it gives no meaning for limit or agent_id, leaving two of three parameters unexplained.

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

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

The description clearly states the tool searches documents by title, tags, hash, or preview snippet, giving a specific verb and resource. It does not explicitly differentiate from sibling tools like doc_list, doc_get, or doc_read, 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?

No guidance is provided about when to use this tool versus alternatives such as doc_list, doc_get, or doc_find. The description implies search usage through the query fields, but it offers no explicit context, prerequisites, or exclusion conditions.

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

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

With no annotations, the description carries the full burden. It does disclose the sharing-for-editing behavior and the two outcomes (grant vs share_token), which is useful. But it omits important behavioral context such as required permissions, reversibility, interaction with TTL/max_uses, or what happens to existing shares.

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

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

The description is a single front-loaded sentence with no filler. It states the core action first and then the two modes, making it easy to scan.

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

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

For a tool with six parameters, no annotations, and no schema-level descriptions, this definition is too sparse. While the output schema may cover return values, the semantics of sharing, grant, token generation, and the remaining parameters are under-specified for reliable invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It only adds meaning to to_agent_id, while role, agent_id, max_uses, ttl_seconds, and doc_id remain unexplained. This is insufficient for an agent to correctly configure the tool across its six parameters.

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

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

The description gives a specific action ('Compartilha para edição' - shares for editing) on a document resource and clearly identifies two modes: grant via to_agent_id, or share_token without it. However, it does not explicitly distinguish itself from related sibling tools like doc_unshare or doc_claim.

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

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

There is no guidance on when to use this tool versus alternatives, and no exclusions or conditions are stated. The only usage hint is the conditional behavior of to_agent_id, but that addresses parameter usage rather than tool selection.

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

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

With no annotations, the description carries the behavioral burden and does disclose an important conditional side effect: if neither grant nor share_token is provided, all tokens of the document are revoked. However, it does not mention irreversibility, authorization requirements, or how agent_id and from_agent_id affect the revocation behavior.

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

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

The description is a single compact sentence that front-loads the core action and condition. It earns its place, though the extreme brevity causes ambiguity around 'grant' and 'os dois'.

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

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

For a tool with four parameters, no annotations, and no schema description coverage, the description is not complete enough. It does convey the main conditional behavior, but omits parameter mappings, usage context, and detailed effects, so an agent would struggle to invoke it correctly in many cases.

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

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

Schema description coverage is 0%, so the description must compensate, but it only clarifies share_token and the all-token fallback. It never explains agent_id or from_agent_id, and uses the term 'grant' which does not appear in the schema, leaving the agent unable to reliably map parameters for the intended operation.

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

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

The description states a concrete action ('revoga') and resource ('grant ou share_token'), and explains the fallback of revoking all document tokens. This distinguishes it from doc_share, but 'grant' is not a named parameter in the schema, creating some ambiguity about what exactly is being revoked.

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

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

No guidance is given about when to use this tool versus alternatives like doc_release or doc_claim. The description implies it is the inverse of doc_share, but it does not explicitly state conditions, prerequisites, or exclusions.

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

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

No annotations are provided, so the description carries the full transparency burden. It discloses a key behavior: conditional compare-and-swap and a conflict error code. It does not cover lock semantics, permissions, or effects on content/metadata, leaving significant mutation behavior undocumented.

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

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

Two short sentences, front-loaded with the action and failure mode; no filler or redundancy. It earns a high conciseness score despite being minimal.

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?

Output schema covers return values, but the tool has 11 parameters, no annotations, and a CAS concurrency model. Missing context about how content is supplied, whether locks/share tokens are required, and what happens to unspecified fields makes invocation ambiguous beyond the one explained failure case.

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

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

Schema description coverage is 0% across 11 parameters, and the description only adds semantics for expected_hash, which must match the current hash. Parameters like content vs content_base64, lock_token, share_token, keep_lock, and agent_id receive no behavioral explanation, so parameter semantics are insufficient.

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

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

The description states a clear action ('Atualiza' = updates) on a document resource and adds a distinguishing mechanism, compare-and-swap. This separates it from doc_create and doc_put, though it does not explicitly say 'existing document' or define the update scope.

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?

CAS semantics imply this tool is for optimistic concurrent updates: the caller supplies expected_hash and failure means another write happened. However, there is no explicit when/when-not guidance against doc_put, doc_checkout/doc_commit, or other siblings, so the agent must infer the 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?

No annotations are provided, so the description alone must disclose behavior. It only says 'copies file within the same access_hash' and does not explain whether the destination is overwritten, whether directories are created, whether it is atomic, whether it copies permissions/timestamps, or what access_hash means operationally. The description is not misleading, but it leaves critical behavioral traits undisclosed.

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

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

The description is a single short sentence that front-loads the core action ('Copia arquivo') and scope. It contains no filler or redundant words. However, it is so brief that it under-specifies important details, which slightly lowers the score from a perfect 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?

With no annotations and no parameter descriptions, the agent lacks context about the access_hash, path formats, overwrite behavior, and relationship to sibling operations. An output schema exists, so return values are covered, but the operational context needed to call this tool correctly is largely absent. More detail about when and how to use it is required.

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

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

Schema description coverage is 0%, so the description must compensate by explaining parameters. It does not mention src, dst, access_hash, or agent_id at all. While src and dst are somewhat self-explanatory, access_hash and agent_id are opaque. The description adds no value beyond the parameter names in the schema, so the agent has to guess meanings from context.

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

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

The description states a specific action ('Copies file') and a resource (file) with a scope constraint ('within the same access_hash'). It is clearly a copy operation, distinguishable at a high level from ftp_mv (move) and ftp_put/get (external transfer). However, it does not explicitly call out sibling tools or explain the access_hash concept, so it does not fully distinguish itself.

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

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

The phrase 'dentro do mesmo access_hash' implicitly tells the agent this tool is for copies where source and destination share the same access_hash, implying it is not for cross-hash copies. But there is no explicit guidance on when to choose ftp_cp over siblings like ftp_mv or ftp_put, nor any 'when not to use' statement. Usage context is implied rather than stated.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It indicates a read-only search over a scoped file set, but it does not mention auth requirements, limits, failure behavior, or confirm that the operation makes no modifications. For a tool with no annotation safety signals, this is a notable 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 description is a single compact sentence with no filler, and the verb and object are front-loaded. It is easy to parse, though the list of search modes is somewhat packed and could be structured more explicitly without much extra 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?

An output schema exists, so return-value documentation is not necessary here. The core search semantics are present, but with no annotations and 0% schema coverage, the definition leaves optional parameters, sibling differentiation, and behavioral expectations underexplained. It is minimally viable but not complete.

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

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

Schema description coverage is 0%, so the description must compensate. It does add meaning for the core parameters: query can be a path, content hash, or metadata, and access_hash scopes the search. However, limit and agent_id are left entirely unexplained, leaving partial coverage only.

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

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

The description states a specific action ('Busca arquivos') and resource ('deste access_hash'), and clarifies the search modes: path, content hash, or metadata. This makes it reasonably distinct from siblings like ftp_ls or ftp_get, though it does not explicitly name an alternative.

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

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

The usage context is implied: use this tool to search files belonging to an access_hash by query criteria. However, there is no explicit guidance about when to prefer ftp_find over ftp_ls, ftp_meta, or other siblings, and no exclusions are stated.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal an important behavior — SHA-256 recalculation — and hints at an auth requirement, but it does not describe side effects, failure behavior, or what happens when expected_hash is supplied. This is useful but not rich context.

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

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

The description is three short sentences, front-loads the main action, and every sentence contributes either purpose, a prerequisite, or behavioral context. There is no filler or redundancy.

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

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

The description covers the basic action, a key prerequisite, and a notable behavior, and an output schema exists. However, it leaves parameter semantics largely unexplained and does not clarify its relationship to ftp_verify or the doc_get family, so an agent may not reliably select it in ambiguous cases.

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

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

Schema description coverage is 0%, so the description must compensate for the five parameters. It adds meaning only for access_hash and indirectly for expected_hash via 'Recalcula SHA-256'; path, agent_id, and include_content are left entirely to inference. This is a meaningful gap.

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

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

The description states a clear verb and resource ('Baixa arquivo' = downloads a file), so the core purpose is obvious. It does not explicitly differentiate itself from sibling retrieval tools like doc_get or ftp_verify, so it stops short of a 5.

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

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

The description gives a concrete prerequisite: the access_hash must be the same one registered/used in the put operation. However, it does not specify when to choose ftp_get over alternatives such as ftp_verify or doc_get, nor does it mention any conditions that should prevent use.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses the admin-password gating and data scoping, which is valuable. However, it doesn't mention error behavior, whether the operation is read-only (implied by 'lista'), or any side effects.

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

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

A single, efficient sentence in Portuguese that front-loads the core action ('Lista hashes') and then adds the conditional scope. Every word earns its place with no filler.

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

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

For a two-parameter tool with an output schema, the description captures the main behavioral rule but leaves agent_id semantics and error details unaddressed. It is adequate for a simple listing tool but not fully complete given the lack of annotations and zero 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 0%, so the description must compensate. It explains the role of admin_password (enables full listing) and implicitly references agent scoping, but agent_id is left undefined and there is no explicit mapping from parameters to behavior.

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

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

The description states a specific action and resource: 'Lista hashes' (lists hashes). It also clarifies the scope by describing admin vs. non-admin behavior. It doesn't explicitly name sibling tools, but the conditional distinction helps differentiate it from related FTP tools.

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

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

The description gives clear invocation context: with the admin password it lists all hashes, without it only those created by the calling agent. This tells the agent when each mode applies, though it does not mention alternative tools or explicit when-not-to-use cases.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It does disclose that the output consists of files with content hashes and metadata, which is useful. However, it does not state whether the operation is read-only, whether it works recursively, or how path/query parameters affect behavior.

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

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

The description is two short sentences with no filler. The primary action is front-loaded in the first sentence, and the second sentence adds relevant output detail. 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?

The description is adequate for a simple listing command, and an output schema exists so return values need not be fully restated. However, the missing explanations for path and query behavior, plus the lack of alternatives, leave meaningful gaps for an agent choosing and invoking the 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 0%, so the description must compensate by explaining parameters. It only references access_hash ('deste access_hash') and ignores path, query, and agent_id entirely. The schema provides defaults and names, but not semantics for how these parameters shape the listing.

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

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

The description uses a specific verb ('Lista') and resource ('o diretório deste access_hash'), making it clear that this tool lists a directory associated with an access hash. This distinguishes it from sibling tools like ftp_get, ftp_put, and ftp_find because 'ls' is explicitly a directory-listing operation.

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

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

The description implies the tool is for listing directory contents, so an agent can infer a basic use case. However, it gives no explicit guidance about when to prefer ftp_ls over alternatives like ftp_find or ftp_stat, and no exclusions or context-dependent selection criteria.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It communicates that only metadata is extracted, that access_hash is required, and that resolution happens by path or content hash. It does not explain behavior when both path and hash are supplied, what happens on missing metadata, or any side effects, but the core read-only metadata boundary is present.

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

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

The description is two short sentences with no filler. The most important constraint ('only extracted metadata') is front-loaded, followed by the required credential and the two lookup modes. 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?

Despite having an output schema, the description is incomplete for a 4-parameter tool with zero schema descriptions. It leaves agent_id undefined, does not clarify how path, hash, and agent_id relate, and does not differentiate itself from ftp_stat among the siblings. An agent would likely need additional probing to invoke this correctly in ambiguous cases.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions path, content hash, and access_hash conceptually, but it never names the parameters explicitly, does not explain agent_id at all, and gives no format or precedence rules for path versus hash. This is a notable gap for a 4-parameter tool.

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

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

The Portuguese description states 'Só metadados extraídos' (only extracted metadata), which clearly indicates the tool returns metadata rather than file content. It also identifies the key lookup modes: by path or by content hash. It does not explicitly contrast with siblings like ftp_get or ftp_stat, but the 'only metadata' scope gives a clear resource and operation.

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

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

The description provides useful context: access_hash is required and lookups happen by path or content hash. However, it does not explicitly say when to use this tool instead of ftp_get, ftp_stat, or ftp_hashes, and it does not give any exclusion or alternative guidance. Usage is implied rather than stated.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It says the tool creates a directory but does not disclose idempotency, error behavior, permission requirements, whether parent directories are created, or any side effects.

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

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

The description is a single short sentence with no filler words, making it easy to parse. However, it is concise to the point of being terse and vague in places.

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

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

This is a mutation tool with three parameters and no annotations, yet the description provides only the minimal verb+object statement. It lacks operational context such as required setup, failure modes, and relationship to the FTP registration workflow, even though an output schema exists.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It only hints that access_hash relates to a 'hash cadastrado' and does not clarify path format, path interpretation, or how to obtain access_hash.

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

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

The description states a clear action ('Cria diretório') and resource ('diretório neste hash cadastrado'), matching the tool name ftp_mkdir. It is distinguishable from siblings like ftp_put or ftp_rm, though 'hash cadastrado' is somewhat ambiguous.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites stated, and no mention of what 'hash cadastrado' means operationally. Usage context is only implied by the tool name and the brief description.

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

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

No annotations are provided, so the description carries the full burden for behavioral disclosure. It indicates a mutating move/rename operation and the same-access_hash constraint, but it does not disclose overwrite behavior, effects on existing files, permission requirements, or what happens when the destination already exists.

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 very concise and front-loads the core action. However, it is so terse that it omits useful context that would fit naturally in one or two additional sentences.

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

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

Given no annotations, 0% schema description coverage, and a mutating operation, the description is incomplete. It communicates the basic operation and the same-access_hash constraint, but leaves out parameter semantics, behavioral effects, and usage guidance needed for an agent to confidently invoke 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 0%, so the description must compensate. It does not define the meaning of src, dst, access_hash, or optional agent_id. While the action 'move/rename' implies src is the source and dst is the destination, the description adds little beyond what the parameter names already suggest.

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

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

The description states the primary action ('Move/renomeia path') and the scope ('dentro do mesmo access_hash'), making it clear this is a move/rename operation on paths. It is distinguishable from siblings like ftp_cp (copy) and ftp_rm (remove), though it does not explicitly name them.

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

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

The description gives an implicit scope constraint ('dentro do mesmo access_hash') but does not explain when to use this tool versus alternatives such as ftp_cp. It also does not describe prerequisites, error conditions, or whether cross-access_hash moves are supported or unsupported.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does add non-obvious behaviors: it requires a registered access hash, writes SHA-256, checks disk space, and extracts metadata. However, it omits key behavioral details for an upload/write tool, such as whether existing files are overwritten, how content vs content_base64 is handled, or what happens on failure.

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

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

The description is extremely concise: three short clauses with no filler. The primary action 'Envia arquivo' is front-loaded, and each additional clause adds distinct information about prerequisites or side effects.

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

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

Given 9 parameters, zero annotations, and no parameter descriptions in the schema, the description is not complete enough to reliably invoke the tool. It lacks guidance on how to provide file content, when to use content versus content_base64, overwrite semantics, and the meaning of visibility/agent_id/message. The output schema reduces the need to describe return values, but the input-side gaps remain significant.

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

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

Schema description coverage is 0%, so the description must compensate for the 9 parameters. It mentions access_hash and implies SHA-256 relates to expected_hash, but it does not clarify the meaning or purpose of content, content_base64, mime, visibility, message, agent_id, or path. The description adds only minimal parameter meaning beyond the schema.

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

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

The description opens with 'Envia arquivo' (sends file), which clearly identifies the verb and resource. It also adds a meaningful distinction via the access_hash requirement and SHA-256/disk-check behavior, though it does not explicitly contrast with sibling tools like ftp_get or doc_put.

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 states a clear prerequisite: a registered access_hash from ftp_register is required. However, it does not explain when to prefer ftp_put over alternatives, nor does it describe exclusions or fallback conditions. The usage context is implied rather than explicit.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose that this is an admin-only creation action requiring the admin password and that the resulting hash is used by clients. However, it does not explain side effects, whether hashes can be revoked, how permissions in the schema affect behavior, or what the response contains.

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

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

The description is a single compact sentence that front-loads the admin requirement and states the core purpose without wasted words. Every clause adds relevant 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?

This is an 8-parameter tool with no schema-level descriptions, no annotations, and a very terse description. The description does not explain most parameters, required inputs beyond admin_password, return format, or interaction with revocation/list tools, so it is not complete enough for reliable invocation.

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

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

Schema description coverage is 0%, so the description must compensate, but it only hints at 'hash' and 'put/get'. The fields label, secret, agent_id, ttl_seconds, can_get, and can_put are left unexplained, leaving the agent to guess their purpose and constraints.

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

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

The description clearly states that the tool registers an access_hash, names the admin-only audience, and explains that clients will use the generated hash for put/get operations. This distinguishes it from siblings like ftp_revoke and ftp_hashes even without comparing schemas.

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

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

The description gives clear context: only admins should call it, and an admin password is required. It does not explicitly name alternatives or say when not to use it, but the admin-scoped purpose and the put/get usage are enough to guide selection.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It openly states the tool mutates state by revoking a hash and that subsequent put/get calls with that hash fail, which is meaningful side-effect information. It does not discuss reversibility or failure modes, but the core behavior is clearly disclosed.

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

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

The description is two short sentences with action and scope front-loaded. Every clause adds useful information, and there is no filler or repetition of obvious schema details.

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

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

The description is adequate for the core action and its effect, and an output schema exists so return-value details are not required. However, with no annotations and zero schema coverage, the missing parameter semantics and the lack of alternative/usage routing keep it from being fully self-contained.

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

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

Schema description coverage is 0%, and the description only indirectly refers to access_hash as 'hash'. The required admin_password and the optional agent_id are not explained at all. Because the schema provides no descriptions and the tool description does not compensate, parameter semantics are weak.

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

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

The description names a concrete action ('revoga um hash cadastrado') and a specific resource, and it adds the observable consequence that put/get operations fail afterward. This clearly distinguishes it from sibling tools such as ftp_register and ftp_hashes.

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 'Admin:' prefix conveys an authorization context, and the effect on put/get implies this is for invalidating an existing hash. However, it never explicitly states when to prefer this tool over alternatives like ftp_register or ftp_hashes, nor does it mention prerequisites beyond admin status.

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

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

With no annotations, the description carries the full burden of disclosing behavior. It does disclose the destructive action and the important recursive requirement for non-empty directories. However, it does not mention permanence, failure behavior, or permission requirements, leaving some behavioral gaps.

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

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

Two short sentences with no filler. The core action is front-loaded and the recursive condition is stated immediately after, making it easy to scan and act on.

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

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

The description covers the primary action and the key recursive condition, and an output schema exists to describe return values. Still, for a destructive tool with no annotations and sparse parameter documentation, it lacks edge-case behavior and guidance relative to sibling FTP tools.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It clarifies recursive behavior and hints at the access_hash scope, but it does not explain path format or the agent_id parameter, so the compensation is only partial.

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

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

The description states a specific action ('Remove') and a clear resource ('arquivo ou diretório') scoped to 'neste hash'. This unambiguous deletion purpose distinguishes it from siblings like ftp_ls, ftp_put, ftp_mv, and ftp_cp.

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

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

The description provides clear context: use it to delete a file or directory, and sets the condition that non-empty folders require recursive=true. It does not explicitly name alternatives or state when not to use it, but the core usage 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?

With no annotations, the description must carry the behavioral burden. It communicates that the call is non-destructive and returns metadata without content, which is useful. However, it does not disclose behavior around missing paths, unregistered hashes, permission requirements, or directory versus file handling.

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

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

A single concise sentence that leads with the resource and result, and adds a content-exclusion qualifier. There is no filler; the structure is easy to parse quickly.

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

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

The tool is a simple stat operation and an output schema is present, so return values need not be spelled out. Still, the description lacks any indication of how this tool relates to ftp_meta/ftp_ls and omits parameter details needed for correct invocation in ambiguous cases.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It implicitly maps 'path' and 'hash cadastrado' to the path and access_hash parameters, but it does not explain path format, agent_id usage, or how access_hash should be supplied.

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 that the tool returns metadata for a path under a registered hash, explicitly excluding content. This gives a specific verb/resource and helps distinguish it from content-returning tools like ftp_get, but it does not differentiate it from the similarly named sibling ftp_meta.

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

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

No guidance is given about when to choose ftp_stat over alternatives such as ftp_meta, ftp_ls, or ftp_find. The description only defines the operation; it never states when it is appropriate or when another tool should be preferred.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does add one meaningful behavioral signal—'Disco alterado → tampered'—which tells the agent that modified content yields a tampered result. However, it does not disclose side effects, read-only behavior, or error/response behavior beyond this ternary signal.

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

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

The description is compact and front-loaded: the core action appears first, followed by the access requirement and the tampered condition. Every fragment earns some place, though the telegraphic style sacrifices some precision.

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

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

The tool has four parameters, only one required, zero schema descriptions, and no annotations. The description leaves the roles of hash, path, and agent_id entirely to inference, and while an output schema exists, the description still lacks enough context for reliable invocation in all expected cases.

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

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

Schema description coverage is 0%, so the description should compensate for the four undocumented parameters. It only mentions access_hash, which duplicates the schema's required field, leaving hash, path, and agent_id semantically unexplained. The phrase 'SHA-256 no disco' loosely implies hash and disk path, but this is weak support.

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

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

The description states a specific action: recalculating the SHA-256 on disk, which conveys the core verification purpose. It is clearer than the tool name alone and hints at its role among the ftp_* siblings, though the phrasing is terse and lacks an explicit 'compare and report' statement.

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

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

No guidance is given about when to use ftp_verify versus alternatives like ftp_hashes or ftp_stat. The only contextual hint is 'Exige access_hash', but that is a parameter requirement rather than a usage decision rule.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does reveal what information the tool reports (data_dir, files, registered hashes, agent identity), which gives some idea of its diagnostic nature. However, it does not explicitly state that it is a read-only operation, mention permissions, or describe any side effects.

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

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

The description is a single compact phrase with no filler words, and the core subject 'Saúde do FTP' is front-loaded. It is efficient, though it borders on under-specification rather than truly concise 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?

For a simple health-check tool with an output schema and no required parameters, the description provides a reasonable high-level summary of what is inspected. The main gap is the undocumented agent_id parameter, which could confuse an agent about whether or how to supply it. Overall, it is minimally adequate but not fully complete.

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

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

Schema description coverage is 0% and the description does not explain the agent_id parameter. The phrase 'identidade deste agente' hints at an identity-related concept, which weakly connects to the Agent Id parameter, but it never clarifies whether agent_id selects a different agent, scopes the health report, or is even relevant to the output.

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

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

The description identifies the resource (FTP) and the nature of the tool (health/status), and lists the included contents: data_dir, files, registered hashes, and agent identity. It is distinguishable from sibling operation tools like ftp_put, ftp_get, and ftp_rm because it signals a diagnostic overview rather than a file operation, though it lacks an explicit verb.

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

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

No guidance is given about when to use this tool versus alternatives, nor are any exclusions or preconditions stated. The name 'health' implies a status check, but the description does not explain scenarios where this is the appropriate choice or when another sibling like ftp_hashes or ftp_stat might be better.

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