PaperOffice AI

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

The 'WRITES DATA' warning duplicates the readOnlyHint=false annotation, and 'Creates or changes data' is vague about effects. It does add useful behavior beyond annotations ('output is always PDF; optional idempotency_key makes retries safe'), but it omits side-effect context like charges or workspace AI-DMS processing that the schema hints at.

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

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

The description is short and front-loaded with the write warning. However, 'WRITES DATA' and 'Creates or changes data in the workspace' are redundant, so it is not perfectly economical.

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

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

For a 14-parameter write tool, the description is minimal, but the input schema is exhaustive and an output schema exists. The description provides the core purpose, output format, and retry safety, which is enough to select and invoke the tool correctly when combined with the schema.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in detail. The description adds only general context about content format and retries, not new parameter-level meaning.

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

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

The description uses a specific verb and resource: 'Create a PDF document from Markdown or HTML content in a workspace.' It also states output is always PDF, which clearly distinguishes it from sibling document tools like po_documents_search or po_documents_upload_url_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?

It gives a clear use context: creating a PDF from Markdown/HTML and using an idempotency_key for safe retries. It does not explicitly name alternatives or give exclusion criteria, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description repeats 'READ-ONLY' and 'changes nothing'. It adds scope context ('not files') but no new behavioral details such as pagination, limits, or response format beyond what annotations already convey.

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

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

The description is short and front-loaded with the safety profile, but 'READ-ONLY' and 'Returns data, changes nothing' are redundant with each other and with annotations. It is still concise and every remaining sentence earns its place.

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

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

For a single-parameter read-only list tool with full annotation coverage, the description plus schema fully explain what the tool returns, what it excludes, and how to list files instead. No critical information needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema documents workspace_id fully. The parameter description adds semantic value by clarifying that it returns only document folders/collections and not files, which goes beyond the bare 'Workspace ID' label and helps the agent set correct expectations.

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: 'List document folders (not files)'. It clearly distinguishes the tool's scope from file-related siblings, and the input schema reinforces this by noting it returns 'document_folders (document folders/collections) only' and points to po_documents_search for files.

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 schema parameter description explicitly says 'Use po_documents_search with query="*" to list documents', naming the exact alternative and condition. This gives the agent unambiguous when-to-use guidance versus the main sibling tool.

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

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

The description reinforces the annotations by explicitly stating 'READ-ONLY' and 'changes nothing', matching readOnlyHint, idempotentHint, and destructiveHint. It adds little beyond those annotations, and it does not disclose versioning behavior or other potential gotchas, though the output schema covers return shape.

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

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

The description is two short, front-loaded fragments with the most important behavioral signal ('READ-ONLY. Returns data, changes nothing') placed first. There is no filler, and every phrase pulls its weight.

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

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

The tool is well-covered overall because the detailed input schema and output schema carry versioning, OCR, and return-shape information, while the description states the read-only contract. The narrative is slightly incomplete at the selection level because it doesn't connect this tool to po_documents_text_get or explain where pofid comes from, though the parameter descriptions partially compensate.

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

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

Schema description coverage is 100%, and the parameter descriptions are already rich, covering pofid encoding, exact versus latest resolution, and pages_ocr behavior. The main description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

The description starts with 'READ-ONLY. Returns data, changes nothing' and names the specific resource and information returned: document identity, processing state, and compact trust. This clearly distinguishes it as a metadata/details getter rather than a write, search, or OCR-text retrieval tool.

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 conveys that this is for read-only retrieval of document details, which gives clear context. However, it does not explicitly say when not to use it or name alternatives such as po_documents_text_get or po_documents_search; routing hints are largely left to the parameter descriptions.

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

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

Annotations already carry readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description restates this as 'READ-ONLY. Returns data, changes nothing.' It adds no behavioral context beyond the annotations, but it is consistent with them and clearly signals the safety profile.

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, front-loading the critical read-only signal. Every phrase earns its place and the search scope is stated immediately.

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

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

The tool is complex with 20 parameters, but the schema is exceptionally detailed and an output schema exists, so the minimal description is sufficient for correct invocation. The only missing layer is prose-level guidance about when to prefer this over generic or sibling search 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 100%, so the input schema already documents all 20 parameters including defaults, enums, constraints, and usage notes. The tool description itself adds no parameter-level meaning, so the baseline 3 applies.

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

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

