remnus

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

Beyond the read-only annotation, the description discloses important behavior: returned changes include deletions, results are oldest-first, the cursor must be persisted, and an entry in the cursor's own second may reappear, requiring deduplication by id. This is valuable operational context not otherwise visible.

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 dense sentences carry the full story: what it returns, how to use it correctly, and the one caveat to handle. There is no filler or repetition of schema text.

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 output schema exists and the annotations cover safety, the description supplies all essential procedural details: cursor chaining, bootstrapping, scope, ordering, and deduplication. An agent can call and paginate this tool correctly from the description alone.

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 schema already documents since and cursor, and the description adds useful context about cursor provenance (digest/map header or previous nextCursor) and bootstrap semantics. The limit parameter remains undocumented in the description, but its default and self-explanatory name reduce 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?

The description states a specific verb and resource: 'Everything created, updated or deleted since a cursor... or an ISO time,' and enumerates the covered item types (pages, databases, rows, deletions) and ordering (oldest first). This clearly distinguishes it from sibling read tools like get_page or get_pages.

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

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

It gives explicit usage direction: omit both parameters to bootstrap, always retain nextCursor for the next call, and use this tool to catch up 'instead of re-reading the tree.' This tells the agent exactly when and how to invoke it iteratively.

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 concrete return-content boundaries (no rows) and a recommended precondition that goes beyond the readOnlyHint. It is consistent with the readOnlyHint and openWorldHint false, and no contradictions.

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

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

One sentence with dense, front-loaded content: return contents first, then the use trigger. No filler.

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

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

For a simple one-parameter read-only tool with an output schema and readOnlyHint, the description supplies the key boundary (schema vs rows) and the intended call timing. Nothing essential 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?

There is no parameter explanation in the description, and schema coverage is 0%, so the description was expected to compensate. The single databaseId is self-explanatory from its name, but the description adds no format, origin, or usage detail beyond the schema.

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

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

The description names the resource ('a database') and a specific verb ('get'), enumerates the exact contents (columns id/name/type/options and saved views), and explicitly excludes rows. This lets an agent distinguish it from row-returning siblings like query_database.

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

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

It states a clear trigger: 'Check it before writing rows or changing views.' It does not explicitly name sibling alternatives or state when not to use it, but the 'without rows' caveat implies row queries belong elsewhere.

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, so the description doesn't need to restate safety. It goes beyond by explaining the type auto-detection, the dashboard spec behavior, and the definition of outline mode. This adds helpful behavioral context.

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

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

The description is concise and front-loads the primary function. The mode explanation is efficiently included, and the guidance on using outline as a skim is optimized for agent decision-making.

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 output schema exists, the description needn't explain return values. It covers the key nuances (type auto-detection, dashboard behavior, outline mode) that an agent needs to invoke correctly. It doesn't mention pagination or rate limits, but these are minor given the tool's simplicity and read-only nature.

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 covers all three parameters with descriptions for pageId and includeComments, and mode has an enum. The description clarifies the 'outline' option and what it returns, adding some value beyond the schema. However, most parameter semantics are already in the schema, so a 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 clearly states the tool reads various resource types by id, auto-detects type, and returns a dashboard as its block spec. It names specific resources (page, database row, dashboard) and distinguishes from siblings that list or search.

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

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

Provides clear guidance on when to use 'outline' mode as a cheap skim before a full read, and mentions the map shows body sizes. It doesn't explicitly exclude alternatives like query_database or get_pages, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to repeat that. It adds valuable behavioral detail: 'A bad id fails only its own entry — check each "ok"', which discloses partial failure semantics not present in annotations. No contradiction.

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 with no waste. The core purpose is front-loaded, followed by the alternative and a failure-behavior note. 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?

Given the tool's complexity (batch read, partial failure) and the presence of an output schema, the description covers the essential points: what it does, when to use an alternative, and failure handling. The 50-item limit is in the schema, so no need to repeat. Nothing critical is missing.

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

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

Schema description coverage is 50% (mode has a description, pageIds does not). The description clarifies that pageIds are ids and can be mixed, adding context beyond the schema. However, it does not elaborate on the mode parameter or its effect, leaving some semantics to the schema reference ('As in get_page').

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

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

The description states a specific action ('Read several pages/rows by id in one call') with a clear resource and scope. It distinguishes itself from get_page (single) and query_database (filtered) by emphasizing batch retrieval for a known, mixed id list.

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

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

Explicitly names the alternative (query_database) and gives the condition for when to use it instead ('For rows of one database use query_database with filters/fields instead: one query, not N lookups'). This provides clear when-to-use and when-not-to-use 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 and openWorldHint=false, so the safety profile is covered. The description adds valuable behavioral context by stating output is 'titles and ids only' and that the resource mode returns the pages resting on that file, which goes beyond the annotations.

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

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

