probo-mcp

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

With readOnlyHint=false the annotation only says a write occurs; the description adds the crucial clarification that the write is local-only and ProBo is unmodified, plus that large files trigger a confirmation prompt. That is real context beyond the annotations, though overwrite behavior on repeat calls (idempotentHint=true) is left unexplained.

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 destination, followed by the scope constraint and the confirmation caveat. Nothing is wasted and nothing is buried.

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 (return location need not be described) and annotations cover the safety profile, so the description only needs the local-write clarification, which it provides. Minor gaps remain around repeat-download/overwrite behavior and where the download folder is configured.

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

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

Schema coverage is 100% and the single 'document' parameter is already documented as an id or attachment path, so the description adds no syntax or format detail beyond the schema. Baseline 3 applies when the schema carries the full 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?

States a specific verb (save) and resource (document) plus the destination (local download folder), which cleanly separates it from read_document/list_documents siblings that operate inside ProBo. It stops short of naming an alternative tool explicitly, so it is clear but not sibling-differentiating at the top level.

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 'nothing changes in ProBo' and 'Save ... to the local download folder' imply this is the tool for pulling a document to disk rather than reading it in place, but no when-to-use/when-not comparison against read_document or find_documents is given.

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

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

Goes beyond the annotations by disclosing cost and feedback behavior: it walks every folder, takes a few seconds, and reports progress as it goes. That latency expectation is genuinely useful for an agent deciding whether to call it. Missing is any note about match limits or what happens when nothing matches.

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 zero waste: scope and filters first, then the operational caveat. Nothing is buried or repeated.

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

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

An output schema exists, so return shape need not be explained, and the description covers scope, cost and progress reporting. Only minor gaps remain, such as result limits or behavior on an empty match set.

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 folder_id, name_contains and added_within_days are already documented with examples and constraints. The description restates the filter axes without adding syntax, combination or precedence guidance, so baseline 3 applies.

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

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

Names a specific verb (search) and resource (the whole document archive across all sub-folders) plus the filter axes: upload date and/or file name. That distinguishes it from a plain list or read tool, though it never names the siblings (list_documents, recent_documents) it most resembles.

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 scope phrase 'whole document archive (all sub-folders)' implies you reach for this when you need cross-folder lookup, but there is no explicit when-to-use statement, no exclusions, and no pointer to recent_documents or list_documents for cheaper narrower cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the return format ('as Markdown'), which is genuinely useful context, but says nothing about pagination, truncation, or missing-page 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?

A single tight sentence with no waste, front-loaded with the verb and resource. It is appropriately short for a one-parameter read tool, though it is arguably too terse to carry usage or parameter detail.

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 read tool with an output schema, the description needn't explain return values, so partial credit is warranted. However, the undocumented page_id and absent usage guidance leave an agent relying on the schema and sibling list to invoke it correctly.

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

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

Schema description coverage is 0% and the single required page_id parameter is completely undocumented in both schema and description. The description does not explain where a page_id comes from or what format it takes, so it fails to compensate for the coverage gap.

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

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

States a specific verb (Get) and resource (information page) plus the return format (Markdown), which separates it from the sibling list_info_pages. It doesn't distinguish itself from other content readers such as read_document or get_news, but the resource is clearly named.

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 the many sibling readers (read_document, get_news, get_message) or when not to use it. The only implied usage is 'you have a page_id', which is left to inference.

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

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

The note 'opening a thread may mark it as read in ProBo' is genuinely useful side-effect disclosure that annotations cannot express, but it conflicts with readOnlyHint=true (marking read mutates ProBo state) without acknowledging that tension. Otherwise no auth requirements, rate limits, or thread-size caveats are given.

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 action and output shape, followed by the caveat. No padding, though the trailing note could be tightened.

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-format explanation is rightly omitted, but the definition leaves the lone required parameter undocumented and provides no selection context against 12 sibling tools. Adequate but with clear gaps.

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

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

Only one parameter (message_id) exists and schema description coverage is 0%, so the schema contributes nothing beyond the field name. The description implies message_id selects a thread but adds no format, source, or where-to-obtain-it details, leaving the parameter semantics thin.

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

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

States a specific verb and resource with scope: 'Get a full message thread: every reply as Markdown, plus attachment paths.' This distinguishes it from list_messages, but the description never names the sibling explicitly, so the differentiation is implicit rather than stated.

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 prerequisites, and no routing to alternatives. The note about ProBo read-state is a side-effect warning, not usage guidance, so an agent must infer that this is the tool for a known message_id rather than a search/list 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, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds one genuinely useful behavioral fact beyond them, that the response bundles comments alongside the post content and renders as Markdown, but says nothing about not-found errors or auth requirements.

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

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