The description states a precise action (search) on a clear resource (documents in DMS) and lists supported search dimensions (keyword, filename, metadata). It is distinct enough from siblings like po_documents_get or po_documents_text_get, though it does not explicitly contrast itself with them.

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

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

The description implies this is the search entry point ('Search documents by...'), but it gives no explicit when-to-use/when-not-to-use guidance or alternative routing. Correct usage relies mostly on schema hints such as po_workspaces_list for workspace selection and filename_only for name-based lookups.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds explicit 'READ-ONLY. Returns data, changes nothing,' which reinforces the safety profile. It does not disclose details like pagination or ordering, but for a read-only list tool this is adequate.

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

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

The description is short and front-loaded with the most important behavioral note ('READ-ONLY'), followed by a clear one-line purpose. Every sentence earns its place, though it could be even more compact.

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 list tool with rich annotations and full schema coverage, the description is mostly complete. It does not describe what the returned tag objects look like or whether the list is paginated, but given no output schema and low complexity, this is a minor gap.

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

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

Schema description coverage is 100%, so the schema already explains both parameters. The description adds no semantic value beyond what properties provide. The baseline of 3 applies because the schema carries the full parameter burden.

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

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

The description states a clear verb and resource: 'List tags in a workspace' is specific enough to convey the operation. It does not explicitly differentiate from sibling tools like po_documents_folders_list or po_documents_get, but the read-only tag-listing purpose is unambiguous.

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

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

The description implies usage for listing tags but gives no explicit guidance on when to choose this tool over siblings or when it is not appropriate. The alternative identifiers (pofid vs documents_id) are mentioned in the schema but not framed as usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description's 'READ-ONLY... changes nothing' largely repeats those. The phrase 'existing OCR/fulltext' adds a mild signal that no OCR generation is triggered, but missing-content/error behavior is not 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?

Extremely compact and appropriately front-loaded: the read-only warning comes first, followed by a single clarifying sentence about what is returned. No space is wasted restating 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?

For a low-complexity read-only tool, the description plus fully documented parameters and strong annotation coverage is nearly sufficient. A note about missing OCR/not-found behavior or response structure would improve it, but the absence is not blocking.

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

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

Schema description coverage is 100%, including the pofid/documents_id either-or requirement and the format enum/default. The description adds no parameter-specific meaning, so the baseline 3 applies.

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

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

States a specific operation — reading existing OCR/fulltext for a document — with the read-only nature front-loaded. This clearly differentiates it from siblings like po_documents_get and po_documents_search, which concern metadata/search rather than text extraction.

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?

Implies use when an agent needs existing document OCR or fulltext content, but never explicitly says when to prefer this tool over po_documents_get or po_documents_search. No exclusions or sibling routing are provided.

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

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

Annotations already declare readOnlyHint=false, and the description reinforces this with 'WRITES DATA'. It adds the specific behavior of returning a presigned PUT URL, which is helpful. However, it does not disclose that the URL is temporary or that the actual file upload must be performed separately via a subsequent PUT request—a critical behavioral detail for correct usage. The description is consistent with annotations but does not go far beyond them.

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

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

The description is short but contains redundancy: 'WRITES DATA' and 'Creates or changes data in the workspace' say essentially the same thing. The essential information—'Register an upload slot and return a presigned PUT URL'—is present but not front-loaded; it appears after the redundant write warning. A more concise version would merge the write hints and lead with the core action.

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 only three optional parameters and no output schema, the description covers the basic purpose and return value (a presigned PUT URL). However, it omits practical details that an agent would need, such as the URL's expiration, the need to perform a PUT request separately, or any size/type restrictions. These omissions could lead to incorrect invocation, so the description is only minimally complete.

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

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

The input schema provides complete descriptions for all three parameters (filename, file_name, content_type), including aliases and defaults. The tool description adds no additional meaning or constraints beyond what the schema already documents. With 100% schema coverage, the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: to register an upload slot and return a presigned PUT URL. It uses specific verbs and a resource, distinguishing it from siblings like po_documents_create_from_content (which creates from content directly) and po_documents_get (which retrieves documents). The action is unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives such as po_documents_create_from_content or other upload methods. It does not mention prerequisites (e.g., needing a workspace or folder context) or scenarios where a presigned URL is the appropriate choice. An agent is left to infer usage from the tool name and sibling list.

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

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