Two compact sentences convey the purpose, output limitation, both input modes, and a caution. Every clause earns its place, and the main idea is front-loaded.

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 read-only annotations, the description covers the essential behavior, input modes, and result scope. There are no significant gaps an agent would need to invoke the tool correctly.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds meaning by explaining the 'instead' relationship between pageId and resource, and by clarifying what each mode returns and the context for using them. This improves on the bare schema descriptions.

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

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

The description clearly states the tool retrieves a page's related neighborhood (parent, children, links, backlinks, siblings, repo files) and explicitly limits results to titles and ids. It also distinguishes the two input modes (pageId vs resource), making its purpose specific and differentiated from sibling tools like get_page or get_pages.

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

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

The description gives clear conditional guidance: use pageId for a page's neighborhood, or use resource to find pages resting on a file, with the practical warning to read before changing the file. It does not explicitly name sibling alternatives or when-not-to-use conditions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context by framing the tool as a diagnostic for auth/permission failures. It does not, however, resolve whether 'renewal' means the call reports renewal state or performs a renewal, which is the one behavior an agent might act on.

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. The return-value list is front-loaded and the call conditions follow immediately, so the agent gets scope and trigger in one read.

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, making the description's field list a bonus rather than a requirement. The only residual gap is the ambiguity of 'renewal' — an agent cannot tell from the text whether calling this can refresh an expired token or only reports on it.

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 is 4. The description adds no parameter detail, but none is needed.

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 resource (this connection's state) and enumerates exactly what is returned: workspace, scope, token expiry and renewal. That field list distinguishes it cleanly from the data-oriented siblings (query_database, get_pages, list_members), none of which report connection health.

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 three concrete, observable triggers: Remnus tools missing, a write refused, or a 401 failure. An agent that hits any of these symptoms knows immediately to call this tool rather than guessing at recovery options, which is stronger routing guidance than most sibling definitions provide.

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 and openWorldHint=false, covering the safety profile. The description adds minor context by naming the returned fields (roles and join dates), but does not discuss pagination, workspace scope, output size, or any other behavioral trait. This is adequate but not rich.

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

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

The description is a single compact sentence that conveys resource and content without wasted words. It is appropriately minimal for a no-parameter list operation and front-loads the essential information.

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

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

For a simple, no-parameter, read-only listing with an output schema available, the description covers the core information an agent needs: what is being listed and what fields are included. It is slightly incomplete only in that it does not state scope or when to choose this over a sibling 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 has zero parameters, so the description cannot and need not add parameter-level meaning. The schema coverage is effectively complete because there is nothing to document. The baseline of 4 for a no-parameter tool 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 names the resource ('Workspace members') and the key returned attributes ('roles and join dates'), making the tool's purpose immediately understandable. It lacks an explicit verb and does not explicitly contrast against siblings like list_workspace or search_workspace, so it stops short of a 5.

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

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

No guidance is given for when to use list_members versus alternatives such as search_workspace or list_workspace. There is no mention of intended use cases, exclusions, or conditions that would route an agent to a 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 and openWorldHint=false, covering the safety profile. The description adds behavioral context by noting that results are paginated and can be scoped under one parent, but it does not go deeper into cursor mechanics, limits, or ordering. This meets the baseline given the annotation coverage.

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

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

Two short sentences with no filler. The main capability is front-loaded, pagination and parent scoping are included, and the cheaper alternative is appended without disrupting the primary message.

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-only listing tool with three optional parameters and an output schema, the description covers what is listed, optional scoping, pagination, and a cost-saving alternative. Nothing essential is missing for an agent to decide whether to call it.

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 67%, with parentId and cursor already documented. The description reinforces that parentId is optional ('optionally under one parent') and that pagination exists, but it does not illuminate the limit parameter or cursor semantics beyond what the schema provides. It is adequate but not additive enough to score higher.

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 ('List'), a specific resource ('sidebar items'), and the item kinds ('pages and databases'), and notes the optional parent scoping. This clearly distinguishes it from siblings like get_pages or search_workspace by anchoring the operation to the workspace sidebar.

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 explicitly mentions a cheaper alternative ('workspace digest/map') and the condition under which it is preferable ('For orientation'). It does not enumerate exclusions versus every sibling, but the main alternative guidance is clear and actionable.

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=true, and the description adds meaningful non-obvious behavior: lexical ranking, preference for human-reviewed knowledge, penalization of stale/deprecated concepts, and inclusion of link neighbors. This goes beyond the annotation surface and explains selection logic without contradicting the read-only hint.

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 dense sentences with no filler. The behavioral core is front-loaded, and the usage guidance is delivered in a small, focused second sentence.

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 input schema, output schema, and annotations, the description covers purpose, selection behavior, usage timing, and alternatives. An agent has enough to decide when to invoke it and roughly what to expect without missing critical operational context.

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 67%, so the schema does substantial work, but the description adds semantic color: 'lexical rank' clarifies how task/keywords drive relevance, 'human-reviewed knowledge preferred' maps to trustPolicy, and 'top hits' link neighbors' explains includeRelated. Only maxConcepts lacks any meaningful description, so the description partially compensates for the uncovered parameter.

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

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

The description uses a specific verb ('Build') and resource ('task-specific, token-budgeted context pack') and clearly differentiates the tool from siblings like search_workspace and get_page by describing a composite, page-synthesizing operation. This is immediately distinct from simple retrieval tools.

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

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

The description explicitly states when to use it: 'before multi-page product or coding work' and contrasts it with 'instead of many search/get_page calls'. This gives an agent direct routing guidance with a concrete alternative.

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, so the safety profile is covered. The description adds context by noting the log is workspace-scoped and filterable by tool, status, and date range, which is useful but not deeply behavioral. 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 a single, front-loaded sentence that communicates the resource scope and key filtering capabilities without excess. Every part adds useful information.

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

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

The description is sufficient for selecting and invoking this low-complexity tool: it names the workspace scope and filter dimensions, and the output schema and input schema cover the remaining details. Limit is not mentioned, but its default and role are apparent from 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 60%, so the schema carries much of the parameter explanation. The description adds a helpful mapping by naming 'tool, status and date range,' aligning with tool, status, to, and from, but it does not clarify limit or provide deeper parameter semantics.

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

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

The description clearly identifies the resource as the 'Agent activity log for this workspace' and conveys that it is queryable via filtering. It does not explicitly contrast with sibling tools, but the subject matter is distinct enough from query_database and search_workspace to be understood.

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: use it when you need an agent activity log for the workspace. It mentions filter dimensions but provides no explicit guidance on when to prefer an alternative tool or when not to use 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 mark it read-only. The description adds meaningful behavioral context: pagination, that row bodies are omitted unless 'content' is in fields, and that using filters/fields is cheaper on wide tables. These go beyond the annotations and help an agent predict behavior and resource usage.

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 with no fluff. The first sentence states the core function and pagination; the second delivers actionable guidance on filters and fields. It is front-loaded and every word contributes.

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 complexity (5 params, nested filters, output schema), the description covers the key behaviors: returns rows and schema, pagination, filtering, projection, content inclusion, and cost implication. It does not detail cursor usage, but the schema and output schema likely fill that gap. It is complete enough for an agent to call it correctly.

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

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

The schema covers about 60% of parameters (cursor, fields, filters have descriptions). The description reinforces the purpose of filters and fields, and explains the special 'content' value for fields. It does not add detail for limit or databaseId, but the moderate schema coverage means the description partially compensates without being fully comprehensive.

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: 'Rows (and the matching schema) of a database, paginated.' It clearly identifies the tool's function and distinguishes it from schema-only or page-oriented siblings, though it does not explicitly name any sibling. The purpose is clear but could be sharper about when this tool is the right choice over alternatives.

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 usage guidance: 'Use filters to narrow and fields to project only the columns you need — much cheaper on wide tables.' This implies when to use it (for querying with filtering/projection) and hints at cost. However, it does not explicitly say when not to use it or mention alternatives like get_database_schema or get_pages, leaving the choice partly to inference.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to state read-only nature. It adds valuable behavioral details: case- and accent-insensitivity and ordering by best matches. These go beyond the schema and annotations, though it does not mention pagination or output structure (covered by output 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?

Two sentences, front-loaded with the main purpose and usage condition, no fluff or redundancy. Every word contributes to understanding the tool.

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

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

The tool is simple with only 2 parameters and an output schema, so the description covers the core purpose and usage well. However, the missing explanation of 'limit' is a notable gap, though minor given the schema provides a default and the output schema handles return details.

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 implicitly covers 'query' by describing text search, but the 'limit' parameter is entirely absent. The description does not explain what limit controls or its default behavior, leaving the agent to infer from the schema alone, which is inadequate.

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 function: case- and accent-insensitive search over titles and bodies of pages, databases, and rows, with best matches first. It names specific resources and a specific verb, distinguishing it from siblings like get_page or list_workspace by its search semantics.

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

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

The description gives a clear usage condition: 'Use it to locate an item by text when the workspace map does not already give you its id.' This implies when not to use it (when you have the id) and provides context for when search is appropriate, though it does not explicitly name an alternative tool.

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