A single front-loaded sentence with zero filler that leads with the action and ends with the output format. Every word earns its place.

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

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

For a one-parameter read tool with a full annotation set and an output schema, the description covers enough to call it correctly. The remaining gap is minor: it does not point the agent to list_news as the source of valid news_id values.

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

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

Schema description coverage is 0%, so the description carries the burden for news_id, yet it says nothing about the parameter, such as where to obtain the ID or its format. 'News Id' in the schema is self-descriptive but the description adds no meaning beyond it.

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

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

States a specific verb (get), a specific resource (a news post), and even the return shape (content and comments as Markdown), so the singular 'a news post' implicitly contrasts with its sibling list_news. It never names that sibling explicitly, so differentiation is inferable rather than stated.

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 exclusion conditions, and no mention of alternatives such as list_news (to find an ID) or get_message (for other message types). Retrieval by ID is only implied by the verb 'Get'.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds the useful fact that results span three distinct content types, but says nothing about ordering, per-source vs. total limits, or how much is returned per source.

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 tight sentence, front-loaded with the 'What's new' framing and immediately followed by the concrete contents. The only minor redundancy is restating the title's phrase 'What's new'.

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

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

With an output schema present, return values need no explanation, and the tool is low-complexity with one optional parameter. What remains missing is the semantics of the limit parameter, which neither the schema nor the description supplies.

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% for the single 'limit' parameter, so the schema supplies no meaning beyond type and bounds (1-50, default 5). The description's 'the latest' hints at truncation but never clarifies whether limit applies per content type or across the combined result set, which is exactly the ambiguity an agent needs resolved.

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 resource and enumerates the three content sources it aggregates (inbox messages, news posts, recently added documents), so the agent understands it is an aggregate 'what's new' view rather than a single-entity fetch. It does not, however, explicitly contrast itself with the sibling list_messages, list_news, or recent_documents, leaving some ambiguity about when the aggregate is preferable.

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 explicit when-to-use statement, no exclusions, and no named alternative among the many siblings. An agent must infer from the phrase 'What's new' that this is a dashboard-style summary rather than a filtered list call.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description does add one useful behavioral fact beyond them: the listing is scoped to a single folder (non-recursive), but it says nothing about pagination, result limits, or permission requirements for the archive.

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

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

A single front-loaded sentence with zero filler, which is appropriate for a simple listing tool. It is arguably over-lean given the 50% schema coverage, but that gap is penalized elsewhere rather than here.

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?

Because an output schema exists, return values need not be described, and annotations carry the safety profile. Still, for a browsing tool in a crowded sibling set, the description lacks the folder-scope mechanics (root vs subfolder behavior, ordering effects) and any routing versus find_documents.

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 only 50%: folder_id is documented in the schema ('omit for the archive root'), but 'order' is an undocumented enum whose values 'date' and 'created' are ambiguous without explanation. The description adds no parameter meaning to compensate for that 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?

States a specific verb (list) and resource (folders and files) and adds scope (one folder of the document archive), which is more precise than the title 'Browse document archive'. However, it never distinguishes itself from siblings like find_documents or recent_documents, which overlap in intent.

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?

Usage is only implied: 'in one folder of the document archive' hints that you navigate folder-by-folder rather than search globally, but there is no explicit when-to-use guidance and no mention of when find_documents or recent_documents would be preferable.

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, destructiveHint=false and openWorldHint, so the safety and idempotency profile is fully covered by structured data. The description's only added behavioral context is the nature of the content (house rules, contacts, practical info), which is mild but useful; it says nothing about ordering, pagination or volume.

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

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

A single front-loaded sentence with no filler; the resource and its contents are stated immediately and every clause earns its place.

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

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

With an output schema present, the description needn't explain return values, and zero parameters means no input documentation is required. The one missing element is the relationship to the get_info_page sibling, which is the only thing an agent still has to guess.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The parenthetical list of page types does help the agent understand what entities the result set contains, which is a slight bonus.

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

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