The description adds 'May reach systems outside PaperOffice' and the 'WRITES DATA' warning, which align with annotations (readOnlyHint=false, openWorldHint=true). However, it does not provide deeper context like the async workflow or job polling, which are covered in the schema. The bar is lowered due to annotations, so the added external-reach note earns a 3.

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 concise, with two sentences, and front-loads the 'WRITES DATA' warning before stating the purpose. While the 'WRITES DATA. Creates or changes data in the workspace.' prefix is somewhat generic and redundant with annotations, it is not verbose. The core purpose is efficiently stated.

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 10 parameters and no output schema, the description is too sparse. It does not explain how the agent should handle the job lifecycle (e.g., when to poll, what the result looks like, or how to interpret job_id vs. immediate result). The schema covers parameters, but the description leaves out critical workflow guidance for a job-based tool, making it incomplete for correct invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add meaning beyond what the schema already provides for parameters. The schema details client_wait, async_only, idp_collection, etc., so the description adds no additional semantic value for 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 clearly states the tool's action: 'Extract invoice fields from a document (starts a job).' This specifies a specific verb, resource (invoice fields), and the asynchronous nature. It distinguishes itself from siblings like po_documents_text_get by focusing on invoice extraction rather than generic text retrieval.

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

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

The description implies usage for extracting invoice fields but does not explicitly mention when to use this tool over alternatives. It lacks exclusions or references to sibling tools. The parameter schema mentions localized alternatives, but that's not in the main description, so the agent gets no explicit guidance on selecting this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's 'READ-ONLY... changes nothing' adds no new information. It does add the 'async' context, but doesn't disclose polling semantics, error behavior, or result lifecycle.

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 read-only warning, no filler. Every word earns its place.

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

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

For a single-parameter read-only polling tool with an output schema and rich annotations, the description covers the essential operation. The only notable gap is not stating how job_id is obtained or that polling may need to be repeated until completion.

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 restates that the tool operates 'by job_id' without explaining where the ID comes from, its format, or its relationship to async job creation. This adds minimal semantic value over the schema's property name.

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

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

The description uses a specific verb ('Poll') and resource ('async PaperOffice job'), and identifies the key identifier (job_id). It clearly conveys the tool's function, though it does not differentiate from sibling tools by name.

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

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

The phrase 'Poll an async PaperOffice job' implies the usage context (after launching an async job), but the description does not explicitly state when to use this tool versus alternatives, nor does it mention any 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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value beyond those by stating writes are rejected and that the tool may reach systems outside PaperOffice, which is important behavioral context. No contradiction with annotations.

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

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

The description is two short sentences, front-loads the most critical information (READ-ONLY, returns data, changes nothing), and every clause earns its place: write rejection, alternate tool, and external-reach warning.

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?

Annotations and output schema cover the safety profile and return shape, so the description does not need to repeat those. It covers read-only behavior, write rejection, and external reach. It could be more complete by pointing to sibling tools like po_mcp_tools_search or po_mcp_tools_schema for discovering valid tool_ids, but it is mostly sufficient.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies tool_id as the read-only inner tool to execute, but the 'arguments' object is left entirely to inference; an agent is not told that arguments are passed through to the inner tool or how they should be shaped. This is a meaningful gap for a proxy tool.

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

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

The description uses a specific verb (execute) and resource (read-only inner tool_id), and clearly states it returns data and changes nothing. It also distinguishes itself from the write sibling by saying writes are rejected and to use call_write.

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

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

It explicitly states when the tool is appropriate: executing a read-only inner tool. It also gives a clear exclusion and alternative: 'Writes are rejected; use call_write,' which lets an agent route correctly without opening the sibling schema.

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

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

Annotations already provide readOnlyHint=false, openWorldHint=true, and destructiveHint=true. The description adds value beyond these by enumerating concrete risky operation classes (delete, revoke, cancel, send, activate retention) and disclosing a genuinely new trait — 'Not automatically undoable' — plus the confirmation-before-call requirement. No contradiction with annotations; the description's claims align with all three hints.

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?

Compact at roughly 52 words across four sentences, and the most critical information ('DESTRUCTIVE') is front-loaded in caps, followed by consequences and the confirmation requirement. Minor redundancy: 'reaches people outside this system' and 'May reach systems outside PaperOffice' communicate the same open-world trait twice.

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

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

For an open-world dynamic dispatcher with an unrestricted arguments object, the description covers the danger profile thoroughly but leaves operational gaps: how arguments should be shaped for a given tool_id, how to discover valid tool IDs (despite schema/search siblings existing), and the explicit read-vs-write split with call_read. An output schema exists, so return-value documentation is not the description's responsibility.

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

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

