Show Link

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

The description reinforces the read-only nature ('Read-only — it changes nothing in Procore') and adds valuable error semantics (401/403/404), which go beyond annotations. It also discloses the return format. No contradiction with annotations is present.

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

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

The description is front-loaded with the core purpose and each sentence contributes useful information (usage, id resolution, return type, error handling, required params, endpoint). It is slightly dense but not wasteful; the length is justified by the tool's behavioral nuances.

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 tool with two parameters and no output schema, the description covers the essential context: when to use, how to resolve the id, return shape, failure modes, required parameters, and the underlying API endpoint. It does not enumerate the returned fields, but 'full field set' reasonably compensates for the absence of an output 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 coverage is 100%, with both parameters already described meaningfully in the schema. The description repeats the required parameters and adds the contextual note that 'id must identify an existing parent record,' but this does not significantly extend the schema's 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 opens with a specific verb+resource: 'Show detailed information for a specific Project Home Link.' It clearly differentiates from list tools by stating 'when you already know which link you want and need its full field set.' It also specifies the return type: 'Returns a single JSON object describing the link.'

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 when-to-use signal ('Use this when you already know which link you want') and instructs resolving the id via the matching list tool first. However, it does not explicitly state when *not* to use this tool (e.g., for browsing or listing links), so it falls short of a fully explicit exclusion.

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