The description gives a specific verb (List) and resource (the association's information pages) and even parenthetically enumerates what those pages contain (house rules, contacts, practical info). It is clear on its own, but it does not differentiate itself from the sibling get_info_page, which an agent could easily confuse with this 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?

Usage is only implied by the verb 'List' – there is no explicit statement of when to call this versus the singular get_info_page, and no note that the returned pages are the input to get_info_page. For a zero-parameter enumeration tool this is minimally adequate, but the sibling relationship is left for the agent to infer.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description contributes one genuine behavioral fact beyond that: results are returned 'newest first'. It says nothing about pagination limits or result volume.

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 compact sentence with the scoping constraint and sort order front-loaded and no filler. It is efficient, though the terseness borders on under-specification for a tool with three parameters.

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

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

An output schema exists, so return values need not be described, and annotations cover safety; the description still omits what a 'thread' contains and whether search spans folders or is scoped to the selected folder. Adequate but with clear gaps for an open-world listing 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 67% (page and search are documented, folder is not), which is below the high-coverage threshold where a baseline of 3 would apply. The description adds no information about any of the three parameters, so it does not compensate for the 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?

States a specific verb and resource ('List message threads'), plus scope ('in a folder') and ordering ('newest first'). It is clearly distinguishable from the singular sibling get_message, though it never names a sibling explicitly to reinforce that distinction.

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 choose this tool over get_message, find_documents, or a search-oriented alternative, and no stated exclusions or prerequisites. Usage is only weakly implied by the word '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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description contributes the useful 'newest first' sort guarantee, but says nothing about page size, pagination limits, or what the search parameter matches.

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

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

A single front-loaded sentence with the resource and the sort order; nothing is padded or redundant.

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

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

An output schema exists, so return values need no explanation, and the read-only annotations cover safety. Still missing for a paginated, searchable list tool is any indication of result volume, page size, or search semantics, which leaves the agent guessing about how to iterate results.

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

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

Schema description coverage is 0% and the description never mentions the two parameters, so neither 'page' nor 'search' gets meaning beyond its bare name and default. The names are somewhat self-explanatory, but the description adds no semantics such as page size, search scope, or behavior when search is null.

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 (List) and resource (the association's news posts) and adds ordering (newest first), so the agent knows exactly what is returned. It does not explicitly differentiate from the sibling get_news, leaving the list-vs-single-item distinction to inference from the 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?

There is no when-to-use guidance at all: nothing about when to prefer this over get_news, when to page through results, or what the search parameter is for. The only signal is the imperative 'List', which the agent must interpret unaided.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's job is lighter. It still adds real behavioral context by disclosing graceful degradation: clients without MCP Apps support receive the same overview as get_overview. No auth, rate-limit, or side-effect detail beyond that.

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

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

Two sentences, zero filler, with the primary action front-loaded and the fallback behavior appended. Every clause 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, and annotations carry the safety profile. The description covers what opens and the fallback path; the only mild gap is that it does not clarify what the agent should do differently after opening the browser versus calling the underlying list 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% and the single 'view' parameter already has an enum plus a description, so the baseline is 3. The description's enumeration of tabs (messages, news, documents, info pages) loosely mirrors the enum values but adds no naming, default, or interaction detail beyond the schema.

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

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

States a specific verb and resource ('Open an interactive ProBo browser in the chat') and enumerates the content domains it surfaces (messages, news, documents, info pages), which maps directly onto the sibling tools for those resources. It also names the sibling it degrades to, so an agent can distinguish it from get_overview.

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 second sentence implies a routing rule — clients lacking MCP Apps support effectively get get_overview — but never states explicitly when an agent should prefer this interactive browser over list_messages, get_overview, or the other listing siblings. Usage is implied rather than declared, and no exclusions are given.

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 readOnly, idempotent, non-destructive, and openWorld, so the safety profile is covered. The description adds the supported file types (PDF, plain-text), which is useful, but says nothing about size limits, failure modes for unsupported types, or authentication.

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 tight sentence with the resource and supported formats front-loaded and zero wasted words.

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

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

For a simple one-parameter read tool with an output schema and full annotation coverage, the return-value contract is already handled structurally. The main gap is routing guidance among the many read/list/search siblings, but nothing required to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema, including that it can be an id or an attachment path. The description adds no parameter detail, so the baseline 3 is appropriate.

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

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

States a specific verb (fetch/read) and resource (document text), and scopes it to PDF and plain-text files. It implicitly separates itself from download_document by returning text rather than a file, but never names the sibling, so an agent must infer the distinction.

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 and no reference to alternatives like download_document or find_documents, despite several plausibly overlapping siblings. The agent is left to guess whether to read, download, 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds a genuine behavioral trait beyond them — that results are capped ('ProBo shows only a handful') — though it never states the actual limit or ordering guarantees for a 'most recent' list.

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 what it does and then the alternative, with zero filler. Every sentence earns its place.

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

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

An output schema exists, so return values need not be explained. Scope, result-cardinality caveat, and the alternative route are all present for a simple read-only list 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?

The tool takes zero parameters and the schema is fully described, so there is nothing for the description to disambiguate at the parameter level. Baseline 4 for a parameterless tool.

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

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

States a specific verb and resource ('List the documents most recently added to the archive') with a scope qualifier, and explicitly contrasts itself with the sibling find_documents. An agent can pick between the two without opening either schema.

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

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

Gives an explicit when-not condition plus the named alternative: for 'everything added in the last N days', use find_documents instead. That is exactly the routing information a sibling-heavy tool list needs.

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