With 0% schema description coverage, the description carries the burden for both parameters, but only nominally addresses tool_id (it selects an inner tool in the connector universe, which is something beyond 'string'). The arguments parameter — a free-form passthrough object with additionalProperties — receives zero explanation, and there is no pointer to sibling tools po_mcp_tools_schema or po_mcp_tools_search for discovering valid tool_id values.

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

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

Description states a specific verb+resource: 'Execute any inner tool_id in this connector universe, including writes.' The title's '(writes allowed)' framing differentiates it from its read counterpart, po_mcp_tools_call_read, which appears directly in the sibling list. Clear overall, though the description body never names the read sibling explicitly.

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

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

The destructive framing ('Not automatically undoable — confirm intent first') implies this is for write operations requiring user confirmation, which is useful. However, there is no explicit routing guidance: it never states 'use po_mcp_tools_call_read for read-only calls' or gives when-not-to-use conditions. Usage context is implied by the title and danger warnings 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?

The description repeats the annotation profile ('READ-ONLY', 'changes nothing') but adds no new behavioral context beyond what readOnlyHint, idempotentHint, and destructiveHint already provide. There is no additional disclosure about errors, availability, or response structure.

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

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

The description is short and front-loads the read-only nature. However, 'Returns data, changes nothing' is partially redundant with 'READ-ONLY', so a slightly tighter wording could make every phrase earn its place.

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

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

For a single-parameter meta-tool with annotations and an output schema, the description adequately explains the tool's function. The main missing context is how to know which tool_id values are valid, but the sibling tool names and the parameter description give enough guidance for basic invocation.

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

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

Schema description coverage is 100% and the tool description merely echoes the tool_id parameter without adding format, examples, or constraints. It does not compensate beyond the schema, but it doesn't need to given the complete schema documentation.

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

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

The description states a specific verb ('Return') and resource ('full input schema for one inner tool_id'), and opens with READ-ONLY. It is clearly distinct from sibling tools, which are operational tools, since this is a schema-introspection meta-tool.

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: an agent needing the input schema for an inner tool would call this tool with that tool_id. However, there is no explicit statement about when to prefer this over sibling tools like po_mcp_tools_search, nor any mention of how to discover valid tool_id values.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces this with 'READ-ONLY' and 'changes nothing,' and adds meaningful behavioral detail: results are compact hits and tools are invoked indirectly via call_read/call_write. No contradiction with annotations.

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

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

Three short sentences, with the most important constraint (READ-ONLY) front-loaded. Every sentence carries meaning; no filler or redundant schema repetition beyond the intentional safety emphasis.

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

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

The tool has an output schema and full parameter documentation, so return values and parameters are already covered. The description provides the remaining essential context: read-only behavior, natural-language search, compact hits, and the call_read/call_write indirection.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context by explaining the query is a natural-language search for an inner tool_id, which complements the schema's parameter description and clarifies the tool's role.

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?

Clearly states a specific verb ('Search') and resource ('PaperOffice tool catalog'), with the key qualifier 'by natural language.' It distinguishes itself from document search siblings by targeting the tool catalog itself, not documents.

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

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

The description explains that the search returns compact hits and that inner tools run only through call_read or call_write, giving the agent a clear workflow. It does not explicitly name alternatives or exclusion conditions, but the intended usage is strongly implied and useful.

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

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

The description explicitly states 'READ-ONLY' and 'changes nothing', which reinforces the annotations (readOnlyHint, idempotentHint, destructiveHint). It adds useful context about token-scoped accessibility, but with annotations already covering the safety profile, the additional behavioral disclosure is modest.

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 most important behavioral trait ('READ-ONLY') is front-loaded, and the rest states the core action and scope efficiently.

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

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

Given the rich schema, output schema, and annotations, the description covers the essential context: read-only behavior, no mutation, and token-scoped accessibility. It does not need to explain return values or parameters because those are fully specified in structured fields.

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

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

Schema description coverage is 100%, so the schema fully documents all 9 parameters including pagination, filtering, detail level, and include_deleted. The tool description itself adds no parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('workspaces accessible to this token'), making the tool's purpose immediately clear. It also distinguishes the tool from document-focused siblings by scoping to workspaces and token accessibility.

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 clearly implies when to use this tool: when you need to enumerate workspaces available to the current token. There are no competing workspace-list siblings, so explicit exclusions are unnecessary, though it could have stated that this is the discovery entry point for workspace IDs.

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