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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so 'READ-ONLY. Returns data, changes nothing.' is pure duplication of structured data. The description adds no behavioral context beyond the annotations — no auth requirements, rate limits, or notes on what the compact flag alters in practice.

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?

Very short and front-loaded, but the opening two sentences are redundant with the annotations, so they do not earn their place. Given five parameters and a compact/resolve versioning model, the definition is under-specified rather than admirably tight.

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

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

An output schema exists, so return values need not be explained, and the schema itself covers the pofid/documents_id either-or constraint. What is missing is any prose about sibling selection (text_get for OCR text, search for discovery), which is exactly the gap the description should fill at this complexity level.

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

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

Schema description coverage is 100% and every parameter (pofid, compact, resolve, documents_id, include_pages_ocr) carries a detailed schema description including the POFID encoding caveat and the alternates. The description adds nothing new about parameters, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Get document identity, processing state and compact trust.' This is more informative than the title alone and tells the agent the payload class (identity/metadata, not content). However, it never distinguishes itself from siblings like po_documents_text_get or po_documents_search, leaving that routing work to the schema.

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

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

The description contains no when-to-use guidance, no prerequisites, and no named alternatives — unlike the sibling routing hint buried in the schema ('otherwise use po_documents_text_get'). An agent gets no textual signal about when this tool is the right choice versus text_get or search.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=true, so "READ-ONLY. Returns data, changes nothing." merely restates structured data and earns no extra credit. The description adds no behavioral context beyond that, such as result caps, latency trade-offs, or the partial-result semantics exposed by the schema.

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

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

Three short sentences, front-loaded with the safety profile and followed by the capability statement; nothing is padded. However, the brevity is arguably achieved by omitting content the agent needs, which limits the credit.

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 needn't be re-explained, but for a 20-parameter search tool the description supplies none of the routing context that matters most: which sibling to pick, how search modes differ operationally, or when pagination/budget settings should be touched. It is far too thin for the tool's complexity.

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 all 20 parameters (including enums, defaults and normalization rules) are fully documented in the schema itself. The description contributes no parameter meaning of its own, so the baseline 3 for high coverage applies.

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

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

States a specific verb and resource ("Search documents") plus the matching surfaces (keyword, filename, metadata), so the agent knows it's a retrieval tool rather than a fetch-one tool. It does not differentiate from siblings such as po_documents_get, po_mcp_tools_search or po_documents_text_get, and it undersells the tool's actual reach (semantic/hybrid modes, date and signature filters).

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 when-to-use guidance: nothing distinguishes this from po_documents_get (single document fetch), po_documents_text_get, or po_mcp_tools_search. No prerequisites, no exclusions, and no mention of when to prefer filename_only or a specific search_mode, despite 20 parameters implying several distinct usage patterns.

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?

'READ-ONLY. Returns data, changes nothing' merely restates the readOnlyHint/destructiveHint annotations already supplied, earning no credit. The only additive content is the cross-reference to po_documents_update_index for indexing fields, which is navigation rather than disclosure of this tool's behavior (e.g., match semantics, result limits).

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

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

Three short sentences, front-loaded with the read-only guarantee, with no filler. The final sentence about indexing fields is somewhat tangential to searching and could be mistaken for a parameter hint, but overall the structure is tight.

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

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

An output schema exists, so return values need not be explained. The description covers safety posture, when to search, and a follow-on tool reference; the remaining gap is how to interpret or narrow a returned inner tool_id, which is minor for a single-parameter lookup.

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

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

Schema description coverage is 100% and the single `query` parameter is fully documented in the schema as a natural-language query for an inner tool_id. The description adds no further syntactic or semantic detail beyond that, 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 verb+resource pair is specific: 'Search the tool catalog' tells the agent this searches MCP tool definitions, not documents (po_documents_search) or tags. The name po_mcp_tools_search plus the description make it distinguishable from all siblings, though it never explicitly contrasts itself with po_mcp_tools_schema or po_mcp_tools_call_read.

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?

'Search the tool catalog before saying an action is unavailable' gives a clear trigger condition for calling this tool, which is unusually actionable. It also points to po_mcp_tools_call_write / po_documents_update_index for the follow-on indexing operation, though it does not state when to prefer this search over po_mcp_tools_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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so 'READ-ONLY. Returns data, changes nothing.' largely restates structured data. The one piece of added value is the token-scoping phrase 'accessible to this token,' which hints at permission-filtered results, but pagination, deleted-item handling and result shape are left to schema/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, front-loaded with the operation and its safety profile. It is compact, though the first two sentences duplicate each other and the annotations, so a small amount of space is not earning its place.

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

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

With an output schema present and 100% schema coverage across nine parameters, the description need not explain return values. However, it offers no guidance on how the listing behaves (pagination defaults, filtering combinations) and duplicates annotation content instead of filling the usage gap, leaving it only minimally complete.

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

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

Schema description coverage is 100% and all nine parameters (skip/take aliases, limit/offset, query/search, detail_level, workspace_id, include_deleted) are documented in the schema itself. The description adds no parameter-level meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states a specific verb and resource: 'List workspaces accessible to this token.' An agent immediately knows this is a listing/read operation on workspaces. It does not, however, differentiate from any sibling (though none of the listed siblings are workspace-listers, so the risk is low).

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 when-to-use guidance, no mention of alternatives, and no conditions under which this tool should be preferred over, e.g., po_mcp_tools_search. 'READ-ONLY. Returns data, changes nothing.' is a safety statement, not usage guidance.

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